Enabling/Disabling Rest Callout

To enable Rest Callouts, add the following entry to config.properties:

mainConfig.EnableRestCallouts=true

Before defining a Rest Callout

To define any of the attributes in the Rest Callout Designer, you will need to have detailed knowledge and understanding of the 3rd party System.

Before defining a Rest Callout, gather information for each of the following:

• API URL: address, use of parameters, etc.
• Payload: structure and content of the payload for the different Rest Methods
• Date Format: in which format does the external system accept and deliver date fields.
• Headers/Response: structure and content

Field Delimiters

Since square brackets ([ ]) are used in JSON to describe Arrays, in the Rest Callout Designer, fields are delimited via the pipe symbol ( | ) instead.

For example:
{
"action_summary":"|Detailed Description|"
}

Rest Callout Attributes

Attribute

Details

Action Title

Descriptive Name for the current Rest Callout

Rest Method

The following methods are available:

• Get: to retrieve data from the external system.
• Post: to create a new record/resource in the external system
• Put: to update an entire record/resource in the external system
• Patch: to only update some properties of a record/resource
• Delete: to delete a record/resource in the external system

API URL

The URL to call the external API. Depending on the API, the URL can be static, but it also can contain dynamic parameters.

You can add the field value of a current record by adding the field name, which can be done by either selecting a field from the selector after clicking API Url, or by typing it into the field and delimit it with the pipe symbol (|),

Example: For a Rest Callout configured on Person with the below URL

http://hrsystem/prod/restapi/people('|Employee Number|')

On save of the Person record, the system would substitute the |Employee Number| placeholder with its actual value when triggering the Rest Callout.

You can also define the URL as a constant under (Designer Constants) and specify the constant ID like below,

|.HR_URL|

Note the "." after the first pipe symbol to different the constants from the form fields.

Token Configuration

Optional selection, required if the external system uses OAuth-style access token authentication.

Refer to this link to know more about setting up External API Tokens.

Headers

You can define multiple Header entries for each call, each entry consisting of a Key/Value pair.

Please consult the documentation of the external system which Headers are required.

Payload

You can define the payload of a Post, Put or Patch call in this field.

You can add dynamic field values by clicking on the Payload button and select the required field(s), which will be delimited by the pipe (|) symbol.

Here is an example:

{
"action_summary": |Action Summary|,
"action_source" : |Action Source|,
"priority" : |Priority|,
"action_description": |Action Description|,
"due_date" : |Due Date|,
"date_raised": |Date Raised|
}

Date Format

Provide the format in which the third party API requests and supplies values for Date fields.

The default format is: dd/MM/yyyy

Response Type

Select the format in which the reply will be delivered by the external system. The options are:

• JSON
• XML

Response Operation

Select either of the following operations:

• Update:
  to update existing records
• Create:
  to create new records

Response

The Response can only be defined once the Response Operation has been defined.

To map the response from the external system to the SAI360 system, you need to provide for each:

• Selector: enter value as provided by external system.
• Mandatory: tick if the response must include a value for this field.
• Destination Field: select the corresponding and supported target field from the field picker.
  Not supported are: Matrix Fields.
• Relationship Key Field: when updating relationships, select the key field to uniquely identify the related record.

NOTE:
the available selection of Destination fields will differ, depending on the selected Response Operation: to-many relationships will only be available when the Operation is defined as CREATE.

Timeout

• This is the time in seconds for how long the web application will wait for a reply from the API before failing it.
• The default value is 60 seconds.

NOTE:
the Timeout here refers to the "Read" timeout.
The Connection timeout for Rest Callouts is defined in the Global Settings.

Check Fields

Click to verify that the fields added to the URL or the Payload fields are valid.

For detailed logging of the Rest Callout responses, especially during the initial setup phase, add the following entry to config.properties (..\SAI360\config\):

mainConfig.Debugsetting=restcallouts

Monitor the catalina.xxxx-xx-xx.log files under Tomcat