vCenter Orchestrator REST APIs: Executing Workflow

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

Lost VMs or Containers? Too Many Consoles? Too Slow GUI? Time to learn how to "Google" and manage your VMware and clouds in a fast and secure HTML5 App.

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

https://192.168.8.8:8281/api/docs/

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.

POST https://192.168.8.8:8281/api/workflows/29b6dfb4-2942-4bc0-b544-c8383d979572/executions
 
Header: Content-Type: application/xml
Body:
<execution-context xmlns="http://www.vmware.com/vco">
    <parameters>
    </parameters>
</execution-context>

The 192.168.8.8 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>
      <parameter name="cluster" type="string">
        <string>Demo Sandbox</string>
      </parameter>

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: https://192.168.8.8:8281/api/workflows/29b6dfb4-2942-4bc0-b544-c8383d979572/executions/ff8080814017b877014055fdbb01089 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.

GET https://192.168.8.8:8281/api/workflows

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="https://192.168.8.8:8281/api/workflows/51808080808080808080808080808080A180808001175587494510271f02ffa1f/">
    <attributes>
      <attribute name="itemHref" value="https://192.168.8.8:8281/api/workflows/51808080808080808080808080808080A180808001175587494510271f02ffa1f/"/>
      <attribute name="id" value="51808080808080808080808080808080A180808001175587494510271f02ffa1f"/>
      <attribute name="categoryName" value="Samples XML (Simple)"/>
      <attribute name="canExecute" value="true"/>
      <attribute name="categoryHref" value="https://192.168.8.8:8281/api/catalog/System/WorkflowCategory/ff8080813fc58b2b013fc58b69ef0004/"/>
      <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"/>
    </attributes>
  </link>
...
  <link rel="down" href="https://192.168.8.8:8281/api/workflows/29b6dfb4-2942-4bc0-b544-c8383d979572/">
    <attributes>
      <attribute name="itemHref" value="https://192.168.8.8:8281/api/workflows/29b6dfb4-2942-4bc0-b544-c8383d979572/"/>
      <attribute name="id" value="29b6dfb4-2942-4bc0-b544-c8383d979572"/>
      <attribute name="categoryName" value="MyWF"/>
      <attribute name="canExecute" value="true"/>
      <attribute name="categoryHref" value="https://192.168.8.8:8281/api/catalog/System/WorkflowCategory/ff8080813fc58c21013fca524c7d0004/"/>
      <attribute name="description" value=""/>
      <attribute name="name" value="HelloWorld"/>
      <attribute name="type" value="Workflow"/>
      <attribute name="canEdit" value="true"/>
    </attributes>
  </link>
</inventory-items>

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

This entry was posted in Virtualization and tagged , , , . Bookmark the permalink. Post a comment or leave a trackback: Trackback URL.

One Trackback

Post a Comment

Your email is never published nor shared. Required fields are marked *

*
*

You may use these HTML tags and attributes <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

  • NEED HELP?


    My company has created products like vSearch ("Super vCenter"), vijavaNG APIs, EAM APIs, ICE tool. We also help clients with virtualization and cloud computing on customized development, training. Should you, or someone you know, need these products and services, please feel free to contact me: steve __AT__ doublecloud.org.

    Me: Steve Jin, VMware vExpert who authored the VMware VI and vSphere SDK by Prentice Hall, and created the de factor open source vSphere Java API while working at VMware engineering. Companies like Cisco, EMC, NetApp, HP, Dell, VMware, are among the users of the API and other tools I developed for their products, internal IT orchestration, and test automation.