Calling vRO (VMware Orchestrator) Workflows via REST API

Last year I integraded some workflow calls in internal websites. The vRO offers a REST API for this. Unfortunately it’s not documented very well so I had to spend some time to figure things out.

This monday in Barcelona (VMworld 2016) there was a Hackathon organized by Alan Renouf. I attended a team to build a HTML5 interface to show information grabbed by docker containers with pyvmomi from vCenter servers. The whole Hackathon was a pleasure!

There was also a team building a HTML5 page to call vRO Workflows through the REST API. They get really close, they get the UI running and grabbed all available workflows via API. But as I know, the hard part follows up 😉
I’d like to share my experience in this post.

Firs of all I began with this guide:
For the beginning it was pretty good but if you really want to use the API it gets not far enough.

To view the API in your Browser jus visit: https://<your vRO>:8281/vco/api/
To view the Docs visit: https://<your vRO>:8281/vco/api/docs/index.html

If you are using vRO 7 you are also able to run and test alle the available API calls with the last link. This is much better than the Docs of vRO 6.

In general you can talk to the vRO in two formats: JSON or XML
To change between these formats you have to set HTTP headers:

for JSON:

Accept: application/json
Content-Type: application/json

for XML:

Accept: application/xml
Content-Type: application/xml


How to run a workflow

To run a workflow you just need to do a POST to this URL: https://<your vRO>:8281/vco/api/workflows/<workflow ID>/executions
You can look up the workflow ID in your vRO Client.

If you get HTTP 202 your workflow started successfull – just start – it does not say anything about the result of your run.

Also you get back a HTTP Header with the parameter „Location“ – which looks like:
https://<your vRO>:8281/vco/api/workflows/<workflow ID>/executions/<execution ID>/

The execution ID is the ID of your running workflow – you need it to get the status of your workflow run, get output parameters, …


How to get a status of my workflow run

To get the status you use the URL you get back in the Location-Parameter of the HTTP Header:
https://<your vRO>:8281/vco/api/workflows/<workflow ID>/executions/<execution ID>/

Here you get all the information you need:

  • state (completed, failed, …)
  • Your provided input-parameter
  • output-parameter (only if state = „completed“)
  • start-date
  • end-date
  • started-by
  • content-exception (only if state = „failed“)


Passing parameters to your workflow

Until now this was all standard REST and nothing special – but now it gets interesting 😉
The easiest way to find out how to pass arguments is to run the workflow from vRO client and take a look at the execution with your browser and the REST API.

To pass parameters you have to provide some information in your body while you do your POST request:

 <execution-context xmlns="">
     <parameter type="VC:HostSystem" name="inHosts" scope="local">
       <sdk-object type="VC:HostSystem" id="your.vcenter.fqdn/host-1234"/>
     <parameter type="string" name="inShareString" scope="local">
       <string>this is a string</string>
     <parameter type="Text" name="inBemerkung" scope="local">
         <string>this is a text</string>
     <parameter type="number" name="inNumber" scope="local">
     <parameter type="boolean" name="inBoolean" scope="local">

In this example there are five input Parameters:

  1. Name: inHosts (Type „VC:HostSystem“)
  2. Name: inShareString (Type „string“)
  3. Name: inBemerkung (Type „Text“)
  4. Name: inNumber (Type „number“)
  5. Name: inBoolean (Type „boolean“)

In JSON it looks like:

  "parameters": [
      "type" : "VC:HostSystem",
      "name" : "inHosts",
      "scope" : "local",
      "value" : {
        "sdk-object" : {
          "type" : "VC:HostSystem",
          "id" : "your.vcenter.fqdn/host-1234"
      "type" : "string",
      "name" : "inShareString",
      "scope" : "local",
      "value" : {
        "string" : {
          "value" : "this is a string"
      "type" : "Text",
      "name" : "inBemerkung",
      "scope" : "local",
      "value" : {
        "string" : {
          "value" : "this is a text"
      "type" : "number",
      "name" : "inNumber",
      "scope" : "local",
      "value" : {
        "number" : {
          "value" : "42"
      "type" : "boolean",
      "name" : "inBoolean",
      "scope" : "local",
      "value" : {
        "boolean" : {
          "value" : "true"

This may contain errors – I’ve just disassembled my running code – forgot to document it last year 😀

As you see the input parameter „Text“ has also the type „string“.

Also you can see how to pass objects – any object is an „sdk-object“.
The value is the MoId (Manage Object ID). In case of the vCenter Plugin it is „vcenter-name/moid“.

Get the MoId you have to pass

There are several way to get it.

  1. For vCenter objects you can get the moid of your VMs, Hosts, .. from MOB (https://<your vcenter/mob)
  2. You can search the vRO inventory by using this URL:
    https://<your vRO>:8281/vco/api/catalog/VC/HostSystem/?conditions=name=<esxi name>
  3. I already have a database with object-name <=> moid relation for other functions of my webpage so I just use this (there is a discovery run every night and my workflows update the database over day per single operation)
  4. For other departments in our company I just build workflows with string input and do the object-search inside the workflow – then they don’t need to bother about object types and IDs and just have to pass me the name


Example code and functions

I’ve pushed some example code to github:

Feel free to do pull requests with your own examples.