This documentation supports the 19.11 version of Remedy Action Request System, which is available only to BMC Helix subscribers (SaaS).
To view an earlier version, select the version from the Product version menu.

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. 

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:

ActionDescription
Task 1 — Select a data sourceSelect the REST API data source.
Task 2 — Select HTTP method and content typeSelect the CRUD operation that you want to perform. Also, select a format to operate.
Task 3 — Define the URIDefine endpoints for the third-party REST API.
Task 4 — Authenticate REST API requestAuthenticate the REST API request by using the supported authentication mechanism.
Task 5 — (Optional) Add customized headerProvide additional header information to the REST API.
Task 6 — Define request response mapping

Send a request to the third-party REST API and map the response to the AR form fields.

Task 7 — (Optional) Add attachment data informationSend or receive attachment data.

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:

    MethodDescription
    GETTo retrieve a resource from the third-party application.
    POSTTo create a resource in the third-party application.
    PUTTo modify a resource in the third-party application.
    DELETETo 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 parametersA 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 Oauth2OAuth2JWT, 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

    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

    KeyValue
    usernameDemo
    passwordDemo123

    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 API
    In this example, as per Twitter requirement, the Client ID and Client Secret are created by using a Twitter development account.

    KeyValue
    TOKEN_AUTH_URI_METHODPOST
    TOKEN_AUTH_URI_PATHhttps://api.twitter.com/oauth2/token
    TOKEN_AUTH_CONTENT_LOCATION_KEYREQUEST_BODY
    TOKEN_AUTH_AUTH_TOKEN_NAMEBearer
    TOKEN_AUTH_REQUEST_MEDIA_TYPEapplication/x-www-form-urlencoded
    AUTH_KEYgrant_typeclient_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.

    KeyValue
    TOKEN_AUTH_URI_METHODPOST
    TOKEN_AUTH_URI_PATHhttps://www.googleapis.com/oauth2/v4/token
    TOKEN_AUTH_CONTENT_LOCATION_KEYREQUEST_BODY
    TOKEN_AUTH_AUTH_TOKEN_NAMEBearer
    TOKEN_AUTH_REQUEST_MEDIA_TYPEapplication/x-www-form-urlencoded
    AUTH_KEYOAUTH2JWT_issmyname@mytestprojects-242213.iam.gserviceaccount.com
    AUTH_KEYOAUTH2JWT_scopehttps://www.googleapis.com/
    auth/calendar.events.readonly
    AUTH_KEYOAUTH2JWT_audhttps://www.googleapis.com/oauth2/v4/token
    AUTH_KEYOAUTH2JWT_exp$Integer Field$
    AUTH_KEYgrant_typeurn:ietf:params:oauth:grant-type:jwt-bearer
    AUTH_KEYOAUTH2JWT_JWT_SECRET_KEY<your private key>
    AUTH_KEYOAUTH2JWT_JWT_TOKEN_ID_KEY_NAMEassertion

    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

    KeyValue
    TOKEN_AUTH_URI_METHODPost
    TOKEN_AUTH_URI_PATHjwt/login
    TOKEN_AUTH_CONTENT_LOCATION_KEYREQUEST_BODY
    TOKEN_AUTH_CONTENT_BODYEnter your user name and password. For example, username=Demo&password=Demo
    TOKEN_AUTH_AUTH_TOKEN_NAMEAR-JWT
    TOKEN_AUTH_REQUEST_MEDIA_TYPEapplication/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

    KeyValue
    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:

Authentication TypeKeyDescription
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, RSSOTOKEN_AUTH_URI_PATH 

URI path for the authentication token request. This changes as per your authentication external service URI.

OAuth2, OAuth2JWT, AR-JWT, RSSOTOKEN_AUTH_CONTENT_LOCATION_KEY

Token authentication content. This comes from the request body.

OAuth2, OAuth2JWT, AR-JWT, RSSOTOKEN_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:

{

  "access_token":"MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",

  "token_type":"bearer",

  "expires_in":3600,

  "refresh_token":"IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk",

  "scope":"create"

}

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:

grant_type=client_credentials&client_id=myclid&client_secret=mysecret

RSSOAUTH_KEYclient_id

Your client ID.

For example, AUTH_KEYclient_id - <your client ID>

RSSOAUTH_KEYclient_secret

Your client secret.

For example, AUTH_KEYclient_secret - <your client secret>

OAuth2,  OAuth2JWT, AR-JWT, and RSSOAUTH_HEADERheader1

Any value

For example: value 1

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:

ParameterValue
TOKEN_AUTH_AUTH_TOKEN_NAMEAR-JWT
TOKEN_AUTH_REQUEST_MEDIA_TYPEapplication/x-www-form-urlencoded
AUTH_HEADERheader1Value1
AUTH_HEADERheader2Value2

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 keyCurrent form nameParent form nameField namePrimary keyForeign keyDistinguishing keyJSON data typeChild array index
    values|LoginNamerestForm
    loginname


    STRINGNULL
    values|Group ListrestForm
    grouplist


    STRINGNULL
    values|StatusrestForm
    Status


    STRINGNULL
    values|Full NamerestForm
    fullname


    STRINGNULL
    values|LicenseTyperestForm
    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 keyCurrent form nameParent form nameField namePrimary keyForeign keyDistinguishing keyJSON data typeChild array index
    values|empnameemployee
    empname


    STRING-1 or NULL
    values|empcompanyemployee
    empcompany


    STRING-1 or NULL
    _embedded|assoc-empoyeeaddressdirect
    |values|addempid
    addressemployeeaddempid
    empidaddempidaddidSTRING1
    values|empcompany
    employee
    empcompany



    STRING-1 or NULL
    _embedded|assoc-empoyeeaddressdirect
    |values|addid
    addressemployeeaddid
    empidaddempidaddidSTRING1
    _embedded|assoc-empoyeeaddressdirect|
    values|adddetail
    addressemployeeadddetailempidaddempidaddidSTRING1
  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 keyCurrent form nameParent form nameField namePrimary keyForeign keyDistinguishing keyJSON data typeChild array index
    values|Login NamerestForm
    loginname


    STRINGNULL
    values|Group ListrestForm
    grouplist


    STRINGNULL
    values|Status History|Current|userrestForm
    shuser



    STRINGNULL
    values|Full NamerestForm
    fullname


    STRINGNULL

    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 keyCurrent form nameParent form nameField namePrimary keyForeign keyDistinguishing keyJSON data typeChild array index
    values|empnameemployee
    empname


    STRING-1 or NULL
    values|empcompanyemployee
    empcompany


    STRING-1 or NULL
    _embedded|assoc-empoyeeaddressdirect|
    values|addempid
    addressemployeeaddempid
    empidaddempidaddidSTRING-1 or NULL
    _embedded|assoc-empoyeeaddressdirect
    |values|addid
    address
    employee
    addidempid
    addempid
    addid
    STRING-1 or NULL
    _embedded|assoc-empoyeeaddressdirect|
    values|adddetail
    addressemployeeadddetail
    empidaddempidaddidSTRING-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. 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 columnDescription
    JSON KeyContext path to the JSON key. Retrieve the value of the JSON key and set it in the AR form. Syntax: value|<JSON key>
    Current FormRequest mapping: The form from where data is retrieved. Response mapping:The form where data is set.
    Parent FormWhen there is a parent-child relationship between forms, specify the parent form of the current form.
    Field NameRequest mapping: Field on the current form from where data is sent. Response mapping: Field on the current form from where data is updated.
    Primary KeyWhen there is a parent-child relationship between form, this is the Field ID on the parent form.
    Foreign KeyWhen 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 KeyWhen 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 IndexWhen 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.

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

JSON keyCurrent form nameParent form nameField name (sorted as ID in database)Primary keyForeign keyDistinguishing keyJSON data typeChild array index
values|
Login Name
restForm
loginname


STRINGNULL
values|
Group List
restForm
grouplist


STRINGNULL
values|Status History|
Current|user
restForm
shuser


STRINGNULL
values|
Full Name
restForm
fullname


STRINGNULL
values|
attach1__
c|name
restForm
attach1__c


STRINGNULL
values|
attach1__
c|sizeBytes
restForm
attach1__c


STRINGNULL
values|
attach1__
c|href
restForm
attach1__c


STRINGNULL

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

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

KeyValueDescription
entryNULL

For part 1: Key = "entry".

This key has a non attachment field JSON data.

attach-attach1__cATTACH_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.

Related topic

Defining workflow to automate processes


Was this page helpful? Yes No Submitting... Thank you

Comments