Invoking UCS Director Workflows via the Northbound REST API

This is a guest post, offered by a colleague of mine: Russ Whitear.

Russ is the UCS Director guru  in our team and, when I saw an internal email where he explained how to use the UCS Director API from an external client, I asked his permission to publish it.

I believe it will be useful for many customers and partners to integrate UCSD in a broader ecosystem.

This short post explains how to invoke UCS Director workflows via the northbound REST API. Authentication and role is controlled by the use of a secure token.  Each user account within UCS Director has a unique API token, which can accessed via the GUI like so:

Firstly, from within the UCS Director GUI, click the current username at the top right of the screen. Like so:

User Information will then be presented. Select the ‘Advanced’ tab in order to reveal the API Access token for that user account.

Once retrieved, this token needs to be added as an HTTP header for all REST requests to UCS Director.  The HTTP header name must be X-Cloupia-Request-Key.

X-Cloupia-Request-Key : E0BEA013C6D4418C9E8B03805156E8BB

Once this step is complete, the next requirement is to construct an appropriate URI for the HTTP request in order to invoke the required UCS Director workflow also supplying the required User Inputs (Inputs that would ordinarily be entered by the end user when executing the workflow manually).

UCS Director has two versions of northbound API. Version 1 uses HTTP GET requests with a JSON (Java Standard Object Notation) formatted URI. Version 2 uses HTTP POST with XML (eXtensible Markup Language) bodytext.

Workflow invokation for UCS Director uses Version 1 of the API (JSON). A typical request URL would look similar to this:

http://<UCSD_IP>/app/api/rest?formatType=json

                 &opName=userAPISubmitWorkflowServiceRequest

                 &opData={SOME_JSON_DATA_HERE}

A very quick JSON refresher

JSON formatted data consists of either dictionaries or lists. Dictionaries consist of name/value pairs that are separated by a colon. Name/value pairs are separated by a comman and dictionaries are bounded by curly braces. For example:

{“animal”:”dog”, “mineral”:”rock”, “vegetable”:”carrot”}

Lists are used in instances where a single value is insufficient. Lists are comma separated and bounded by square braces. For example:

{“animals”:[“dog”,”cat”,”horse”]}

To ease readability, it is often worth temporarily expanding the structure to see what is going on. 

{

    “animals”:[

        “dog”,

        ”cat”,

        ”horse”

    ]

}

Now things get interesting. It is possible (And common) for dictionaries to contain lists, and for those lists to contain dictionaries rather than just elements (dog, cat, horse etc…). 

{ “all_things”:{

        “animals”:[

            “dog”,

            ”cat”,

            ”horse”

        ],

        “minerals”:[

            “Quartz”,

            “Calcite”

        ],

        “vegetable”:”carrot”

    }

}

With an understanding of how JSON objects are structured, we can now look at the required formatting of the URI for UCS Director. When invoking a workflow via the REST API, UCS Director must be called with three parameters, param0, param1 and param2. ‘param0’ contains the name of the workflow to be invoked. The syntax of the workflow name must match EXACTLY the name of the actual workflow. ‘param1’ contains a dictionary, which itself contains a list of dictionaries detailing each user input and value that should be inserted for that user input (As though an end user had invoked the workflow via the GUI and had entered values manually.

The structure of the UCS Director JSON URI looks like so:

{

    param0:"<WORKFLOW_NAME>",

    param1:{

                "list":[

                       {“name":"<INPUT_1>","value":"<INPUT_VALUE>"},

                       {"name":"<INPUT_2>","value":"<INPUT_VALUE"}

                ]

            },

    param2:-1

}

So, let’s see this in action. Take the following workflow, which happens to be named ‘Infoblox Register New Host’ and has the user inputs ‘Infoblox IP:’,’Infoblox Username:’,’Infoblox Password:’,’Hostname:’,’Domain:’ and ‘Network Range:’.

The correct JSON object (Shown here in pretty form) would look like so:

Note once more, that the syntax of the input names must match EXACTLY that of the actual workflow inputs.

After removing all of the readability formatting, the full URL required in order to invoke this workflow with the ‘user’ inputs as shown above would look like this:

Now that we have our URL and authentication token HTTP header, we can simply enter this information into a web based REST client (e.g. RESTclient for Firefox or Postman for Chrome) and execute the request. Like so:

 

If the request is successful, then UCS Director will respond with a “serviceError” of null (No error) and the serviceResult will contain the service request ID for the newly invoked workflow:

Progress of the workflow can either be monitored by other API requests or via the UCS Director GUI:

Service request logging can also be monitored via either further API calls or via the UCS Director GUI:

This concludes the example, that you could easily test on your own instance of UCS Director or, if you don't have one at hand, in a demo lab on dcloud.cisco.com.

It should be enough to demonstrate how simple is the integration of the automation engine provided by UCSD, if you want to execute its workflows from an external system: a front end portal, another orchestrator, your custom scripts.

See also The Elastic Cloud project - Porting to UCSD for the deployment of a 3 tier application to 3 different hypervisors, using Openstack and ACI with Cisco UCS Director.