Exploring vCO and REST APIs

Lets talk about vCenter Orchestrator and how to use it to drive other products or solutions that have a rest based API. During my journey learning about vCO I had to communicate with an external REST API. Specifically an element orchestrator for storage process automation.

First of all we need a common understanding of how vCO can be used to talk to REST APIs. At the very first you need to install the rest plugin. Next you add a so called “REST host” by runnning a predefined workflow that is automatically made available by the rest plugin. In the third step you define “REST Operation(s)”. A rest operation define how to call a REST API and with what parameters. this operation can later be reused in your own workflows. The good thing doing it this way is you get a lot of help along the way as you have to work your way through different wizards. For my use case it was not a great solution hence why I´m writing this article.

first of all you need to run the “Add a REST host” workflow.

Add all parameters asked for in the wizard:

Name = logical name you will later use in javascript
URL = Base URL to REST API host

Choose authentication mechanism. Our example host uses basic authentication.

Our example uses a shared user for all operations done where this host definition is used

Next step is to add a REST operation. This is an operation we can call from our own developed workflows if needed. I won’t go into much details of how to do this but instead link to another blog post that explain how this works. See, http://blogs.vmware.com/orchestrator/2011/07/browsing-the-netflix-catalog-using-the-vco-http-rest-plug-in.html
referenced blog post is created with an older version of vCO. Although the concepts are the same in vcO v5.1.

Lets get started with the details. One thing you should do too, is to let vCO manage your REST host credentials. I don’t want to have username and passwords in clear text within my workflows which is why I decided to use vCO builtin repository of REST Hosts. Doing it this way mean you don’t have to worry much about security as much as you can call upon a host from your workflow, without knowing it´s username and password. Lets have a look at how it is done in JavaScript. The code example below is part of a “Scriptable Task” with a few input parameters. Namely “restHost” and “size”, “restHost” is created as a workflow attribute with a predefined value that contain the logical name of the REST host we added earlier (mytesthost) and “size” is an input parameter.

var restOp = new RESTOperation("Order NFS Storage from ISM"); // Define the name of the new operation
restOp.method = "POST"; // How is data sent to the api when called. POST mean we send data to the api.
restOp.urlTemplate = "/api/services/43?volumeName={exportName}&size={size}&rwHosts={RWHosts}"; // Define how to call api. Three parameters get sent when we call the api.
restOp.defaultContentType = "application/json";
var exportName = "vCO_" + datastoreName; // Set name of NFS export
var RWHosts = ""; // Which hosts should have R/W access to export
var inParamtersValues = [exportName, size, RWHosts]; // Add input parameters and variables to array
operation = restHost.addOperation(restOp); // Add defined operation to rest host defined in "restHost" attribute
var content = ""; // Our api do not need any payload send to it as all interaction is done through different URLs
var request = operation.createRequest(inParamtersValues, content); // Create request to api

Now you know how to use a predefined REST Host in your workflows directly from javascript while defining your own operation that can be executed against that host. The code snippet below will execute the defined REST Operation above and return data from the REST Host and store it in a variable named “response”.

var response = request.execute(); // Execute request and store returndata in "response"
/ Code below is for debugging purposes and will output data in Orchestrator client when run. Output is not persistent.
System.log("Returned status code: " + response.statusCode);
var contentAsString = response.contentAsString; // Convert response to plain string
System.log("Content as string: " + contentAsString);

At this point we have executed our operation and we got a response back. If this was production grade code we would have error checking in the code before we process the returned data. For now we consider all responses to be ok and being of type json. Code snippet below show you how to process our returned json data and extract a variable named “orderId”.

var jsonResponse = JSON.parse(contentAsString);
ismOrderId = jsonResponse.orderId; // Extract the orderId variable form the response
System.log ("orderId = " + ismOrderId);

By now you should have a basic understanding of how to interact with REST APIs through JavaScript in vCO. As you have realized already this article do not tell how to build a complete workflow that communicate with a REST API. It was not my intention to do so either. I welcome all comments and interaction as I´m also learning about vCO at the same time.

This entry was posted in Automation, Unified Storage, vCenter Orchestrator. Bookmark the permalink.

2 Responses to Exploring vCO and REST APIs

  1. todar says:

    Did you use VCO4 or VCO5 for this?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s