Calling third-party REST APIs in a Remedy application - Documentation for Remedy Action Request System 19.08
John Castro As a developer, you can call third-party REST APIs to update the Remedy application by using Remedy Developer Studio. You can call third-party REST APIs in a Remedy application, if a third-party application exposes its REST APIs.
You can call third-party REST APIs directly by using a filter having Set Fields action with REST API as a data source. This filter enables you to define a one-time configuration for the third-party REST API that you want to call in Remedy workflows. You can use different HTTP methods such as GET, PUT, POST, or DELETE.
Scenario
Seth, a developer at Calbro Services, needs to collect information about weather, sunrise time, and sunset time in various cities. He decides to use the weather API provided by RapidAPI.
The following diagram depicts the high-level process he performs:
The following video (2:54) describes how to create a filter for calling a third-party REST API to update a Remedy application.
Before you begin
Ensure that:
- The third-party application has exposed its REST APIs.
- You must have complete knowledge about the third-party REST services such as authentication mechanism, headers, endpoints, and parameters.
- If you plan to use Oauth2, OAuth2JWT, or RSSO authentication method, you must perform necessary steps such as creating client ID, creating client secret, depending on the requirement of the third-party application.
- Create a new filter with Set Field action.
Process of calling third-party REST API in a Remedy application
To call a third-party REST API, create a Set Fields action with REST API as the data source. You can send or can receive data from a third-party application. The Set Fields filter action invokes the REST service.
The following diagram depicts the process flow of calling a third-party REST API in a Remedy application:
The following table describes the process of calling the third-party REST API in a Remedy application:
Task 1—To a select a data source
- Select the filter that you have created and expand the Other Definitions panel.
- Expand the If actions panel.
- Expand the Set Fields REST API | Get panel.
- From the Data Source list, select REST API.
Task 2 — To select HTTP method and content type
- Expand the HTTP Method and Content Type panel.
From the HTTP Method list, select a method from the following options:
Method Description GET To retrieve a resource from the third-party application. POST To create a resource in the third-party application. PUT To modify a resource in the third-party application. DELETE To delete a resource from the third-party application. From the Content-Type list, select application/json.
Currently, we support only the application/json Content Type.
Task 3 — To define the URI
The URI is composed of the Base URL (that includes protocol, server name, and port), resource path (/v1/employees), and query parameters. A question mark is added after appending the base URL and the resource path.
For example, .
Before adding URI, Path parameters, or query parameters, ensure to complete the HTTP encoding.
Perform the following steps to define URI:
- Expand the URI, Path and Query Params panel.
- In the Base URI: field, enter the base URL of the third-party application.
For example: - (Optional) In the Path Params field, enter the path parameters for the base URL.
You can combine the path parameters with the base URL. Path parameter creates an endpoint URL.
For example: /v1/employees - (Optional) To enter the key-value pair for the query parameters, In the Query Params table, click Add.
These parameters are passed as a part of your request.
Task 4 — To configure authentication information
Expand the Authentication panel.
You must know the authentication method, which the third-party application supports.
For Oauth2, OAuth2JWT, and RSSO authentication types, the AR System server communicates with an external server. The logic is triggered through a workflow. The workflow shares the admin context to the AR application. Therefore, no user context is involved in such external calls.
From the Type list, select an authentication method.
(Optional) If you are setting authentication method to retrieve attachment data from a third-party application, you must specify the authentication URL by using the absolute path.
For example,You must know the authentication keys for a specific authentication type that the third-party application supports.
Authentication options
NOAUTH
No authentication required. In the Auth Parameters table, do not enter any authentication parameter.
BASIC
This method authenticates by using the user name and password.
In the Auth Parameters table, enter the user name and password as keys and define values.
Example of Basic authentication
Key Value username Demo password Demo123 OAuth2
This method fetches a token from a third-party authentication server by using OAuth2 parameters. If the token expires, the AR System server automatically fetches a new token. You can use the token to access a third-party REST resource.
In the Auth Parameters table, enter the authentication keys and values applicable for the OAuth2 authentication.
Example of authenticating Twitter APIKey Value TOKEN_AUTH_URI_METHOD POST TOKEN_AUTH_URI_PATH TOKEN_AUTH_CONTENT_LOCATION_KEY REQUEST_BODY TOKEN_AUTH_AUTH_TOKEN_NAME Bearer TOKEN_AUTH_REQUEST_MEDIA_TYPE application/x-www-form-urlencoded AUTH_KEYgrant_type client_credentials AUTH_KEYusername <your client ID> AUTH_KEYpassword <your client secret> In this example, as per Twitter requirement, the Client ID and Client Secret are created by using a Twitter development account.
OAuth2JWT
This authentication method enables login access to a third-party application without exposing user account credentials and information.
In the Auth Parameters table, enter the authentication keys and values applicable for the OAuth2JWT authentication.
Example of fetching a token from Google APIKey Value TOKEN_AUTH_URI_METHOD POST TOKEN_AUTH_URI_PATH TOKEN_AUTH_CONTENT_LOCATION_KEY REQUEST_BODY TOKEN_AUTH_AUTH_TOKEN_NAME Bearer TOKEN_AUTH_REQUEST_MEDIA_TYPE application/x-www-form-urlencoded AUTH_KEYOAUTH2JWT_iss AUTH_KEYOAUTH2JWT_scope
auth/calendar.events.readonlyAUTH_KEYOAUTH2JWT_aud AUTH_KEYOAUTH2JWT_exp $Integer Field$ AUTH_KEYgrant_type urn:ietf:params:oauth:grant-type:jwt-bearer AUTH_KEYOAUTH2JWT_JWT_SECRET_KEY <your private key> AUTH_KEYOAUTH2JWT_JWT_TOKEN_ID_KEY_NAME assertion In this example, as per Google's requirement, other parameters apart from Client ID and Client Secret are created.
AR-JWT
The AR System server performs authentication mechanisms to validate the credentials of a token. If the credentials are valid, the AR System server generates a JSON Web Token (JWT). You can use the token to access a Remedy REST resource.
In the Auth Parameters table, enter the authentication keys and values applicable for the AR-JWT authentication.
Example of key value pair for AR-JWT authenticationKey Value TOKEN_AUTH_URI_METHOD Post TOKEN_AUTH_URI_PATH jwt/login TOKEN_AUTH_CONTENT_LOCATION_KEY REQUEST_BODY TOKEN_AUTH_CONTENT_BODY Enter your user name and password. For example, username=Demo&password=Demo TOKEN_AUTH_AUTH_TOKEN_NAME AR-JWT TOKEN_AUTH_REQUEST_MEDIA_TYPE application/x-www-form-urlencoded Remedy Single Sign-On (RSSO) is an authentication system that supports SAML V2.0 and Remedy Action Request System authentication protocols and provides single sign-on and single sign-off for users of BMC products.
In the Auth Parameters table, enter the authentication keys and values applicable for the RSSO authentication.
Example of key value pair for RSSO authenticationKey Value TOKEN_AUTH_URI_METHOD POST TOKEN_AUTH_URI_PATH TOKEN_AUTH_CONTENT_LOCATION_KEY Request body TOKEN_AUTH_AUTH_TOKEN_NAME Bearer TOKEN_AUTH_REQUEST_MEDIA_TYPE application/x-www-form-urlencoded AUTH_KEYclient_id <your client ID> AUTH_KEYclient_secret <your client secret> AUTH_KEYusername QATEST In the Auth Parameters table, click Add to add the authentication parameters.
Refer to the following table to see the details about the key value pair used in authentication:
| Authentication Type | Key | Description |
|---|---|---|
| OAuth2, OAuth2JWT, AR-JWT, RSSO | TOKEN_AUTH_URI_METHOD | The authentication token request. The request can be for GET, POST, PUT, or DELETE method. |
| OAuth2, OAuth2JWT, AR-JWT, RSSO | TOKEN_AUTH_URI_PATH | URI path for the authentication token request. This changes as per your authentication external service URI. |
| OAuth2, OAuth2JWT, AR-JWT, RSSO | TOKEN_AUTH_CONTENT_LOCATION_KEY | Token authentication content. This comes from the request body. |
| OAuth2, OAuth2JWT, AR-JWT, RSSO | TOKEN_AUTH_AUTH_TOKEN_NAME | Once you get the successful token response, you must obtain the token from the response field. For example, if you obtain the toe from Okta, it is access_token. If you obtain the token from Twitter, it is Bearer. For more information about the standard authentication mechanism, see Client Credentials The Okta response is as follows:
|
| OAuth2, OAuth2JWT, | AUTH_KEYgrant_type | Client credentials. The string after AUTH_KEY is considered and the corresponding value is a part of request body. For example: Twitter — userid, password Okta — client_id, client_secret The example of response body is as follows:
|
| RSSO | AUTH_KEYclient_id | Your client ID. For example, |
| RSSO | AUTH_KEYclient_secret | Your client secret. For example, |
- Expand the Custom Header panel.
- To add request header, in the Custom Headers table, click Add.
These headers send an additional information to the third- party REST API.
This can be any custom header.
Task 6 — To define request response mapping
- Expand the Request/Response panel.
- Expand the Static Body panel.
- (Optional) In the Static Body panel, enter any static request that needs to be sent in the HTTP request.
Static body value can be derived dynamically from the field value on the form.
Request mapping takes precedence over Static Body. - Expand the Request Mapping panel.
This panel enables you to send data from the AR form field and receive a JSON response. To add fields from the AR form, in the Request Mapping table, click Add.
For information about populating the Request Mapping table, see the following examples:
Example of creating a JSON to update the third-party application by using PUT or POST method:
Request mapping:JSON key Current form name Parent form name Field name Primary key Foreign key Distinguishing key JSON data type Child array index values|LoginName restForm loginname STRING NULL values|Group List restForm grouplist STRING NULL values|Status restForm Status STRING NULL values|Full Name restForm fullname STRING NULL values|LicenseType restForm License Type Example of creating a JSON by using the PUT and POST method by using the parent-child relationship to fetch data from multiple forms.
Sample input JSON{ "values": { "Request ID": "000000000000002", "Submitter": "b", "Create Date": "2019-06-04T04:33:45.000+0000", "Assigned To": "b", "Last Modified By": "Demo", "Modified Date": "2019-06-04T04:33:45.000+0000", "Status": "New", "Short Description": "b", "Status History": { "New": { "user": "Demo", "timestamp": "2019-06-04T04:33:45.000+0000" } }, "empid": "2", "empname": "doug", "empcompany": "wipro" }, "_links": { "self": [ { "href": "" } ] }, "_embedded": { "assoc-empoyeeaddressdirect": [ { "values": { "Request ID": "000000000000001", "Submitter": "a", "Create Date": "2019-06-04T04:36:44.000+0000", "Assigned To": null, "Last Modified By": "Demo", "Modified Date": "2019-06-04T04:36:44.000+0000", "Status": "New", "Short Description": "a", "Status History": { "New": { "user": "Demo", "timestamp": "2019-06-04T04:36:44.000+0000" } }, "addempid": "2", "addid": "add2", "adddetail": "address2" }, "_links": { "self": [ { "href": "" } ] } }Request mapping
JSON key Current form name Parent form name Field name Primary key Foreign key Distinguishing key JSON data type Child array index values|empname employee empname STRING -1 or NULL values|empcompany employee empcompany STRING -1 or NULL _embedded|assoc-empoyeeaddressdirect
|values|addempidaddress employee addempid empid addempid addid STRING 1 values|empcompany employee empcompany STRING -1 or NULL _embedded|assoc-empoyeeaddressdirect
|values|addidaddress employee addid empid addempid addid STRING 1 _embedded|assoc-empoyeeaddressdirect|
values|adddetailaddress employee adddetail empid addempid addid STRING 1 The primary key is fetched from the parent form. In this case, empid is the primary key in the parent form. The foreign key in the current form is matched against the primary key of the parent form. When you get data from JSON, the distinguishing key determines the entries to create, update, or delete from the database.
Expand the Response Mapping panel.
This panel enables you to send a JSON request and receive data for AR form fields.To add fields from the JSON file, in the Response Mapping table, click Add.
For information about populating the Response Mapping table, see the following examples:
Example of using GET method to fetch data in the AR form fields.
This example fetches data from a User form of a third-party application and populates information in the restForm of the Remedy application.{ "values": { "Request ID": "000000000000201", "Creator": "Demo", "Create Date": "2019-05-13T05:13:26.000+0000", "Assigned To": null, "Last Modified By": "Demo", "Modified Date": "2019-05-13T05:13:26.000+0000", "Status": "Current", "Full Name": "Demo1", "Status History": { "Current": { "user": "Demo", "timestamp": "2019-05-13T05:13:27.000+0000" } }, "Login Name": "Demo1", "Password": "***", "Email Address": null, "Group List": "1;", "Default Notify Mechanism": "Alert", "License Type": "Fixed", "Full Text License Type": "None", "Computed Grp List": null, "Application License": null, "Force Password Change On Login": null, "Last Password Change For Policy": null, "Number of Warning Days": null, "No. Days Before Expiration": null, "zDays Left Before Expiration": null, "Account Disabled Date": null, "Disable Password Management": null, "Days After Expiration Until Disablement": null, "Unique Identifier": "AGGAA5V0HGVRNAPR55U4PQ8BW1WS4K", "Dynamic Group Access": "'Demo1';", "Datatag": null, "Applied PasswordEnforcementEnabled": null, "Applied Number of Warning Days": null, "Applied No. Days before Expiration": null, "Applied Days After Expiration Until Disablement": null, "Applied New User Must Change Password": null, "zPush From Config No Set": null, "Allowed Client Types": null, "z1D_Service": null, "Instance ID": null, "Object ID": null }, "_links": { "self": [ { "href": "" } ] }Response mapping
JSON key Current form name Parent form name Field name Primary key Foreign key Distinguishing key JSON data type Child array index values|Login Name restForm loginname STRING NULL values|Group List restForm grouplist STRING NULL values|Status History|Current|user restForm shuser STRING NULL values|Full Name restForm fullname STRING NULL Example of using PUT method to retrieve data from JSON response and set it in an AR form that has parent-child relationship:
Response mappingJSON key Current form name Parent form name Field name Primary key Foreign key Distinguishing key JSON data type Child array index values|empname employee empname STRING -1 or NULL values|empcompany employee empcompany STRING -1 or NULL _embedded|assoc-empoyeeaddressdirect|
values|addempidaddress employee addempid empid addempid addid STRING -1 or NULL _embedded|assoc-empoyeeaddressdirect
|values|addidaddress employee addid empid addempid addid STRING -1 or NULL _embedded|assoc-empoyeeaddressdirect|
values|adddetailaddress employee adddetail empid addempid addid STRING -1 or NULL The primary key is fetched from the parent form. In this case, empid is the primary key in the parent form. The foreign key in the current form is matched against the primary key of the parent form. When you get data in AR form, the distinguishing key determines the entries to create, update, or delete from the database.
Note
If you set parent-child relationship by using data in the JSON Array node, the array elements use the same flow of events. However, if you perform a simple mapping to a key residing in a JSON array and if multiple child nodes are present in that JSON array node, then the AR System server concatenates all child key node values and produces a string that is mapped as a single mapping element. The #ARRAYSEP# string is used as a delimiter string.
The following table describes the columns of request and response mapping table:
Table column Description JSON Key Context path to the JSON key. Retrieve the value of the JSON key and set it in the AR form. Syntax: value|<JSON key>Current Form Request mapping: The form from where data is retrieved. Response mapping:The form where data is set. Parent Form When there is a parent-child relationship between forms, specify the parent form of the current form. Field Name Request mapping: Field on the current form from where data is sent. Response mapping: Field on the current form from where data is updated. Primary Key When there is a parent-child relationship between form, this is the Field ID on the parent form. Foreign Key When there is a parent-child relationship between form, this is the Field ID on the current form. The value of foreign key is matched against the value of the designated primary key in the parent form. Distinguishing Key When there is a parent-child relationship between form, this is the unique key to find the child record to be created, updated, or deleted. JSON Type Request mapping: Defines the value of response JSON.
Response mapping: Not applicable.
Child Array Index When there is a parent-child relationship between form, Child Array Index starts the child array element. Important
You can use dynamic field values in all fields except for the JSON key in the request response mapping.
Task 7 — (Optional) To add attachment data information
- Expand the Multipart Info panel.
The Multipart information panel enables you to send the attachment data from the AR form attachment fields to a third-party application and to fetch attachment data from a third-party application and store them in the AR form attachment field. - To add an attachment, in the Multipart Info table, click Add.
The attachment data is in binary format.
Response mapping for attachment data
The response contains the following:
- (Optional) Attachment field file name
- (Optional) Size
- Attachment URL to external system
When you set the response mapping for attachment data, you must use attributes in the given order. If you do not want to set the optional attributes, you must assign keys to a non-existent node. You must assign existent and non-existent nodes to the response mapping.
Example of attachment field for response mapping
| JSON key | Current form name | Parent form name | Field name (sorted as ID in database) | Primary key | Foreign key | Distinguishing key | JSON data type | Child array index |
|---|---|---|---|---|---|---|---|---|
| values| Login Name | restForm | loginname | STRING | NULL | ||||
| values| Group List | restForm | grouplist | STRING | NULL | ||||
| values|Status History| Current|user | restForm | shuser | STRING | NULL | ||||
| values| Full Name | restForm | fullname | STRING | NULL | ||||
| values| attach1__ c|name | restForm | attach1__c | STRING | NULL | ||||
| values| attach1__ c|sizeBytes | restForm | attach1__c | STRING | NULL | ||||
| values| attach1__ c|href | restForm | attach1__c | STRING | NULL |
Request mapping for attachment data
Consider the following points when you perform request mapping for attachment data:
- The AR System server sends data from an attachment field in multiple parts.
- The first part is the JSON for the non-attachment field type.
- The subsequent parts are binary attachment data.
- The parts are separated by using keys.
- We support the content disposition only for form data.
- We do not support child form attachment entries for the parent-child relationship.
Example of attachment field for request mapping
JSON
--W3NByNRZZYy4ALu6xeZzvWXU3NVmYUxoRB
Content-Disposition: form-data; name="entry" /** part 1 - with key as name="entry" **/
Content-Type: application/json; charset=UTF-8
Content-Transfer-Encoding: 8bit
{ /** JSON data always in 1st part **/
"values" :
{ "Submitter" :"Allen", "Short Description" : "testing 123", "Attachment1" : "sample.jpg"
}
}
--W3NByNRZZYy4ALu6xeZzvWXU3NVmYUxoRB
Content-Disposition: form-data; /** part 2 - with key as name = "attach-Attachment1" **/
name="attach-Attachment1"; filename="sample.png"
Content-Type: application/octet-stream
Content-Transfer-Encoding: binary
<binary data removed for brevity> /** actual attachment datafor 1st field **/
--W3NByNRZZYy4ALu6xeZzvWXU3NVmYUxoRB--Adding an attachment
| Key | Value | Description |
|---|---|---|
| entry | NULL | For part 1: Key = " This key has a non attachment field |
| attach-attach1__c | ATTACH_FIELD_KEY:536870922 #MULTSEP#ATTACH_HEADER_ DATA_TYPE :application/octet-stream #MULTSEP #Content-Transfer-Encoding:binary | For subsequent parts such as part 2, part 3: The first part of the key ATTACH_FIELD_KEY is separated by the Field ID. The next keys are the headers for subparts. Each subpart is separated by using the #MULTSEP# word. The first subpart key ATTACH_FIELD_KEY is separated by its field IDs. The subsequent keys are headers for subparts. Every subpart is separated with a special word #MULTSEP#. Repeat this for the number of attachment fields data that needs to be sent in a JSON request. |
For more information about attachment handling, see the knowledge article Handling attachments 
.
For information about troubleshooting the issues that might occur while calling a third-party REST API, see Troubleshooting issues when calling a third-party REST API.
