Create a plug-in for a REST based web service in minutes - part 1
In a previous article I have explained how Dynamic Types work and how these are very useful to create a vCO / vRO plugin that will enable the XaaS capabilitites of vCAC / vRA.
Then explained how to build your own twitter plug-in using the plug-in generator package. I have now extended the capabilities of the plug-in generator and will attempt to demonstrate these in this new series of articles. This article use NSX as the orchestrated endpoint but following the explanation included on this tutorial you should be able to get it to work with many REST web service.
Pre- requisites
- The system to be Orchestrated via the plug-in must have a REST based interface that works with the REST plug-in.
- Make sure that you have the minimum version of the DynamicTypes plug-in and of vCO as specified on VMware communities.
- Import the v2 package to your vCO client.
- Import icons for the inventory objects you will want to create as resource elements. In case you do not find these you will still be able to use some defaults icons but having nice icons makes things so much prettier.If you need the NSX icons I have posted these on communities.
Warning : Not a single line of code is required for generating a plug-in when using the plug-in generator - if you landed here looking for complex development tasks taking several days of work and requiring a complex development environment you will be frustrated by the efficiency and simplicity of this tutorial !
To create a new plug-in, go in the inventory view, unfold Dynamic Types / Type Hierarchy. Right click on Type hierarchy / run the workflow Plug-in Gen - Create new plug-in.
Enter a plug-in name and select an icon.
Submit. If the “Running workflow” windows stays open click on : “Run in background”
To create the inventory objects we first need to add a new host. Right click on the newly created namespace and run the “Plugin gen - Add new host” workflow
The next screens are exactly the same as the library workflow to add a REST host. Provide a name and URL.
On the next screens you will have to enter proxy settings if required and authentication types and credentials.
Once you have submitted you can check that you have a new host in the HTTP-REST inventory. You can even right click / add a REST operation and then invoke it to make sure everything work as expected.
We are now ready to create a type. Unfold the Type Hierarchy and right click on the plug-in namespace host type / run the workflow Plugin gen - Create a type
After the presentation finish loading (this can be from 20 s to 1 min).
- Enter a type name. This should be all lower case, singular and alpha only.
- Select an icon for the type (If you do not have any specific you can use the “item-16x16”)
- Choose a Folder name. This is going to be the name of the folder showing in the inventory. You can use Upper case for the first letter, plural and spaces if needed.
- By default the same icon as for the type will be used for the folder. If you decide otherwise the default icon will be a folder that you may change to a more specific folder icon.
- Object cache is the time for which this object type will stay in the cache. This means that once the plug-in get an object from the remote system it will store the result for this time and not request it again. This will improve the performance by a lot in the vCO UI but also in the workflows manipulating the objects, particularly with array of objects or if using loops within the workflow. A lower value will maintain the inventory more current against any changes not done by vCO but also slow down performance. A too high value would mean a not so current inventory which may cause errors in a workflow if for example there is an attempt to modify an object that was deleted outside of vCO.
On the next screen you can choose the host that will be used interactively to create the object. If you created a single host it should be set by default. Click next.
If you are in a hurry just click next.
The relation types screen define how many URL you can provide to get the object.
It is now time to read your endpoint API guide and search how to get the object.
In my case the /api/4.0/edges URL gets all the edges objects and the /api/4.0/edges/{edgeId} URL get a single edge.
The findRelation URL will get all the objects under the Edges folder. Since this is a 1rst child of the host these will be all the edges using the /api/4.0/edges URL. The findRelation URL is always mandatory.
In a similar way the findAll URL will be using the /api/4.0/edges URL. FindAll is used to list all objects when selecting one for a workflow input.
The findById URL needs to be specified with a parameter in curly braces {}.
If you do not provide a findAll URL findRelation will be used on all the objects that are of the parent type of the object you are looking for.
If you do not provide a findById URL findAll will be used to get all objects and be iterated until finding the one having a matching ID.
To implement quickly a plug-in you can use NOT to use the findById and findAll URL. This will shorten the creation of a single object and avoid the case where the API returns different object properties for the different URLs. Also some APIs do not provide an URL for findAll or findById but only for findRelation. If you have further time to implement, an API that implements the different URLs and returns the same object properties than you should definitely use findById and findAll URLs since this will improve the queries performance a lot.
The version 1 of the plug-in generator required all URL to be filled making impossible to implement objects with API not providing one of these URLs.
On the next screen you will have to set the findRelation properties.
Enter the URL. Likely this will be an object under the host object and the inventory and the URL will be the same as the one to find all objects.
Once you will set the focus on the next input the response should appear. It should be in JSON format. Do not edit the response content. Instead copy and paste the response content, open a web browser and look for a JSON viewer or JSON editor online. I like to use http://jsoniewer.stack.hu. Paste your JSON in the text area and check the viewer.
The “Use action …” is an alternative way to get the object properties requiring you to write an action taking as input a json string and as output an array of properties object. It is used when performance is key or when the object has complex properties requiring that need to be parsed / transformed programmatically. I will cover this case in another article since it is not needed in most cases.
You may wonder what happen if the REST web service send a response in the XML format. The plug-in generator des a request with providing a header requesting for JSON format. This works for example with the NSX API. When this is not supported the plug-in generator use an XML2JSON method included in the REST plug-in to do the conversion.
The JSON viewer will show something like this. Unfold the tree to recognize the different elements.
What you are looking for is the path to the array [] of objects {} that are returned. Some APIs will return the array of objects at the root element while other will have intermediary objects. Once you have identified this path get to the next screen.
The objects selector or object accessor is the path you have identified. If the array of object included child objects enter the path starting with a “.” and separated with “.” as if it was a javascript object. In my case the array of objects is under the path .edgePage.data The preview size limits the number of objects returned in the objects preview. This was designed to avoid to get very large number of objects since it is not needed to identify the properties we will need. After using tab to get from one field to another the objects preview should be populated. if you copy and paste the content to the JSON viewer it should look similar to this:
With the objects selector entered the objects will be found automatically for each request happening. Get on the next screen to define the objects properties selectors.
The list of properties selectors will be set bu default based on the properties that were returned by the objects previously. You have to edit the properties selector to:
- Check that it includes only properties you need.
- Check that it include at least an id and a name properties In my case it is missing the id property. Click on the insert value.
To determine which property can be used as an unique ID for the object look at the object properties in the JSON viewer. In my case this property is objectId so the accessor is .objectId.
Once you accept the change the properties preview should be filled. You can copy and paste the content to a text editor to check the properties are retrieved as expected.
The object properties that are not simple types may not be displayed in a visible form for example it may list [object Object]. Since Dynamic Types only support string properties in the object such properties will be made available in the object in a JSON format. This allows to convert these properties to a javaScript object in a vCO scriptable task using var object = JSON.parse(objectProperty);
If you had selected to provide findById or findAll URL you will have to go through similar steps to provide object and properties accessors. Once done you will be asked if you want to merge or intersect the properties returned by the different URLs. If not you will see the list of object properties. You can submit the workflow and click run in background. You can now check the Type Hierarchy in the inventory.
The type was created under a Folder type created under the host type. Unfold the namespace.
Under the namespace there is your host instance having for child the folder instance having for child the objects instances. Managing multiple hosts is a new feature of the version 2 of the plug-in generator. If you click on one of the object and check the right pane for its properties.
All the properties are listed. As explained above the complex ones are in JSON format. If you look for the id property it will be in the format hostId/objectID so there won’t be any conflict when using more than a single host.
You managed to create your own plug-in object in minutes without typing a single line of code. The next article in the series will walk though creating objects that have for parent another object type different than the host type. If you want to create other objects for an NSX plug-in you can run the Create type workflow using the following parameters:
| Type name | Icon | Folder name | FindRelation URL | Objects selector | Properties |
|---|---|---|---|---|---|
| datacenter | datacenter.png | Datacenters | /api/2.0/vdn/scopes/vdnscope-1 | .clusters | id: .cluster.scope.id name |
| name : .cluster.scope.name | |||||
| edge | edge.png | Edges | /api/4.0/edges | .edgePage.data | |
| securityGroup | securityGroup.png | Security Groups | /api/2.0/services/securitygroup/scope/globalroot-0 | id: .objectId | |
| transportZone | transportZone.png | Transport Zones | /api/2.0/vdn/scopes | .allScopes | |
| securityTag | securityTag.png | Security Tags | /api/2.0/services/securitytags/tag | .tagList | id: .objectId |
| securityPolicy | securityPolicy.png | Security Policies | /api/2.0/services/policy/securitypolicy/all | .policies | id: .objectId |
| virtualWire | virtualWire.png | Virtual Wires | /api/2.0/vdn/virtualwires | .dataPage.data | id: .objectId |
