Using vRO REST API to execute a workflow with SDK objects

I was working on something last week which involved vRealize Orchestrator and I wanted to execute a vRO worklfow but rather than using the UI, I wanted to use the vRO REST API. Although there are a couple of blog posts such as this one which demonstrates how to use the vRO REST API, they all use a very simple workflow that only contains string inputs. In my opinion, this does not actually reflect practical workflows which usually contains a mix of strings but also SDK-based objects like vSphere VMs, ESXi hosts, Networks, etc.

It actually took me awhile to wrap my head around how to call these more complex workflows using the vRO REST API and after a ton of trial/error and some help from Kasey Linden and one of the vRO Engineers, I now have a method in which users can follow to identify the required payload for a given vRO workflow when using the vRO REST API. The instructions below is using the latest vRO 8.0.1 release which has a new HMTL5 UI, it has been awhile and I am not sure when this new UI was introduced but the instructions may work for older clients but I would recommend standing up the latest version for developing your automation.

Step 1 - Retrieve the vRO workflow ID by selecting the workflow in the vRO UI. In the example below, my Tag a VM workflow ID is 9d95c7f5-a563-413f-af42-fd7e09275216

Step 2 - Manually execute the workflow once and retrieve the execution ID as highlighted in the screenshot below. In my example, the execution ID is 03ae74a3-2466-4607-aded-b6514f358fae

Step 3 - Next we will use the vRO REST API to retrieve more information about this manual execution which will give us details about the required payload structure. In my example, I am using Postman but you can use any REST Client including cURL. You will need to perform a "GET" on the following URL example https://[VRO-SERVER]:443/vco/api/workflows/[WORKFLOW-ID]/executions/[EXECUTION-ID]

In my example, here is what the URL looks like substituting the required fields: https://vro.cpbu.corp:443/vco/api/workflows/9d95c7f5-a563-413f-af42-fd7e09275216/executions/03ae74a3-2466-4607-aded-b6514f358fae and if the operation was successful, you should see a section called "input-parameters" which describes the exact structure and payload of the input that you had provided when using the vRO UI to execute the workflow.

As you can see, when dealing with SDK objects like VM input within vRO, you need to construct a more complex JSON property which is not very well documented. In fact, I came to learn that even the results here is also a little missing leading. The href property is not absolutely required but if you include that, it will override the id field which along with the type are the two mandatory inputs to properly construct this object.

To be explicit, below is a valid payload that can be used and notice even the syntax for id can have two forms: [VC],id:[VM-MOREF-ID] or [VC]/[VM-MOREF-ID] which just adds to the confusion. I prefer the latter format as its easier to understand and now that we know now to construct the VC:VirtualMachine JSON property, we now have all the pieces to execute this workflow using the vRO REST API.

"value": {
   "sdk-object": {
      "type": "VC:VirtualMachine",
      "id": "mgmt-vcsa-01.cpbu.corp/vm-2660"
   }
}

Step 4 - Finally, putting all this together we have the following payload (be sure to replace the values with your respective workflow) and then we perform a "POST" to https://[VRO-SERVER]:443/vco/api/workflows/[WORKFLOW-ID]/executions which will execute the vRO workflow via the vRO REST API.

{
    "parameters": [
               {
			"value": {
				"sdk-object": {
					"type": "VC:VirtualMachine",
					"id": "mgmt-vcsa-01.cpbu.corp/vm-2660"
				}
			},
			"type": "VC:VirtualMachine",
			"name": "vm",
			"scope": "local"
		},
		{
			"value": {
				"string": {
					"value": "Application"
				}
			},
			"type": "string",
			"name": "categoryName",
			"scope": "local"
		},
		{
			"value": {
				"string": {
					"value": "Photon"
				}
			},
			"type": "string",
			"name": "tagToFind",
			"scope": "local"
		}
	]
}

In my example, here is what the URL looks like substituting the required fields: https://vro.cpbu.corp:443/vco/api/workflows/9d95c7f5-a563-413f-af42-fd7e09275216/executions as shown in the screenshot below

If everything was successful we should see the workflow execute successfully via the vRO REST API and we can also confirm by using the vRO UI. Once I understood how the object should be constructed and the actual required values and syntax, this was not too difficult but I can say it was not a trivial thing to figure out. I should also mention for those looking to automate vRO workflows via vRO REST API, check out Jonnathan Medd awesome PowervRO module which makes it very simple to call into a specific workflow via the vRO REST API, but you will still need to create the required payload and using this blog post, you now have a way to construct it! Happy vRO'ing and stay tuned for how I will be using the vRO REST API as this is not the end of it 🙂