External Web Service Configuration

Field

Description

Configuration Details

Configuration Name

Specify the configuration name.

Description

Specify the description of the configuration.

Application as Source

Select this check box when you want to configure the data flow from Application to the Client web services.

Batch Process

Select this check box when you want to configure the data flow from Client Web Services to Application.

The Batch Process only applies in the following two scenarios:

• User Master creation from Client Web Service to Application

• User Master update from Client Web Service to Application

Note:

When the Application as Source check box is not selected, the Batch Process check box appears below it.

No. of Records (in a Batch)

Specify the number of records you want to create or update in a single batch.

Note:

• When the Batch Process check box is selected, a new field, No. of Records (in a Batch) appears below it.

• You can specify a maximum of 100 records in the No. of Records field.

Include Attachment

Select this check box if you want to include attachment of Incident/ Service Request/ Work Order for the data flow configuration. Upon selecting Include Attachment check box, a separate Attachment Details section is displayed below the Web Service Details section.

Web Service Details

Service URL

Specify the Web Service URL for both the Source and the Target.

Service Description

Specify the Web Service description for both the Source and the Target.

Configure API Authentication

Select the pre-defined authentication values of the list. The listed values are:

1. No Authentication

2. API Key - Specify the API key details.
   
   Figure: API Key

3. Bearer Token

   1. Static Bearer Token
      
      Figure: Static

   2. Dynamic Bearer Token

      Figure: Dynamic Bearer Token

4. Basic - Specify the credentials for the authentication.
   
   

5. OAuth 2.0 - Enter the required auth details.
   Figure: OAuth 2.0

Authorization Key/Token

Provide Authorization details to authenticate API for both the Source and the Target.

Headers

Select the Web Service type from the drop-down list for both the Source and the Target.

Additional Header(s)

To pass any additional information in the API call you make, provide the key and value in Additional Header(s).

Request Body

Provide the Input data for both the Source and the Target.

Response JSON Key

Specify the JSON path from where want to consume the response.

Get Response

Click Get Response button to get the response for specified JSON key.

Response Template

Response for specified JSON key gets auto filled in this field after clicking on Get Response button.

Map Data

Select this check box to configure columns and their values to exchange the data between the two web services.

View/Edit Data Integration

Click View/Edit Data Integration button to configure the Column Names and their values to exchange the data between two Web Services. Upon clicking the View/Edit Data Integration button, the Map Data pop-up page is displayed.

Figure: Integration Fields

The Source Response Field contains an array with three elements: "value1", "value2", and "value3". You can access the values within the array using the appropriate object parameters and values.

The Target Input Field contains an "input" field. When passing this JSON object as the input to the field, make sure to provide the necessary formatting and parsing based on the value name and attribute you are using to Map.

Note:

The View/Edit Data Integration button is displayed while editing only when the Map Data check box is selected.

Once you check the Map Data check box, you will see the page to map the data.

Once you check the Default Check box, the value entered in the Source/Target column will be considered as a Default value. This means that when there is no matching value in the Third-Party system this default value will be considered for all future transactions.

New Column named Collection addition under View/Edit Field Integration

There is a new column named Collection, where three new options have been introduced namely First, Last and All in the source field.

Figure: Collection Column

First: Choose this option to map only the first attribute of the array mentioned in the Source Field to the Target Field.

For example, if we have the below input in the source field,

Source: Fields.comment.comments.0.body

and we select the First option under collections, then only the First comment in that array will be mapped to the Target Field.

Last: Choose this option to map only the Last attribute of the array mentioned in the Source Field to the Target Field.

For example, if we have the below input in the source field,

Source: Fields.comment.comments.0.body

and we select the Last option under collections, then only the First comment in that array will be mapped to the Target Field.

All: Choose this option to map all the attributes of the array mentioned in the Source Field to the Target Field which will be comma separated.

For example, if we have the below input in the source field,

Source: Fields.comment.comments.0.body

and we select the All option under collections, then all the comments (Comma separated) in that array will be mapped to the Target Field.

Note:

In case there is no array matching with the input provided in the Source Field, this option will be greyed out.

Confidential Key Value Protection Changes in External Web service Configuration

While Integration with a third-party application, to gain access we need to enter the credentials such as an API Key which is confidential information. To protect such confidential information, we have implemented Confidential Key Value Protection.

While entering confidential information such as the API Key in the request body, the platform has been updated so that the API key can be mentioned along with $$ as prefix and suffix as shown below:

“APIKey”: $$APIKEY$$

After entering this in the request body, on clicking SUBMIT, user will be prompted to enter the Actual API Key (which is confidential) under PLACEHOLDER INPUTS as shown below:

On clicking the eye Icon next to the field, you can hide the confidential information as shown below:

Figure: Confidential information hidden using Eye Icon

Similarly, while entering any information while configuring an API key, any confidential information can be suffixed and prefixed with $$ as shown below, to protect the confidentiality of the information. The user will be prompted to enter the confidential information separately. The same has been implemented for the following fields:

• Request Body:

In the request body, enter the $$ symbol before and after the API Key to protect the confidential information as shown below:

Figure: Request Body

• Additional Headers

• URL

Figure: $$ before and after the Target URL

You will get a prompt and the Target URL will be hidden as shown below:

Map Data

The Map Data pop-up page consists of four sections, namely, Filters, Import/Export, Configuration, and List.

Filters

The Filters section contains the following fields.

Search By

Select one of the Search By criteria that are Source Column Name, Source Column Value, Target Column Name, or Target Column Value.

Search Value

Specify the Search Value based on selected search by criteria.

Import/Export

The Import/Export section contains the following fields.

Import/Export Option

Select the Import/Export option, that is, either JSON or XML

Download Template

Click the Download Template button to download the JSON or XML template for import configure columns and their values to exchange data between the two web services.

Upload Web Service Integration

Browse a Web Service Integration and click Upload to import the columns and their values to exchange data between the two Web Services.

Configuration

The Configuration section contains the following fields.

Source Column Name

Select a Source Column Name from drop-down list.

Source Column Value

Specify the Source Column Value based on the selected Source Column Name.

Target Column Name

Select a Target Column Name from drop-down list.

Target Column Value

Specify the Target Column Value based on the selected Target Column Name.

List

The List section contains the following fields.

Source Column Name

The Source Column Name column displays list of configured Source Column Names.

Source Column Value

The Source Column Value column displays list of configured Source Column Values.

Target Column Name

The Target Column Name column displays list of configured Target Column Names.

Target Column Value

The Target Column Value column displays list of configured Target Column Values.

Action

Clickadd new field Integration andto remove any existing field Integration.

View/Edit Fields Integration

Click View/Edit Fields Integration button to map request and response fields accordingly. Upon clicking the View/Edit Fields Integration button, the Integration Field pop-up page is displayed.

Integration Field

The Integration Field pop-up page contains the following fields.

Source Response Field

Specify a Source Response field.

Target Input Field

Specify a Target Input Field to which you want to map the Source Field.

Action

Clickadd new field Integration andto remove any existing field Integration.

Click to format JSON.

Click to revert JSON format to original format.

Click to view/Edit JSON.

Attachment Details

Note:

Attachment Details section displayed only after selecting Include Attachment check box on the Configuration Details section. Configure Attachment Details section to include attachment of Incident/ Service Request/ Work Order for the data flow configuration.

Service URL

Specify the Web Service URL for both the Source and the Target.

Headers

Select the Web Service type from the drop-down list for both the Source and the Target.

Request Body

Provide the Input data for both the Source and the Target.

Response JSON Key

Specify the JSON path from where you want to consume the response.

Response Template

Provide a sample output data.

File Data Type

Select a file data type under the File Data Type drop-down field.

• Base64: Select to represent binary data in an ASCII string format by translating it into a radix-64 representation.

• Byte Array: Select byte array to store a collection of binary data, for example, the contents of a file.

• Multipart/form data: Select Multipart/form data for request payloads that contain files, non-ASCII, and binary data.

Response Data

Specify the Response Data.

View/Edit Fields Integration

Click View/Edit Fields Integration button to map request and response fields accordingly. Upon clicking the View/Edit Fields Integration button the Integration Field pop-up page is displayed.

Integration Field

The Integration Field pop-up page contains the following fields.

Source Response Field

Specify the Source Response Field.

Target Input Field

Specify the target input field to which you want to map the Source Field.

Action

Clickadd new field Integration andto remove any existing field Integration.

Click icon to format JSON.

Click to revert JSON format to the original format.

Click icon to view/edit JSON.

Job Details

Run At

Selected the Server type under the drop-down field. Following two servers types are available under the Run At drop-down field: Summit Server and Proxy Server.

Schedule Start Date (UTC)

Specify a start date and time according to UTC zone for the Web Service configuration.

Frequency (In Mins)

Specify a time interval in minutes.

Note:

If the No. of Records under the Configuration Details tab is more than 500 for Batch processing, the job will run for longer period of time to process all the records. Please increase the Job Frequency.  

Active

If selected, the configuration becomes active.

Field

Description

Actions Required

Select actions required as Yes or No

Response Details

The Response Details section contains the following fields.

Service URL

Specify the Web Service URL for both the Source and the Target.

Service Description

Specify the Web Service description for both the Source and the Target.

Authorization Key/ Token

Provide Authorization details to authenticate API for both the Source and the Target.

Headers

Select the Web Service type from the drop-down list for both the Source and the Target.

Request Body

Provide the Input data for both the Source and the Target.

Response JSON Key

Specify the JSON path from where you want to consume the response.

Response Template

Provide a sample output data.

Map Data

Select this check box to configure columns and their values to exchange the data between the two Web Services.

View/Edit Data Integration

Click View/Edit Data Integration button to configure the Column Names and their values to exchange the data between two Web Services. Upon clicking the View/Edit Data Integration button, the Map Data pop-up page is displayed.

Note:

The View/Edit Data Integration button is displayed while editing only when the Map Data check box is selected.  

Map Data

The Map Data pop-up page consists of four sections namely Filters, Import/Export, Configuration, and List.

Filters

The Filters section contains the following fields.

Search By

Select one of the Search By criteria that are Source Column Name, Source Column Value, Target Column Name, or Target Column Value

Search Value

Specify the Search Value based on the selected search by criteria.

Import/Export

The Import/Export section contains the following fields.

Import/Export Option

Select Import/Export Option, that is either JSON or XML

Download Template

Click the Download Template button to download the JSON or XML template for import configure columns and their values to exchange data between the two web services.

Upload Web Service Integration

Browse a Web Service Integration and click Upload to import configure columns and their values to exchange data between the two web services.

Configuration

The Configuration section contains the following fields.

Source Column Name

Select a Source Column Name from drop-down list.

Source Column Value

Specify the Source Column Value based on the selected Source Column Name.

Target Column Name

Select the Target Column Name from drop-down list.

Target Column Value

Specify the Target Column Value based on the selected Target Column Name.

List

The List section contains the following fields.

Source Column Name

Source Column Name column displays list of configured Source Column Names.

Source Column Value

Source Column Value column displays list of configured Source Column Values.

Target Column Name

Target Column Name column displays list of configured Target Column Names.

Target Column Value

Target Column Value column displays list of configured Target Column Values.

Action

Clickadd new field Integration andto remove any existing field Integration.

View/Edit Fields Integration

Click View/Edit Fields Integration button to map request and response fields accordingly. Upon clicking the View/Edit Fields Integration button, the Integration Field pop-up page is displayed.

Integration Field

The Integration Field pop-up page contains the following fields.

Source Response Field

Specify a Source Response Field.

Target Input Field

Specify a Target Input Field to which you want to map the source field.

Action

Clickadd new field Integration andto remove any existing field Integration.

Click icon to format JSON.

Click to revert JSON format to the original format.

Click icon to view/edit JSON.

Field

Description

Retry Count

Select retry count to process the Job again when tickets (Incidents, Service Requests, and Work Orders) are failed.

Note:

• The Retry count is the number of times the Job retries to process the tickets (Incidents, Service Requests, and Work Orders) that have failed to process.

• A maximum value of 100 can be set in the Retry Count field.

Failure Configuration

If selected, all the failed tickets are picked up for re-processing.

Note:

• Failure configuration is a system-created configuration when Application is the target and few tickets (Incidents, Service Requests, and Work Orders) failed to process.

• The Failure Configuration check box appears only when the Application as Source check box is not selected on the Configuration tab.

Attempts for (in hrs)

Specify the attempts (in time) to process the failed tickets (Incidents, Service Requests, and Work Orders).

Note:

The Attempts for (in hrs) field appear only when Application as Source check box is not selected on the Configuration tab.

Notification

The Notification section contains the following fields.

Set Notification

If selected, you can configure an e-mail template to notify the user about ticket failure.

To List

Specify the e-mail recipients for the notification related to ticket failure.

CC List

Specify the Cc e-mail recipients for the notification related to ticket failure.

Subject

Specify the subject for the e-mail notification.

Body

Specify the e-mail body of the e-mail notification.