Calling third-party REST APIs in a Remedy application
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.
- 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:
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
- 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, 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:
- Expand the URI, Path and Query Params panel.
- In the Base URI: field, enter the base URL of the third-party application.
For example: http://dummy.restapiexample.com - (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.
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
- 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, 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 authenticationKey
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.readonlyAUTH_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 authenticationKey
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
RSSOBMC 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.
Example of key value pair for RSSO authenticationKey
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>
- (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.
- 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
- 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 the PUT or POST method
Request mappingJSON 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|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
- Expand the Response Mapping panel.
This panel enables you to send a JSON request and receive data for AR form fields. (Optional) To add response headers in the Response Mapping table, click Add.
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
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|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
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.
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.
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| | restForm | loginname | STRING | NULL | ||||
values| | restForm | grouplist | STRING | NULL | ||||
values|Status History| | restForm | shuser | STRING | NULL | ||||
values| | restForm | fullname | STRING | NULL | ||||
values| | restForm | attach1__c | STRING | NULL | ||||
values| | restForm | attach1__c | STRING | NULL | ||||
values| | 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.
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 | 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.
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:
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. |
Example: Enabling two-way SSL when calling a BMC Helix Innovation Suite REST API
- In the jetty-http.xml file, located in the /opt/bmc/ars/jetty/etc folder, uncomment HTTPS section.
- 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>
- Create a self-signed certificate with different passwords for client, such as client.jks and server, such as server.jks.
- Place both certificates in a folder.
For example, c:\\mystore\. 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>Modify the default value as shown in the example below:
<Arg name="sniHostCheck" type="boolean"><Property name="jetty.ssl.sniHostCheck" default="false"/></Arg>- 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
- 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.