Home > Virtualization > vCenter Orchestrator REST APIs: Executing Workflow

vCenter Orchestrator REST APIs: Executing Workflow

August 12th, 2013 Leave a comment Go to comments

Just played with vCenter Orchestrator REST APIs and found it’s pretty straight-forward to use. With the REST APIs, you can manage various resources such as workflow, workflow run, workflow presentation, workflow user interaction presentation, catalog, action, package, inventory, action, category, configuration, content, notification, service descriptor, user. It seems possible to build your vCO client like GUI with this set of APIs.

API Documentation Included

Time to learn how to "Google" and manage your VMware and clouds in a fast and secure


With vCO installation, you can access the REST API documentation easily with the following URL. Note that also works but it redirects to the HTTPS link as follows.

The page has links to the REST API services, Data Model, and Files and Libraries. Very helpful and convenient indeed.

Executing Workflows Remotely

While you can interact with various services from vCO, the most common one is to remotely call existing workflows. This is achieved by the Workflow Run Service which includes several operations like retrieving all workflow runs, starting workflow in a new run, finding out the running status of a workflow run, retrieving logs.

What I care the most is to run a workflow. It can be done using HTTP POST with REST client add-on Firefox browser.

Header: Content-Type: application/xml
<execution-context xmlns="http://www.vmware.com/vco">

The is the static IP address of vCO server, and the 29b6dfb4-2942-4bc0-b544-c8383d979572 is the id for the workflow you intend to run. Note: you have to use https protocol or you will receive same response as GET and the workflow would not run at all.

If you have parameters to pass into the workflow, you want to include them within the tag in the above XML body.

      <parameter name="dcName" type="string">
        <string>Santa Clara</string>
      <parameter name="cluster" type="string">
        <string>Demo Sandbox</string>

After running the API call, you will get a response with code 202 as follows:

    Status Code: 202 Accepted
    Content-Length: 0
    Date: Tue, 06 Aug 2013 23:37:06 GMT
    Etag: "0d41d8cd98f00b204e9800998ecf8427e"
    Location: 3/
    Server: vCO Server

Find Workflow ID Using Name

You may wonder, “how can I find the id string for the workflow even though I know its name?”

A fair question. To get the id, you want to list all the workflows via HTTP GET method.


It may take several seconds before the call returns with the following the header – all depends on how many workflows you have in vCO server.

    Status Code: 200 OK
    Cache-Control: no-cache
    Content-Length: 227041
    Content-Type: application/xhtml+xml;charset=UTF-8
    Date: Wed, 07 Aug 2013 17:16:53 GMT
    Etag: "0ffdf5134a56fa98d2898883caee557c9"
    Expires: Thu, 01 Jan 1970 00:00:00 UTC
    Pragma: No-cache
    Server: vCO Server

The interesting part is the response body which looks like the following. Since the real XML is pretty long, I just list part of it with clear structure.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<inventory-items xmlns="http://www.vmware.com/vco" total="247">
  <link rel="down" href="">
      <attribute name="itemHref" value=""/>
      <attribute name="id" value="51808080808080808080808080808080A180808001175587494510271f02ffa1f"/>
      <attribute name="categoryName" value="Samples XML (Simple)"/>
      <attribute name="canExecute" value="true"/>
      <attribute name="categoryHref" value=""/>
      <attribute name="description" value="Creates a simple XML document for testing purposes."/>
      <attribute name="name" value="Create a simple XML document"/>
      <attribute name="type" value="Workflow"/>
      <attribute name="canEdit" value="true"/>
  <link rel="down" href="">
      <attribute name="itemHref" value=""/>
      <attribute name="id" value="29b6dfb4-2942-4bc0-b544-c8383d979572"/>
      <attribute name="categoryName" value="MyWF"/>
      <attribute name="canExecute" value="true"/>
      <attribute name="categoryHref" value=""/>
      <attribute name="description" value=""/>
      <attribute name="name" value="HelloWorld"/>
      <attribute name="type" value="Workflow"/>
      <attribute name="canEdit" value="true"/>

With the above XML, you can easily retrieve the ID of an existing workflow if you know its name.