Configuring a REST Connector to Invoke a REST Service

Configure a REST connector to invoke a REST service. In the REST connector, you specify an HTTP method and then provide the following additional details required for the connector to complete the request:

The path to a particular endpoint in the REST service.
Parameters, if required by the endpoint.
Key-value pairs for the HTTP header.

In the Orchestrator Studio, you can test the connector and view the JSON response of the REST service call. You can also use scripting to refine the data in the connector output. For example, you can configure a script to change the contents of the REST service response so that the connector output contains only the data required by the consuming device or program.

To configure a connector to invoke a REST service:

Click the Connectors icon on the Orchestrator Studio Home page.
On the Connectors side panel, click the New drop-down menu and select REST.
Create and name the connector service request as described in Creating a Component.
On the Connectors design page, click the REST field and select a connection.
Click the HTTP Method drop-down list and select the appropriate method.
Slide the Fire and Forget toggle to the right if you want the orchestration to execute without waiting for a response. If Fire and Forget is enabled, the Output section is hidden because the REST service response is not processed.
(Release 9.2.4.4) The Number of Threads option is displayed when you enable the Fire and Forget toggle. This option enables you to select the number of threads for an iterated step.
(Release 9.2.5.2) Enable the Use Connection Security option if you want to use the security defined in the connection.
Expand the Pathing section and use the Value grid to build the path to a REST service endpoint.
Each value you enter in the Value grid is appended to the path, separated by a slash (/). You can use variables in the path by adding a value inside ${}. Click the Delete button at the end of a row to delete any values from the path.
If the REST service takes parameters, use the Parameters section to append parameters to the endpoint.
Parameters are appended to the endpoint after a question mark (?) and are separated by an ampersand (&). You can include variables by specifying a value inside ${}.
In the Headers section, enter key-value pairs for the header in the Key and Value columns. You can also choose any known values from the drop-down menu in each column.

Starting with Tools Release 9.2.6.4, the File Upload and Multipart toggle options are available in the Headers section. When you select the File Upload option, the system enables the File section and the Parts section of the request where you can configure files (reports or files from the temporary directory) as input to the REST service in addition to any text-based input to the request.

When you select the Multipart option, the system enables you to set the Content-Type to multipart/form-data. When you select this option, the system enables only the Parts section to allow for multipart request without sending a file.

Starting with Tools Release 9.2.8.2, the Orchestrator Connector step is enhanced to allow files to be sent to external REST APIs either as a multipart request or as a direct request (without multipart boundaries in the request body). When you select the File Upload option, the system displays the Binary Body option. You can enable the Binary Body option to send the file as the body of the HTTP request. When you select the Binary Body option, you can add an appropriate header value for Content-Type. If the Content-Type header is not defined, the system attempts to find the matching MIME type based on the file name. If the MIME type is not found, then the system uses application/octet-stream.
In the Body section (which is not used or displayed if the HTTP method is GET or TRACE), if required by the HTTP method, specify a payload to send to the REST service.

Note: Starting with Tools Release 9.2.5.5, the variables defined inside the JSON strings in the body of the request should include the esc notation. The esc notation ensures that the string values are properly escaped for use as JSON strings at runtime.For example, you should define the JSON input as follows in the body of the REST connector:instead of using this traditional method:In the above examples, a variable called myVariable is defined. In the first example, the value inside the variable will be escaped for use as a JSON string at runtime. An invalid JSON may be created if you use the second example, and the runtime value may have invalid characters and they will not be escaped.
(Release 9.2.5.2) Expand the Response section and in the Header section, enter the name of the header field in the Output column and a variable name in the Variable Name column. By defining a variable, you can pass a header value from the response of the REST service to the subsequent orchestration steps. For example, after successful authentication, a REST service may return an authentication token in the response header. You can pass that token as a variable to subsequent orchestration steps to maintain an authenticated session.
In the Manipulate Body section, use scripting to manipulate the output of the REST call. For example, if you only need certain data in the output, you can use a script to refine the data displayed in the output. Depending on the scripting language you choose, a template will be displayed and you can modify it to manipulate the output. For Groovy, see Groovy Template for Manipulating Output from a REST Connector Response for more information.
(Release 9.2.8.2) In the Output section, you can enable the Include Response Status option, and enter the variable. This option enables the connector step (REST or OpenAPI) to assign the returned HTTP status code to an orchestration variable. Having the HTTP status code as an orchestration variable then gives you more control over an intelligent reaction to the HTTP status. For example, if a third-party system returns an HTTP status of 500, the orchestration might pass that status into a rule, which in turn sends a notification message indicating the failure.
In the Output section, use the following sections to identify the outputs:
- JSON Output.
  
  If the value you want is nested in JSON objects, you can get to the value by separating each JSON object name by a period (.). If the value you want is in an array, you can access the value by adding the proper index of the array inside brackets ([]).
  
  Note: The outputs are based on the JSON response of the REST service call. You can see the response after running a successful test of the REST service using the Test button.
  
  To understand how to define the name and category as objects in the array, see the following section Defining Array Outputs from Connectors (Release 9.2.5.2).
- Output to a File (Release 9.2.6.2)
  
  Use this option to accept files from the response from external REST calls and to save and name the file output for use in subsequent orchestration steps.
  
  Complete the following fields:
  - File Name: Enter a file name or a variable.
  - Overwrite Existing Files: Enable this option if you want to use the original file name for all the files throughout the processing. Disable this option to assign a unique file name to each file.
  - Keep Temp Files: Enable this option to save the files in the temporary directory. The files saved in the temporary directory will remain there indefinitely. Disable this option if you want to save the files in the user's session temporary directory. The system deletes these files when the session ends.
  - File Name Variable: Enter the file name variable that can be referred in the subsequent orchestration steps.
  Note: You can test the response by using the Test button. When you click the Test button, the system will call the service and download the output file.
To test the connector:
1. Click the Test button.
2. If the connector includes variables, enter values for the variables.
  If test is successful, the Orchestrator Studio displays the response.
3. Click the Show Output button that is displayed at the end of the response to apply the instructions that are defined in the Output section, including any manipulation specified in the script.
  Use the results to validate the path to the output values that are specified in the Output section.