cancel
Showing results for 
Search instead for 
Did you mean: 
cancel

Invoking UCS Director Workflows via the Northbound REST API

6879
Views
7
Helpful
10
Comments

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:

SG01.jpg

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

SG02.jpg

Once retrieved, this key 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 invocation 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 comma 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:’.

SG03.jpg

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

SG04.jpg

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:

SG06.jpg

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:

SG07.jpg

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

SG08.jpg

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

SG09.jpg

Comments
Cisco Employee

Thank you!

Where do I get the Infoblox integration tasks?

Regards!

Enthusiast

interesting is here any more details picture  how the Postman headers and body should look like ?

Trying to catch up here :-)

Beginner

Is there an API Call to resubmit a Service Request

Cisco Employee

 Looks like 'userAPIResubmitServiceRequest' is still supported.


@rwhitear42 wrote:

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:

SG01.jpg

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

SG02.jpg

 

Once retrieved, this key 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 invocation 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 comma 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:’.

SG03.jpg

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

SG04.jpg

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:

SG06.jpg

 

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:

SG07.jpg

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

SG08.jpg

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

SG09.jpg




Beginner

That was quick and helpful!! This is not documented in the recent docs and is available only in Cisco_UCS_Director_REST_Developer_Guide_53.

Beginner

@rwhitear42 I get the below error on UCSD 6.6..am I getting wrong something basic?

 

URL POST:

 https://100.65.219.24/app/api/rest?formatType=json&opName=userAPIResubmitServiceRequest&opData={param0:837,param1:2,param3:true}

 

Response:

{

    "serviceResponse": null,

    "serviceError": "SERVICE_CALL_EXCEPTION: Service InfraMgr does not support operation userAPIResubmitServiceRequest",

    "serviceName": "InfraMgr",

    "opName": "userAPIResubmitServiceRequest"

}

Cisco Employee
Hi,

I find that the best way to see which API requests are supported for a particular release is to do the following:


1. Login to UCSD with an admin account.
2. Click the User icon in the top right of the screen and select ‘Edit My Profile’.
3. Click ‘Show Advanced Settings’ at the bottom of the screen.
4. Click the checkbox to ‘Enable Developer Menu’
5. Save
6. Logout/Login as admin again.



Next time you select Orchestration with in the GUI, there should be a new tab called ‘REST API Browser’. This shows all available API calls.



Hope this helps.




Cisco Employee
I’ll try to find the time to give it a try and will post an example if I can make it work.

Beginner

Got it from the REST API Browser, Thanks :)

 

/app/api/rest?formatType=json&opName=servicerequest:userAPIResubmitServiceRequest&opData={param0:{"requestId":1000,"workflowStepId":"sample","skipApprovals":true}}

 

Cisco Employee
Great. Good to know.

Regards


CreatePlease to create content
Content for Community-Ad
August's Community Spotlight Awards
This widget could not be displayed.