Open the API explorer via the Tools menu:
Here the second mentioned option. If you click edit on a scriptable task, the API explorer is shown on the left-hand side of the window:
Now we have access, what can we do with it. Ideally, we need a use case what we would like to achieve. I suggest, that we would like to verify if the NTP server configuration in the ESXi host is correct, and if not, change it. That seems to be a useful example even though, a host is a very complex object in vRO.
Firstly, we need to figure out, how to collect the NTP server configuration from an ESXi host. Therefor we have two options. You can start with the VcHostSystem object in the API explorer or use the MOB. In many cases I prefer using the MOB. Therefor I login an navigate to a host object and use the “config” link.
In the config we find a link named “dateTimeInfo” -> “ntpConfig”. It looks like this:
What we see is a property called server containing an array with the NTP server IP addresses. The TYPE column shows the type of the variable and if it’s a single value or an array. If you see “[]” after the type, then it’s an array. This is a very helpful information, because values inside an array needs to be accessed differently compared to a single value.
That was the MOB approach. Let’s do the same using the API explorer. We expand the VcHostSystem object in the API explorer and click config. The return type is displayed in the lower pane.
Just click the VcHostConfigInfo link. It will forward you to the VcHostConfigInfo scripting object in the API explorer.
Next, click VcHostDateTimeInfo. Same procedure. You will be forwarded and expand the scripting class.
One last step, and we are at the destination.
The same information is displayed. If we access server, an array of string is returned.
Let’s build to code to access that piece of information. Starting to build a workflow, and testing purposes, I create an attribute containing the host. For the future, I recommend adding an input parameter of the type hostSystem as an array.
The code is built on the information we collected using the MOB. The property path shows how to access the configuration of that object and at the end use the property name. The type shows us that we have to deal with an array. Alternatively, you can use the API explorer as well. Just add all the clicks we did using the property names. That leads to the same piece of code.
That’s how the output looks like. We added some formatting to the output. Again, we deal with an array, so we don’t know how many results will be returned.
Awesome. What are the next steps? As I’ve said, we are going to verify the current NTP server configuration against provided values. In our case, we need to ask for the NTP server values. You have several options. Either collect a single string value, an array of strings, multiple single strings. This time, I use the easy way and allow two inputs, using single string values, verifying if they are not empty and, in the end, we need to create an object to send to the host using the appropriate method. Let’s do this.
I add two inputs to my scriptable task, each containing a string with an IP address of an NTP server. Firstly, we need to verify if the configuration is OK, or not. Therefore, we need to add both strings into an array and do some validation testing. This is a very simple script:
If the array length is 0, the configuration is already valid. In our case, that can’t happen, because it’s a testing scenario and based on the inputs we make sure that there is a configuration drift.
Let’s start figuring out, how we can reconfigure the NTP servers. To change the host config, we need to start at the configManager of the host. Again, we use the vRO API explorer to collect the needed information.
I’ll only add a screenshot from the start and not showing each screen. We use the same method like before:
As we navigate down the tree, we find a method to update the host including the needed object. That’s how everything is linked together.
The API explorer clearly show which object is required for the method updateDateTimeConfig. Just click the link forwards you to the scripting class for this specific object type.
As we can see, for the ntpConfig we a a VcHostNtpConfig object and that’s how it looks like:
You can either create the object with the constructor with or without arguments, as you like. In our case, we are just changing the NTP configuration, so I create the object without arguments and add all needed information in subsequent steps. That’s how we work our way up the tree, until we reach the method discovered, requiring the mentioned object.
That’s how the code looks like. I tried using proper variable names to make easier for the audience to follow what I did.
That’s it, afterwards the NTP configuration of the ESXi host changed.
I hope I was able to make it clear, using a simple example, how to use the vRO API explorer to achieve the expected result. At the end of the blog article, you can download the vRO workflow with all the parameters for testing in your home lab. That’s the workflow I’ve used to create the screenshots and all the comments are still in there.
Thanks for reading and have fun playing around the API explorer of vRealize Orchestrator.
