How to find vCAC entities with the vCAC plug-in for vCO (and how to filter them in scripting)

The vCAC plug-in for vCO provides a scripting utility object called vCACCAFEEntitiesFinder to help to get, find and filter the same lists of objects that you can see in the plug-in inventory. But if that's not enough, you can directly use the different clients also provided by the plug-in and their services (most of them directly exposed from the vCAC CAFE SDK) which usually have search features based on OData and OData-like queries.

How to use the vCACCAFEEntitiesFinder

The methods from the vCACCAFEEntitiesFinder are the ones that the plug-in uses to do its own internal stuff, basically finding objects from the inventory when running workflows (usually by id) and finding objects from the inventory when searching from the workflows presentations (usually by name or description). That's why usually you have the methods:

• vCACCAFEEntitiesFinder.getX(host) - retrieves all the objects of type X from a specific host
• vCACCAFEEntitiesFinder.getX(host, id) - retrieves the object of type X with the specific id found in the specific host
• vCACCAFEEntitiesFinder.findX(host, query) - retrieves all the objects of type X matching the specific query (by name and/or description) found in the specific host

Again, those are the methods that the plug-in internally needs, but the vCACCAFEEntitiesFinder exposes them via scripting in case they can be useful.

The next examples are based on the Catalog Resources entities, but the same principles are applicable to any type of inventory object, and also in most of the cases for any method of any service which accepts as a parameter an object of type Pageable.

How to find catalog resources filtered by name

You have 2 options here:

(I assume that the host scripting object is an input parameter or it's retrieved beforehand)

• With the vCACCAFEEntitiesFinder and the findCatalogResources(host, query) method.

You just have to use the object method with the target host and to pass as a query the name of the catalog resource.

var items = vCACCAFEEntitiesFinder.findCatalogResources(host, "name_of_the_resource_here");

• With the Catalog client and the Consumer Resource service.

You have to get the Consumer Resource service and to invoke the get method passing as a Pageable parameter an instance of, for example, the vCACCAFEPageOdataRequest. In this case you create the vCACCAFEPageOdataRequest object by providing a query (OData query actually) which is build as a single filter of an attribute ("name") matching an specific string (your resource name).

var service = host.createCatalogClient().getCatalogConsumerResourceService();

var filter = new Array();

filter[0] = vCACCAFEFilterParam.equal("name", vCACCAFEFilterParam.string("name_of_the_resource_here"));

var query = vCACCAFEOdataQuery.query().addFilter(filter);

var items = service.getResourcesList(new vCACCAFEPageOdataRequest(query));

How to find catalog resources filtered by owner

In this case it's not possible to use the vCACCAFEEntitiesFinder directly because, again, for now its methods filter only by name/descriptions since it's what the plug-in needs internally. Then, the only option is to use the Consumer Resource service and to build the proper OData query.

var filter = new Array();

filter[0] = vCACCAFEFilterParam.substringOf("owners/ref", vCACCAFEFilterParam.string("user@domain.com"));

var query = vCACCAFEOdataQuery.query().addFilter(filter);

var items = service.getResourcesList(new vCACCAFEPageOdataRequest(query));

The important part here is the "owners/ref", which depends on the internal structure and fields of the catalog resources, but you could get an idea how to compose it since the vCACCAFECatalogResource entity has a property "owners", which is a collection of  vCACCAFECatalogPrincipal entities, and each of those entities has a property "ref", which is a string representation of the user's principal id.

How to find catalog resources filtered by name and owner

In this case you just need to combine the last 2 OData conditions into a single one with the "and" operator.

var conditions = new Array();

conditions[0] = vCACCAFEFilterParam.equal("name", vCACCAFEFilterParam.string("name_of_the_resource_here"));

conditions[1] = vCACCAFEFilterParam.substringOf("owners/ref", vCACCAFEFilterParam.string("user@domain.com"));

var filter = new Array();

filter[0] = vCACCAFEFilterParam.and(conditions);

var query = vCACCAFEOdataQuery.query().addFilter(filter);

var items = service.getResourcesList(new vCACCAFEPageOdataRequest(query));

Other logic operators

Of course, apart from the "and" operator, the typical set of logic operators are available, together with the most common basic types conditions. All of them accessible through the vCACCAFEFilterParam entity, some examples:

• vCACCAFEFilterParam.and(array of conditions)
• vCACCAFEFilterParam.group(array of parameters) - A group represents the "(" ")" so you can modify the default logic operator evaluation order.
• vCACCAFEFilterParam.not(parameter)
• vCACCAFEFilterParam.startsWith(id, string)
• vCACCAFEFilterParam.endsWith(id, string)
• vCACCAFEFilterParam.greaterThan(id, number)
• vCACCAFEFilterParam.lessThan(id, number)
• ...

Conclusion

The plug-in offers different ways to retrieve, filtering or not, all (or most of all) the entities of the vCAC model. Some of those ways are more simple or more flexible than others, but as you see, you can always access through the plug-in to the vCAC REST API to get the items directly from there.