Configuring an Open API Connector to Invoke a REST Service
You can configure an Open API connector to invoke a REST service. In the Open API connector, when you specify the API call and set the HTTP methods that are populated in the system according to the allowed API call, the Pathing and Parameter fields are automatically filled with values as required for the REST service.
You can test the connector and view the JSON response body of the REST service. You can also use Groovy, JRuby, Jython scripting to refine the data in the connector output.
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:
{"value":"$esc{myVariable}"}instead of using this traditional method:
{"value":"${myVariable}"}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.
To configure an Open API 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 Open API.
Create and name the connector service request as described in Creating a Component.
On the Connectors design page, click the Open API field and select a connection.
The URL to the REST service for the Open API connection is displayed.
Click the API drop-down list and select the API from the list of all the available APIs as defined in the Open API documentation. The HTTP methods will be populated as applicable to the selected API call.
Click the HTTP Method drop-down list and select the method as required.
After you select the HTTP Method value, if available in the documentation, the corresponding values for the selected API are displayed in the API Description and API Summary fields. Also, the Pathing, Parameters, Headers, and Body sections are automatically filled with the appropriate values.
Note: Pathing section is read-only and hence you cannot modify this section. The value in the Pathing section is displayed based on the API definition. You can change the values defined in the Parameter and the Body sections if you want to hard-code the values that are passed.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). If you select the File Upload option in the Headers section, 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.Enable the Fire and Forget toggle 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.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:
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.Manipulate Output (advanced). Use Groovy, JRuby, or Jython scripting to modify the output of the REST call. For example, if you only need certain data in the output, you can use Groovy scripting to refine the data that is displayed in the output. See Groovy Template for Manipulating Output from a REST Connector Response for more information.Click the Show Shortcut Command icon (?) to view the commands to edit the script.
Output grid. 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 it by adding the proper index of the array inside brackets ([]).
To test the connector:
Click the Test button.
If the connector includes parameters, enter values for the parameters in the pop-up box.
Clicking Execute displays the REST service response.
Click the Show Output button that is displayed at the end of the response to view the modified output.