Calling third-party REST APIs in a Remedy application

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. 

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

1. Select the filter that you have created and expand the Other Definitions panel.
2. Expand the If actions panel.
3. Expand the Set Fields REST API | Get panel.
4. From the Data Source list, select REST API.
   
   
   

Task 2 — To select HTTP method and content type

1. Expand the HTTP Method and Content Type panel.

2. 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.

3. 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, http://dummy.restapiexample.com/v1/employees?paramName1=value1¶mName2=value2.

Before adding URI, Path parameters, or query parameters, ensure to complete the HTTP encoding.

Perform the following steps to define URI:

1. Expand the URI, Path and Query Params panel.
2. In the Base URI: field, enter the base URL of the third-party application. 
   For example: http://dummy.restapiexample.com
3. (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
4. (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.
   

You can use the URL-Safe-Encode command to encode the special characters in the URL. For more information, see URL- Safe-Encode command.

Task 4 — To configure authentication information

1. 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.

2. 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, https://api.twitter.com/oauth2/token
   • You must know the authentication keys for a specific authentication type that the third-party application supports.

   Authentication options

   • NOAUTH
   • BASIC
   • OAuth2
   • OAuth2JWT
   • AR-JWT
   • RSSO

   NOAUTH

   No authentication is 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.

   The following example shows key-value pair required for Twitter. You can use this framework as per your requirement.
   In the Auth Parameters table, enter the authentication keys and values applicable for the OAuth2 authentication.

   
   Example of authenticating Twitter API
   In this example, as per Twitter requirement, the Client ID and Client Secret are created by using a Twitter development account.

   Key	Value
   TOKEN_AUTH_URI_METHOD	POST
   TOKEN_AUTH_URI_PATH	https://api.twitter.com/oauth2/token
   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>

   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 API
   In this example, as per Google's requirement, other parameters apart from Client ID and Client Secret are created.

   Key	Value
   TOKEN_AUTH_URI_METHOD	POST
   TOKEN_AUTH_URI_PATH	https://www.googleapis.com/oauth2/v4/token
   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	myname@mytestprojects-242213.iam.gserviceaccount.com
   AUTH_KEYOAUTH2JWT_scope	https://www.googleapis.com/ auth/calendar.events.readonly
   AUTH_KEYOAUTH2JWT_aud	https://www.googleapis.com/oauth2/v4/token
   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

   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 authentication

   Key	Value
   TOKEN_AUTH_URI_METHOD	Post
   TOKEN_AUTH_URI_PATH	http://<hostname>:port/api/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

   
   

   RSSO
   

   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 authentication

   Key	Value
   TOKEN_AUTH_URI_METHOD	POST
   TOKEN_AUTH_URI_PATH	http://servername:8080/rsso/oauth2/token
   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

3. 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:

Adding additional header for token-based authentication

You can add a custom header for token-based authentication, such as OAuth2,  OAuth2JWT, AR-JWT, and RSSO. The AUTH_HEADER parameter enables you to pass authentication information. The string after AUTH_HEADER is passed to the header name and value is the value portion in the header.

Refer to the following AR-JWT authentication example:

Additional parameters for calling a third-party REST API through a proxy server

Use the following parameters to make a call to proxy server:

Keys supported by different authentication types

The keys are case-sensitive. The following table describes the list of valid keys supported by different REST API authentication types:

Task 5 — (Optional) To add customized header

1. Expand the Custom Header panel.
2. 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

1. Expand the Request/Response panel.
2. Expand the Static Body panel.
3. (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.
   
   
4. Expand the Request Mapping panel.
   This panel enables you to send data from the AR form field and receive a JSON response.  
   

5. 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 the 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 or POST method. Use 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": "http://clm-pun-023265:8008/api/arsys/v1/entry/employee/000000000000002"
   }
   ]
   },
   "_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": "http://clm-pun-023265:8008/api/arsys/v1/entry/address/000000000000001"
   }
   ]
   }
   }

   Request mapping
   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.

   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|addempid	address	employee	addempid	empid	addempid	addid	STRING	1
   values|empcompany	employee		empcompany				STRING	-1 or NULL
   _embedded|assoc-empoyeeaddressdirect |values|addid	address	employee	addid	empid	addempid	addid	STRING	1
   _embedded|assoc-empoyeeaddressdirect| values|adddetail	address	employee	adddetail	empid	addempid	addid	STRING	1

6. Expand the Response Mapping panel. 
   This panel enables you to send a JSON request and receive data for AR form fields.
   

7. 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 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": "http://clm-pun-023844:8008/api/arsys/v1/entry/User/000000000000201"
   }
   ]
   }

   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 mapping
   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.

   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|addempid	address	employee	addempid	empid	addempid	addid	STRING	-1 or NULL
   _embedded|assoc-empoyeeaddressdirect |values|addid	address	employee	addid	empid	addempid	addid	STRING	-1 or NULL
   _embedded|assoc-empoyeeaddressdirect| values|adddetail	address	employee	adddetail	empid	addempid	addid	STRING	-1 or NULL

   Note

   If you set parent-child relationship by using data in the JSON Array node, the array elements use the same flow of events. For information about building a simple JSON with an array, see the knowledge article Send POST request to third-party REST API. 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

1. 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.
   

1. 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:

1. (Optional) Attachment field file name
2. (Optional) Size
3. 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 attaching field for response mapping

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 attaching field for request mapping

JSON

Adding an attachment

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.

Enabling two-way SSL support for AR System REST API

When calling a AR System REST API, you can upload server certificate and Public or Private key into the truststore and Keystore.  Before using two-way SSL support, make sure that the Base URI and the Authentication URI use the HTTPS protocol. 

The following table lists the authentication parameters you use for the two-way SSL support. These parameters are applicable for all authentication types.

Example: Enabling two-way SSL when calling a AR System REST API

1. In the jetty-http.xml file, located in the /opt/bmc/ars/jetty/etc folder, uncomment HTTPS section.
2. Add the following parameters in the jetty-http.xml file.
   • <Set name="NeedClientAuth">true</Set>

   • <Set name="EndpointIdentificationAlgorithm"></Set>
     See the example: 

     <New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory">
     <Set name="KeyStorePath">C:\mykeystore\keystore.jks</Set>
     <Set name="KeyManagerPassword">test1234</Set>
     <Set name="KeyStorePassword">test1234</Set>
     <Set name="TrustStorePath">C:\mykeystore\keystore.jks</Set>
     <Set name="TrustStorePassword">test1234</Set>
     
     <!-- new parameters for 2 way SSL -->
     <Set name="NeedClientAuth">true</Set>
     <Set name="EndpointIdentificationAlgorithm"></Set>
3. Create a self-signed certificate with different passwords for clients, such as client.jks and server, such as server.jks. For more information about creating self-signed certificates, see Configuring-the-REST-API-by-using-SSL-certificates.
4. Place both certificates in a folder.
   For example, c:\\mystore\.

5. Update the jetty-http.xml file as shown in the example below:

   <New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory">
       [Specify Server Certificate in Keystore]
                 <Set name="KeyStorePath">C:\\mykeystore\\server.jks</Set>
                 <Set name="KeyManagerPassword">123</Set>
      <Set name="KeyStorePassword">123</Set>
                  [Specify Client Certificate in Truststore]
      <Set name="TrustStorePath">C:\\mykeystore\\client.jks</Set>
      <Set name="TrustStorePassword">secret</Set>
                 <Set name="NeedClientAuth">true</Set>
      <Set name="EndpointIdentificationAlgorithm"></Set>

6. Modify the default value as shown in the example below:

   <Arg name="sniHostCheck" type="boolean"><Property name="jetty.ssl.sniHostCheck" default="false"/></Arg>
7. Open Filter set field option for the REST API Data Source and add or update the following details:
   • BASE URI :https://<hostname>:8443/api/
   • Authentication - Type (AR-JWT)
   • TOKEN_AUTH_URI_METHOD: POST
   • TOKEN_AUTH_URI_PATH:jwt/login
   • TOKEN_AUTH_CONTENT_LOCATION_KEY: REQUEST_BODY
   • TOKEN_AUTH_CONTENT_BODY:username=Demo&password=xyz123
   • TOKEN_AUTH_AUTH_TOKEN_NAME: AR-JWT
   • TOKEN_AUTH_REQUEST_MEDIA_TYPE: application/x-www-form-urlencoded
   • USE_STRICT_SSL: true
   • KEYSTORE_LOCATION: C:\\mykeystore\\client.jks
     This is the client configuration. Add client certificate in its keystore.
   • KEYSTORE_SCRT: secret
   • TRUSTSTORE_LOCATION: C:\\mykeystore\\server.jks
   • TRUSTSTORE_SCRT: 123
8. Perform response mapping as per your requirement. For more information see, Defining request and response mapping.

After the steps are complete, create a record on a form and modify it. The GET call triggers.

Related topic

Defining-workflow-to-automate-processesHow to get an attachment from a third-party Webservice