In this recipe, we will use the REST plugin. We will use it to connect to the Orchestrator Control Center REST API.
We need a REST-capable host you can contact. As every REST host handles things a little differently, we will use the REST interface Orchestrator and the Orchestrator Control Center, to showcase the functionality.
I have also collected some other Orchestrator-REST integration examples in the See also section of this recipe.
If you are new to REST, I would like to point you to the Accessing Orchestrator REST API recipe in Chapter 7, Interacting with Orchestrator.
This recipe is divided into connecting, gathering information, sending information, as well as creating workflows.
There are two methods (as of vRO7.1) to connect to a host. We will use the normal method here to connect to a REST host, as this showcases a lot of things you should know. The other one (using Swagger) is discussed in the There's more... section:
Orchestrator |
|
Orchestrator Control Center |
|
Orchestrator |
Orchestrator Control Center | |
Authentication |
Basic |
Basic |
Session |
Shared or per user |
Shared (root) |
You have now added the REST host to Orchestrator. However, some REST interfaces (such as vCloud Director) require a certain path for login. To adjust to this behavior, you can have a look at the example workflow: Library | HTTP-REST Samples | Set vCloud Director Authentication to a REST host.
We will now demonstrate a GET request to a REST host. GET gets information from a REST host:
About
or Status
.
Orchestrator |
|
Displays version information of Orchestrator. |
Control Center |
|
Displays the status of the Orchestrator service. |
You will see that the GET on Orchestrator will result in a string that contains a JSON object. Have a look at the logs. The Orchestrator will show:
Content as string: {"version":"7.0.1.3533702","build-number":"3533702","build-date":"2016-02-09T12:19:45Z","api-version":"5.5.2"}
Whereas the Control Center shows an error (all in red), which shows:
Error in (Workflow:Invoke a REST operation / Check status code (item3)#1) HTTPError: status code: 415
This is due to the way the default content type is used in the request. Check the How it works... section of this recipe.
While GET gets information, POST will alter, create, or transfer information on the REST host:
Info
or Start
.
Host |
Template URL |
Content type |
Orchestrator |
|
|
Orchestrator Control Center |
|
|
The {id}
part will be replaced later at execution.
Before we can execute the workflow, we need to get the ID of the workflow. In this example, we will use the example workflow 00.00 BasicsWorkflow
. Using the Orchestrator Client, browse the workflow and copy its ID from the General tab (for example, 312b7be1-abd2-47b6-9bc9-9e44c80ad168
):
<execution-context xmlns="http://www.vmware.com/vco"> <parameters> <parameter type="string" name="input" scope="local"> <string>Entry String</string> </parameter> </parameters> </execution-context>
The POST request requires you to enter additional information. The content is in the string
form; however, it contains XML. The return code should be a 202 status code, which means that the request was accepted.
The Control Center doesn't need extra information but executes a command that starts the Orchestrator service on the selected host.
To create a workflow out of a REST operation, follow these steps:
When running the workflow, you will be required to enter the same variables that you entered when using the Invoke a REST operation
workflow.
For the examples we are looking at, there are only two return types; XML and JSON.
XML parsing is discussed in the Working with XML recipe in Chapter 10, Built-in Plugins.
JSON parsing is shown in the Introduction to Chapter 7, Interacting with Orchestrator.
The other method to connect a host, and probably the best one for Control Center, uses the workflow Add a REST host by Swagger spec from a URL.
Swagger is a method describing the operations of a REST host. The interface is pretty common nowadays but not every REST host uses it yet.
To try it out, we will add the Orchestrator Control Center using the following method:
https://[FQDN
Orchestrator control Center]:8283/vco-controlcenter/api/api-docs
.application/json
as the default content type.REST stands for Representational State Transfer and is the way that most applications nowadays use an interface. Even Orchestrator itself switched from a SOAP interface to a REST interface.
Orchestrator can use the following authentication methods out-of-the-box:
Method |
Description |
None |
Doesn't use any authentication at all. |
OAuth |
A token-based authentication. For the difference between v1 and v2, see https://blog.apigee.com/detail/oauth_differences . |
Basic |
Basic authentication, no encryption, and clear text passwords. |
Digest |
Provides a basic encrypted authentication. |
NTLM |
NTLM (NT LAN Manager) provides encryption using the Window Security Support Provider (SSPI) framework. |
Kerberos |
Encrypted authentication using tickets. Also see the Configuring the Kerberos authentication recipe in Chapter 2, Optimizing Orchestrator Configuration. |
Taking a look at the code behind the workflows, we find that authentications are created by the RESTAuthenticationManager
object using the createAuthentication()
method. This method requires the authentication type (Basic, OAuth 1.0, and so on) as well as the authentication parameters (authParams
). The authParams
variable can have different content depending on the REST host and login method used. Take a look at this example:
Method |
Usage |
OAuth 1.0 |
|
OAuth 2.0 |
|
Basic |
|
vCD |
|
So, if you have trouble connecting to your REST host, you can simply alter authParams
to the specifications of your REST host.
Let's take a look at the results of a request. The results are part of the RESTResponse
object. The two important attributes of this object for most users are contentAsString
and statusCode
. The statusCode
attribute contains the status code of the request. You can view the basic response codes at https://[IP or FQDN Orchestrator]:8281/vco/api/docs/rest.html
.
The contentAsString
attribute returns a string that represents which is returned, which is XML in case of the Orchestrator and JSON in case of the Control Center. You can use the information in the Working with XML recipe in Chapter 10, Built-in Plugins or the JavaScript complex variables recipe in Chapter 6, Advanced Programming to phrase the return code.
The error we get in the GET of the Control Center is related to the fact that we didn't (or better, couldn't) define a default content type (Header). Other REST servers, such as vCloud Director, might also need some more headers. To fix this you can do the following:
Method A:
//Customize the request here //request.setHeader("headerName", "headerValue");
request.setHeader
and replace the header content:request.setHeader("content-type", "application/jso");
Method B:
defaultContentType
variable.application/json
.The example workflows are as follows:
09.04.1 Copy of Add a REST operation
09.04.2 Invoke 'status: GET /server/status'
09.04.3 Invoke 'start Orchestrator Service: POST server/status/...'