Example Workflows

1. Example: Scripts to Manage Inventory (All Resource Types)

Servers and services are routinely added or removed from a local machine. While discovery scans are scheduled regularly, actually adding or removing that resource within the JBoss ON inventory is all manual — and administrator must actually choose to import the resource.
An administrator can manage the JBoss ON inventory by automatically adding new resources and automatically deleting other ones based on whatever criteria are defined.

1.1. Automatically Import New Resources: autoimport.js

As soon as a resource is discovered it is, technically, already in the JBoss ON inventory. It is included with a status of NEW. That's an in-between state, because JBoss ON is aware that the resource exists, but the resource has not been committed so JBoss ON can't manage it.
A script can be created and run regularly so that any newly-discovered resources can be automatically added to the inventory. This script bases its identification on new resources on the inventory state, so ignored or already imported resources aren't included.
The CLI script runs through three steps:
  • It identifies new resources using the findUncommittedResources() method.
  • It gets those new resources' IDs.
  • It then imports those resources by invoking the discovery system's import operation.
//Usage: autoImport.js
//Description: Imports all auto-discovered inventory into JON
// autoImport.js
rhq.login('rhqadmin', 'rhqadmin');
println("Running autoImport.js");
 
var resources = findUncommittedResources();
var resourceIds = getIds(resources);
DiscoveryBoss.importResources(resourceIds);
 
rhq.logout();
Only one of the operations is already defined in the remote API — importResources. The other two functions — findUncommittedResources and getIds — have to be defined in the script.
Uncommitted (new) resources can be identified through a ResourceCriteria search by adding a search parameter based on the inventory status.
// returns a java.util.List of Resource objects
// that have not yet been committed into inventory
function findUncommittedResources() {
    var criteria = ResourceCriteria();
    criteria.addFilterInventoryStatus(InventoryStatus.NEW);
     
    return ResourceManager.findResourcesByCriteria(criteria);
}
The second function checks that the inventory search actually returned resources and, if so, gets the ID for each resource in the array.
// returns an array of ids for a given list
// of Resource objects. Note the resources argument
// can actually be any Collection that contains
// elements having an id property.
function getIds(resources) {
	var ids = [];

	if (resources.size() > 0) {
		println("Found resources to import: ");
		for (i = 0; i < resources.size(); i++) {
			resource = resources.get(i);
			ids[i] =  resource.id;
			println("  " + resource.name);
		}
	} else {
		println("No resources found awaiting import...");
	}

    return ids;
}

1.2. Simple Inventory Count: inventoryCount.js

Searches are performed using *Criteria classes; for resources, this is ResourceCriteria. A search can be very specific, passing criteria so that it returns only one resource or a small subset of resource. It is also possible to return everything in inventory.
This script runs a search with no specific criteria (ResourceCriteria()), so that every resource matches the search. It then takes the size of the results to produce a simple inventory count.
// inventory.js
rhq.login('rhqadmin', 'rhqadmin');
var resources = ResourceManager.findResourcesByCriteria(ResourceCriteria());
println('There are ' + resources.size() + ' resources in inventory');

// end script

1.3. Uninventory a Resource After an Alert: uninventory.js

Removing a resource from the inventory simply removes it from JBoss ON; the server or application itself remains intact on the local system. (This allows the resource to be re-discovered and re-imported later.)
The alert system can launch CLI scripts in response to a fired alert (covered in "Setting up Monitoring, Alerts, and Operations"). One possible response is to uninventory a resource which is not performing well.
This can be a pretty simple little script. To uninventory the resource, simply use the resource ID which was included in the alert and the uninventoryResource method:
List<Integer> uninventoryResources(Subject subject, int[] resourceIds);
It is possible to combine the uninventory operation with another task. For example, uninventory one resource and automatically create and import another resource to take its place.

Note

This script should be uploaded to the server and then referenced as an alert notification.