REST Execution

You can execute REST calls to remote products via the On-Premise Bridge Agent by using the Execute REST business rule. You can use this business rule in a workflow, or in task and approval plans. The rule enables you to define tasks that execute REST calls automatically to external servers, and return the results. The results are stored in the output field defined in the business rule.

On-Premise Bridge Agent pre-configuration

To use the Execute REST Business Rule, the On-Premise Bridge Agent needs to be installed on a customer machine, and be configured to work.

Perform the following prerequisites:

• Configure the On-Premise Bridge Agent with a default endpoint. For more information, see How to use On-Premise Bridge agents on Windows or How to use On-Premise Bridge agents on Linux.

• Configure credentials using the Credentials Manager of the On-Premise Bridge Agent. These credentials are used for authentication in the remote server.

• Configure endpoints. An endpoint is defined with the remote service location: <Protocol>://<Host>:<Port>/<Service>. The endpoint uses the default credentials ID that was configured in the previous step for server authentication. For more information, see How to use endpoints.

Execute REST business rule configuration

After the On-Premise Bridge Agent is configured with endpoints and credentials, it is possible to configure and execute the Execute REST business rule.

The Execute REST business rule accepts the following parameters:

Parameter	Value
OPB Agent ID	Select an agent ID from the drop-down list. There is one agent for each network domain. Every agent has a default agent ID, but you can override it and use another pre-defined agent ID.
OPB Endpoint ID	Select an endpoint from the drop-down list. Every agent has a default endpoint, but you can override it and use another endpoint of that agent. For example, http://www.google.com/mail is the default endpoint for an agent, but the administrator can configure additional endpoints for the user to select, such as http://www.google.com/search.
Credentials ID	Select the credentials from the drop-down list by their ID. Every endpoint has a default credentials ID, but you can override it and use another credentials ID of that endpoint. For example, the default credentials are user1/pass1 with an ID of 123, but the user wants to use the credentials tester1/tester1 with the ID of 456 instead.
Uri Suffix	Select one of the following options: Simple Mode. Enter the required value manually. Expression Language. Enter an Expression Language phrase that returns the required value. The prefix of the URL is taken from the endpoint. This parameter is the suffix of the URL. The concatenated expression forms the URL of the REST call. This parameter must be HTTP encoded.
Web Method	Select a method from the drop-down list (POST/PUT/GET/DELETE).
Body	Select one of the following options: Simple Mode. Enter the required data manually. Expression Language. Enter an Expression Language phrase that returns the required data. This is the body that will be used in the REST call request to the remote server. The Body parameter is only relevant if POST or PUT is selected as the web method.
Headers	A dialog box opens with two boxes. For the Header key, enter data as free text. For the Header value, select one of the following options: Simple Mode. Enter the required data manually. Expression Language. Enter an Expression Language phrase that returns the required data. Click Add item to add an additional row with boxes for another header. The REST call request headers provide additional information for the REST call, such as the file type to be returned.
Output field name	Enter a field of the current record. Select one of the following options: Simple Mode. Enter the required field manually. Expression Language. Enter an Expression Language phrase that returns the required field. This parameter defines the field where the returned results are stored. For more information on the available output field types, see the next section.
Task Prefix	Enter the prefix text in the box manually. This parameter enables you to set values to be used in the result fields defined inside a complex type output field. It is not relevant for textual type output fields.

Click the Expression Language button to toggle between these options. When the button is selected (green), the field is in Expression Language mode. When it is not selected (white), the field is in Simple mode. For a full list of Expression Language functions, see Expression Language functions and syntax.

Output field types

When selecting the output field, you should select a field of the type that matches the type of results to be returned by the REST call. The field types are defined for each field in the Fields tab.

You can define the output field for the business rule execution with the following types:

Field type	Description
Textual field	A textual field is defined according to size. The following options are available: SMALL_TEXT MEDIUM_TEXT LARGE_TEXT RICH_TEXT If the defined field size is large enough to contain the full response string, it is stored in the field as is. If the field size is smaller than the response value, the response value is truncated to the size of the field.
User options	A user-defined field. You can define the following system fields within the user option to use in the business rule: RawOutput_c. A third party response of type string which contains the full JSON response. Example: {"ExecutionId" : "123", "URL" : "http/:<servername>.port/..."}. HttpStatusCode_c. A third party HTTP status response of type integer. Example: 400. To parse the RawOutput_c string, you can define the following custom fields, based on the above example, to use in the business rule (all of type string): ExecutionId_c. Parses the execution Id from the raw output string. Example: 123. URL_c. Parses the URL from the raw output string. Example: http:/<servername>.port/... Note   Only string result fields are supported in the complex type field (with the exception of the HttpStatusCode and IsFailed fields). The custom field name must be identical to the corresponding parameter in the raw output string (the comparison is case insensitive). Do not define multiple custom fields with names that differ only by case. Parameters in the raw output string that contain delimiters are not supported (For example, vm.name.)

Task Prefix field

You can set the TaskPrefix value in the business rule, to be used in the result fields defined inside the complex type field. This value is not relevant for a textual type output field.

If the TaskPrefix is defined, it is added to the complex type field names as follows: fullName = taskPrefix+fieldname. The result values are then matched to a field named fullName. Similarly, when accessing a value from internal properties of the complex type field, this is done from the property named fullName.

This enables you to run multiple tasks with this business rule concurrently without overriding the other results, since the results are saved in different results fields inside the same complex type output field, according to the TaskPrefix value.

Using the example from above, for taskPrefix=Task1, the field in the complex type should be Task1Comments0ContentSubmitterUserId, in order to get the value of Comments0ContentSubmitterUserId after the execution of a task with the prefix Task1.

For multiple tasks, each task should have its own TaskPrefix value and result fields names (such as Task2 and Task2Comments0ContentSubmitterUserId).

Example of a business rule

You can use the Execute REST business rule to post issues (defects) via the JIRA service.

Follow these steps:

1. Create a demo JIRA account (go to https://www.atlassian.com/software/jira). Define the JIRA server URL: https://<demo>.atlassian.net.

2. In Integration Management, download and install the On-Premise Bridge agent and configure the agent to work with Service Management. Create credentials for the connection.

   On the Endpoints tab, define the endpoint and configure it as described in How to use endpoints. Select REST Executor 1.0 as the endpoint type.

3. In Service Management, define the following user options for an offering:

   • RawOutput. A string which contains the full JSON response. Required: false, Visibility: Agent

   • HttpStatusCode. An HTTP status response of type integer. Required: false, Visibility: Agent
   • Summary. A summary of the issue. Required: true, Visibility: User

   • Description. A description of the issue. Required: true, Visibility: User

   • Issuetype. The category of the issue. Required: false, Visibility: Agent

4. Define an automatic task for the offering, as described in How to build a task/approval plan.

5. Select the Execute REST business rule.

6. For the OPB Agent ID, OPB Endpoint ID and Credentials ID parameters, select the agent, endpoint, and credentials defined in step 2.

7. For the URI Suffix parameter, enter /rest/api/2/issue. For more information, consult the JIRA API documentation.
8. For the Web Method parameter, select POST.

9. For the Body parameter, you can either select Simple mode and enter a static JSON body, or select Expression Language mode and enter a dynamic JSON body.

   Static body example:

       {
       "fields": {
          "project":
          { 
             "key": "YOURDEFECTS"
          },
          "summary": "OPB REST Test 1 ",
          "description": " OPB REST Test 1 - description",
          "issuetype": {
             "name": "Bug"
          }
      }
   }
   

   Dynamic body example:

   ${concat('{"fields": {"project": {"key": "SAWDEFECTS"},"summary":"',	
   entity.UserOptions.Summary_c,'", "description": "',
   entity.UserOptions.Description_c,'","issuetype": {"name": "Bug"}}}')}
   							

   For more information, consult the JIRA API documentation.

10. For the Headers parameter, enter:

    Headers:
    "Accept", "application/json", 
    "Content-Type", "application/json"
    

11. For the Output field name parameter, select User Options.
12. Save the offering.
13. In Service Request Management, create a request based on the offering and run the automatic task.

14. Review the task output and check the user options fields.

Related topics

• Processes and Rules

• Record Management business rules

• Business rule descriptions and tags

• Action rule examples

• Validation rule examples

• Rendering rule examples

• Field selection rule examples

• Record Management - use case

• How to add a business rule

• How to edit, remove, or disable a business rule

• Enrichment rules