Plug-in Generator v2 advanced techniques
In previous tutorials we created inventory object types, their children objects, workflows to operate these that we packaged for our end users.
In this tutorial we are going to create an orchestrator plug-in to list vCO / vRO workflows ! You may wonder why doing so ?
This is a good use case for leveraging some of the more advanced features of the plug-in generator v2 to handle complex REST APIs and improving performance when needed.
Prerequisites
- vCO 5.5.1 build 1617131 (vCO 5.5 U1 released with vSphere 5.5 U1) or greater.
- DynamicTypes plug-in build 166032 or later
- Plug-in generator v2 package installed (make sure you get the latest version since it is updated often)
Create a plug-in
Right click on the inventory “Type hierarchy” / run Plugin gen -1- Create new plug-in
Name your plug-in and select an icon (any of your choice if you did not bother importing the multi node plug-in icons).
Submit / Run in background Hit the F5 key to refresh the inventory and see your vCO namespace.
Add a host
We need a vCO host to interact with.
Right click on the vCO namespace / run the workflow “Plugin gen -2- Add new host:
Let the selected namespace.
Enter a name for the vCO server you are going to use and its URL (note that I used the API URL)
Select basic authentication
Enter a vCO admin credential
Submit.
Create a workflow type
Right click on the vCOHost type / run the workflow “Plugin gen -3- Create a type
Enter the parameters:
- Type name : workflow (no upper case)
- Folder name : Workflows
Click next. It is going to show the host you have defined.
Click next. Choose not to provide a findById and findAll URL
Click next. Since we will need to know the URL to get the workflows let’s check the built in API docs. Enter https://yourvCOServer:8281/vco/api/docs and browse to the workflow service.
The URL is /workflows. Enter it in the findRelation URL input
Hit tab - After a few seconds the response should be filled. Copy and paste it to a JSON viewer (I.E http://jsonviewer.stack.hu)
The array of workflow objects is under link.
Click next. Set the objects selector to .link, hit tab
Copy the objects preview. Click next.
There is an error as it seems the properties that were collected are missing the required id and name properties. Click on the properties selectors input.
Unfortunately the properties there does not seem to match workflow properties such as id, name. description, version. Paste the JSON you just copied to the JSON viewer.
With unfolding the attributes property you can see that each of them has a name and a value. The issue with having such objects attributes instead of regular object properties is that you cannot just define id as being .id since there is no id property. You may think a few seconds that you can always use .attributes.1.value with assuming .1 will always contain the id but this may not always be the case, at least the API documentation does not guarantee it. What you need is to get the attribute value for the attribute having a name equal to “id”.
With the plug-in generator V1 there was no way to write an expression for doing so but the V2 now include JSONSelect. To understand how to write these queries you can read JSONSelect documentation. To test your expressions called selectors you can use online JSONSelect expression testers such as http://jsonselect.curiousconcept.com
Open it in a web browser, paste the JSON you copied and test your expressions to get the name, id and other values.
If you did not find on your own to get the id the expression is .name:val(“id”) ~ .value Basically it means that we look for the .value property for a .name sibling set with a value of “id”.
And it returns 5 workflow ids which is the sample I was working on (Preview size was set to 5 to avoid working with the full set of workflows which in my case are 1036).
You can now remove the existing properties that are not useful and add the id property.
Repeat the last operation for name, description, version
If you got your expression right the properties preview should now be populated
Click next.
The properties are listing description and version (id and name being mandatory, they are not listed here). Submit.
Unfold the inventory. You should see something similar as below.
You may have noticed that during the creation of the object and unfolding the inventory is taking a long time. We will now see what we can do to make the plug-in be faster. Using JSON Select is a code free way of implementing gathering objects properties of complex objects but while powerful making a JSON Select query per object properties * total objects number can be too long. Also in some cases getting some properties may require transforming the properties values with doing some parsing or even making new REST calls to get linked objects.
Testing and improving performance
Let’s test getting all the Workflows objects.
Right click on the workflow type / Run the “Find all objects for type” workflow.
In my case it took 1 minute 39 seconds to get all workflows. While this is not a disaster it is not offering a very good end user experience when unfolding the inventory or listing all the elements in a workflow input.
Right click again on the workflow type and run the “Plugin gen - Define a get properties action”
Fill in the parameters
- method : findAll
- operationAction : getWorkflowsProperties (and do not set getWorkflowProperties - singular workflow)
Submit.
Right click again on the workflow type and run the “Plugin gen - Define a get properties action” - Show workflow run / General tab.
We are now down to 22 seconds which is a lot better for end users.
The getWorkflowsProperties is included in the plug-in generator package as an example on how to get object properties from the JSON returned by the HTTP query
It takes a jsonString as input, use JSON.parse to transform it in a JavaScript object, get the link property as we did previously and add each attribute name and value to a Properties() object and add it into an array of object properties it returns.
Here it was pretty straight forward. In other cases you may have to add more logic to get the properties, for example do additional HTTP GET operations to get linked properties. If you need so you can add a second input to the action that will be set with the REST Host this object is from.
If needed / wanted you can use actions for all three methods (findRelation, findAll, findById - in this case return a single Properties).
If the action is defined for an object and a method it will always be used before the configured selectors.
You may wonder how the cache timeout setting available during the type creation is affecting the performances. By default it was set to 30 seconds.
Change the cache setting by editing the cache configuration element. Right click / edit.
Set a very high number here to make sure it exceed the time in second since the last time you ran the workflow to get all the workflow objects.
Right click again on the workflow type and run the “Plugin gen - Define a get properties action” - Show workflow run / General tab.
We are now down to 3 seconds to get hundreds to thousands of objects.
While making the cache timeout longer may sound like a good idea to increase a lot the performance it has a drawback : if you set a 1 hour timeout your inventory may be different from the remote system if change happened in the last hour. Using very small timeout will give you a very accurate inventory but then vCO will send a LOT of queries. For example vCO does a findById between each workflow step involving a given object. If you did not define a findById URL it will call the findRelation one that will pull a lot of objects and get their properties. If you do so in a workflow loop it is going to slow down vCO, the remote system and eventually cause the remote system to reject your queries.
This is why the timeout value should be adjusted to a value that will likely avoid repeating the queries returning the same results. The workflows operating the inventory objects should handle the case where there is a discrepancy between the inventory and the remote system (For example deleting an object that has been deleted by another process a few seconds before).
Conclusion
In this tutorial we could get the (complex) workflow object properties leveraging JSONSelect and tested the performance improvements using an action.
JSONSelect gives more flexibility to gather objects properties and the action allows for even more flexibility and for much better performance.
