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: http://www.vcoteam.info/articles/learn-vco/268-how-to-use-the-rest-api-to-start-a-workflow.html
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:

for 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:

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:

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: https://github.com/Torsten-/vro_rest_api

Feel free to do pull requests with your own examples.

 

2 Kommentare zu “Calling vRO (VMware Orchestrator) Workflows via REST API

  1. Hallo,
    Ich versuche laufen ein workflow mit REST API.
    Meine JSON parameters sind:
    {
    „parameters“: [
    {
    „value“: {
    „sdk-object“: {
    „type“: „AdcVCOPlugin:AdcContainer“,
    „id“: „vxContainer“
    }
    },
    „type“: „AdcVCOPlugin:AdcContainer“,
    „name“: „container“,
    „scope“: „local“
    }, …

    Ich becomt win fehler:
    {
    „status“: 400,
    „message“: „2 error(s) found: [ { ADC-VX Container – Unable to convert object, no sdk type defined for class : AlteonPartitioned vxContainer (10.205.122.86) } { ADC-VX Container – This field is required. } ]“
    }

    (it is too hardfor me to continue in German… 🙂 )
    Anyway, I get the above failur, while try to use an API REST call to run a workflow.
    It seems that the object I use in the parameters payload is wrong; any idea, how can I solve that?
    Danke,
    Efner

    • Hi Efner,

      I think you are using a special Alteon Plugin? I don’t know how to pass the objects of this plugin, but maybe it could help if you run the workflow once with your parameters from vRO Client and then take a look with the browser inside the api of this workflow run, how the parameters look like there.

      Other method: Pass a string and let the workflow search the object 😉

      Regards
      Torsten

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.

*