Searching within vRealize Automation – Part 1 - Orchestrator

I was recently engaged with a customer needing to execute some very particular manipulations of their provisioned virtual machines in their nascent vRealize Automation environment.  I learned a few things about using search functions in both vRealize Orchestrator and the vRealize Automation REST API, and I figured it was worth sharing here.

vRealize Orchestrator

The requirement for this part was to use vRealize Orchestrator to change properties of a specific type of vRA-provisioned machine.  This entailed finding all managed virtual machines that lived on a certain cluster within vCenter, and then filtering those machines by a further custom property that was being used.

It tuned out to be a bad idea to use vRealize Orchestrator to do all the grabbing and manual sorting, iterating over scripts and actions to gradually reduce all machines down to the required subset.  It was taking ages, and it was REALLY annoying to have to wait for so long before finding out I hadn’t quite nailed the search anyway!  So I turned to the Model Manager function within the vRA IaaS component.  This is one of the services that runs on Windows servers in the solution, and manages the data model quite directly.

Cluster search

I used a little bit of cheeky searching to discover the right “entity sets” and fields I needed to utilize for the search.  I needed to find the UUID of the target cluster first, taking the “cluster path” that was derived from vCenter’s API structure.  I handled the search as per the below code snippet.

var modelName = 'ManagementModelEntities.svc';
var entitySetName = 'Hosts';
var filter = "HostUniqueID eq '" + clusterPath + "'";
var orderBy = null;
var top = 1;
var skip = 0;
var headers = null;
var select = null;
var entities = vCACEntityManager.readModelEntitiesBySystemQuery(host.id,     modelName, entitySetName, filter, orderBy, select, top, skip, headers);

The important parts to point out are:

• modelName is indicating the standard entity model.  There is a special one for AWS, for example, if I wanted to search on that instead.
• entitySetName is “Hosts” in the first search, which is the host or cluster running a given virtual machine.  If you are running clusters, then the cluster is stored as the “host”, rather than a specific runtime host.
• filter is the magic part.  It turns out that this complies with OData syntax, which you can read about here ().  In my case, the query was for a cluster path, but this is where you need to engage your brain to determine was to search for.
• orderBy, top, skip, headers and select are all modifiers for what gets returned from the search result set and how.  I will come back to these in the follow up blog article where I search in the vRA REST API.
• vCACEntityManager is the object that executes the search, and this invocation method is the same across all my queries – just varying a couple of parameters.

Virtual Machine search
In my use case, I then wanted to find the virtual machines within the matching cluster, which was similar to above, but I used a new entitySet and filter.

var entitySetName = 'VirtualMachineProperties';
var filter = "PropertyName eq '" + propertyName + "' and PropertyValue eq     '" + propertyValue + "'";

Properties search

And the final search was to find all virtual machines with a given property – a custom property in my case.

var entitySetName = 'VirtualMachineProperties';
var filter = "PropertyName eq '" + propertyName + "' and PropertyValue eq     '" + propertyValue + "'";

End result
At the end of these searches, I had two arrays of virtual machine objects.  Merging these arrays in vRO was a piece of regular Javascript, looping over the data set looking for common elements.

See below for the visual representation of the two searches and final merge.

(Download the vRO actions here, if you like.)

In the next article, I will show a different search use case, where I needed to filter a specific VM from the vRA API.