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

Related topics

Defining workflow to automate processes

How to get an attachment from a third-party Webservice knowledge article in BMC Community

Example

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:

image2019-8-28_9-1-51.png

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 Oauth2OAuth2JWT, 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.
  • A new filter with Set Field action is created. 

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:

image2019-8-16_14-19-27.png

The following table describes the process of calling the third-party REST API in a Remedy application:

Action

Description

Select the REST API data source.

Select the CRUD operation that you want to perform. Also, select a format to operate.

Define endpoints for the third-party REST API.

Authenticate the REST API request by using the supported authentication mechanism.

Provide additional header information to the REST API.

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

Send 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.
    REST1.png


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.

    HTTP-Method.png

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, 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.
    QryParams.png

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

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.

    Basic_auth.png
    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.

    OAuth2.png
    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.
    Oauth2JWT.png
    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.

    AR-JWT.png
    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

    BMC Helix Single Sign-On (RSSO) is an authentication system that supports SAML V2.0 and 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.

    RSSO.png
    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

    AUTH_KEYuser_assertion_key

    <Your user assertion key value>

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

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

RSSO

AUTH_KEYclient_id

Your client ID.

For example, AUTH_KEYclient_id - <your client ID>

RSSO

AUTH_KEYclient_secret

Your client secret.

For example, AUTH_KEYclient_secret - <your client secret>

OAuth2,  OAuth2JWT, AR-JWT, and RSSO

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

Parameter

Value

TOKEN_AUTH_AUTH_TOKEN_NAME

AR-JWT

TOKEN_AUTH_REQUEST_MEDIA_TYPE

application/x-www-form-urlencoded

AUTH_HEADERheader1

Value1

AUTH_HEADERheader2

Value2

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

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

Parameter

Value

PROXY_HOST

http(s)://host_server_name

PROXY_PORT

8008

PROXY_USER

(Optional) User name of the proxy server

PROXY_PASSWORD

(Optional) Password of the 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:

Authentication type

Valid key

Basic

username

password

OAuth2

TOKEN_AUTH_URI_METHOD

TOKEN_AUTH_URI_PATH

TOKEN_AUTH_CONTENT_LOCATION_KEY

TOKEN_AUTH_AUTH_TOKEN_NAME

TOKEN_AUTH_REQUEST_MEDIA_TYPE

AUTH_KEYgrant_type

AUTH_KEYusername

AUTH_KEYpassword

OAuth2JWT

TOKEN_AUTH_URI_METHOD

TOKEN_AUTH_URI_PATH

TOKEN_AUTH_CONTENT_LOCATION_KEY

TOKEN_AUTH_AUTH_TOKEN_NAME

TOKEN_AUTH_REQUEST_MEDIA_TYPE

AUTH_KEYOAUTH2JWT_iss

AUTH_KEYOAUTH2JWT_scope

AUTH_KEYOAUTH2JWT_aud

AUTH_KEYOAUTH2JWT_exp

AUTH_KEYgrant_type

AUTH_KEYOAUTH2JWT_JWT_SECRET_KEY

AUTH_KEYOAUTH2JWT_JWT_TOKEN_ID_KEY_NAME

AR-JWT

TOKEN_AUTH_URI_METHOD

TOKEN_AUTH_URI_PATH

TOKEN_AUTH_CONTENT_LOCATION_KEY

TOKEN_AUTH_CONTENT_BODY

TOKEN_AUTH_AUTH_TOKEN_NAME

TOKEN_AUTH_REQUEST_MEDIA_TYPE

RSSO

TOKEN_AUTH_URI_METHOD 

TOKEN_AUTH_URI_PATH

TOKEN_AUTH_CONTENT_LOCATION_KEY

TOKEN_AUTH_AUTH_TOKEN_NAME

TOKEN_AUTH_REQUEST_MEDIA_TYPE

AUTH_KEYclient_id 

AUTH_KEYclient_secret 

AUTH_KEYusername 

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.  
    Custom-header.png

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.  
    request-mapping-date-time.PNG
  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.
    response-mapping-date-time.PNG

  7. (Optional) To add response headers in the Response Mapping table, click Add.
    Response_header.png
    For information about populating the Response Mapping table for response headers, see the following example:
    Example - Using GET method to fetch data in form fields.

    Here, the response header location is mapped to the resourceLink field on the restForm form to fetch the resource location and the response header server is mapped to the serverName field on the form. 

    {
    "Content-type": "application/json;charset=utf-8",
    "location": "https://example.com/eapi/v1/123",
    "server": "EDS001KS2",
    "Cache-Control": "no-cache"
    }

    Response header mapping

    JSON Key

    Current form name

    Parent form name 

    Field name

    Primary key

    Foreign key

    Distinguishing key

    JSON data type

    Child array index

    @HEADER@location

    restForm


    resourceLink




    STRING

    NULL

    @HEADER@server

    restForm


    serverName




    STRING

    NULL

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

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

    Valid values:

    • INTEGER(1)
    • STRING(2)
    • NULL(3)
    • NUMERIC(4)
    • ARRAY_OF_BOOLEAN(10)
    • ARRAY_OF_INTEGER(11)
    • ARRAY_OF_STRING(12)
    • ARRAY_OF_NULL(13)
    • ARRAY_OF_NUMERIC(14)

    Response mapping: Not applicable.

    Child Array Index

    When there is a parent-child relationship between form, Child Array Index starts the child array element.

    Date/Time Format

    In this column, you can specify the format in which the information from the Date/Time field is to be sent out of a Remedy application. For example, yyyy-MM-dd'T'HH:mm:ss.SSSZ. If you don't specify any format, the default format is used to send the date and time information. Also, if you set any invalid format in Remedy Developer Studio, the default date and time format is used.

    You can use dynamic field values in all fields except for the JSON key in the request response mapping.

Send multiple responses from one field

If you have a character field as source field, you can send multiple responses from one field without defining parent-child relationship by using one of the following JSON Types:

  • ARRAY_OF_BOOLEAN(10)
  • ARRAY_OF_INTEGER(11)
  • ARRAY_OF_STRING(12)
  • ARRAY_OF_NULL(13)
  • ARRAY_OF_NUMERIC(14)

When you define these values, the AR System server splits the values based on comma and creates an element of array.
For example, the Address field contains multiple values, such as, House number, Street, Postal Code. To fetch all values, define ARRAY_OF_STRING(12) JSON Type for the Address field. The AR System server returns a comma separated list of values available for the Address field.

Important

  • If the field value contains comma (,) and you want to treat the comma as a literal comma, prefix the comma with backslash (\).
    For example, Street number \, Postal code
  • If the REST API response takes longer time, update the value of the Outbound-Http-Client-Read-Timeout parameter by using the Centralized Configuration.


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.
    Multipart-info.png
  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. 

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.
--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 = "entry".

This key has a non attachment field JSON data.

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 Knowledge Article number 000199341 (Support logon ID required).

Sending text field values by using the Multipart Info panel

The Multipart Info panel also supports form field values. You can send a form field along with attachments to a third-party REST API. However, the Multipart Info panel does not support the Parent-child relationship between forms.

The following code sample shows sending a field value (table_name=Incident) along with an attachment (SampleTest.txt). This generates a multipart payload with both, the field and the attachment.

--Boundary_22_1819824054_1659743653382
Content-Type: application/json
Content-Disposition: form-data; name="entry"

{"file1":"SampleTest.txt"}
--Boundary_22_1819824054_1659743653382
content-disposition: form-data; name="table_name"

Incident
--Boundary_22_1819824054_1659743653382
Content-Transfer-Encoding: binary
Content-Type: application/octet-stream
Content-Disposition: form-data; filename="SampleTest.txt"; name="uploadFile"

Sample Test1
Sample Test2
Sample Test3
--Boundary_22_1819824054_1659743653382

Adding attachment by using static body and content type in the custom header

You can add attachments by using static body section and specifying the content type in the custom header section.
The following screenshot shows an attachment added to Statis Body with 536870914 Field ID:

Attachment-REST-API.png

The Content Type must have  a value if you want to send an attachment through Static Body by using the format given in the example.
Example: ATTACHMENTDATA(536870914)

For Custom Headers, you can obtain the value of Content-Type from a sample Postman request.

If you add an attachment by using the Static Body, do not enter attachment details in the Multipart Info panel. The attachment details in the Multipart Info panel takes precedence over the information added in the Static Body.

Enabling two-way SSL support for BMC Helix Innovation Suite REST API 

When calling a BMC Helix Innovation Suite 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.

Key

Example

Description

USE_STRICT_SSL

true

Enable two-way SSL support.

KEYSTORE_LOCATION

c:\\mystore\newstore

Your keystore location.

KEYSTORE_SCRT

secret

Your keystore secret value.

TRUSTSTORE_LOCATION

c:\\mystore\newtruestore

Your truestore location.

TRUSTSTORE_SCRT

123

Your truestore secret value.

CLIENT_ALIAS

demo123

Alias for the certificate.

STORE_TYPE

jks or pkcs12

Store types you use.

Important

When you enable two-way SSL for a third-party REST API, you must import the client certificate in your truststore. Also, the client(REST API) must import the end-point certificate in the truststore. For more information, see Configuring REST API for HTTPS connection

Example: Enabling two-way SSL when calling a BMC Helix Innovation Suite 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 client, such as client.jks and server, such as server.jks. 
  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.


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.