Anatomy of the API
Before proceeding with how to call the API, let us look at the request and response objects of the API.
This section explains following:
Request Object
Following is the request object in json format accepted by the API.
{ "processInput": "{\"Search.arg1\":\"test\"}", "processName": "testProcess", "profileName": "testProfile", "requestTimeout": 30000, "retry": false, "sourceId": "PostMan", "isSync": false, "retryConfigurations": { "noOfTimesRetry": 2, "retryCoolOffInterval": 20000 } }
|
NOTE: |
If there is no search input defined for the process, then processInput can be empty. e.g. {"processInput ": {}, other properties}. |
Description of key properties:
|
Name |
Datatype |
Required |
Description |
|
processInput |
Dictionary/ HashMap/ KeyValuePair in the form string, object |
Optional
|
If the process does not have any search inputs to be passed, just provide empty braces. Search.<searchinputname>. Search is mandatory followed by a dot and followed by search input name as defined in the automation process.
|
|
processName |
String |
Yes |
Name of the automation process to be run. |
|
profileName |
String |
Yes |
Profile under which the process needs to run. |
|
Retry |
Boolean |
Optional default false |
If set to true, request is re-tried in case of processing failures or times out when expiration time exceeds. |
|
noOfTimesRetry |
Integer |
Yes, if retry is set to true |
Number of retry attempts to be made when the process fails or times out when expiration time exceeds |
|
retryCoolOffInterval |
integer |
Optional |
Time(in milliseconds) to wait before attempting a retry. |
|
requestTimeout |
Integer |
Yes |
Time(in milliseconds) after which this request times out. The time out applies to request waiting in the queue as well as time under which the request needs to be executed by the robot. |
|
isSync |
Boolean |
Optional default false |
Setting this to true (sync mode) means API responds only after a bot has completed processing a request. Setting this to false (async mode) means API just moves the request to either automation or fall out queue and respond. |
|
sourceId |
String |
Yes |
Unique source Id. |
Response Objects
Async mode when isSync is set to false in the request body.
|
Status: Success { "transactionId": "cea3ac12-dc20-4af9-9bd8-6b9e2b320d51", "status": "success", "response": { "acknowledge": true }, "error": {} } |
Description of key properties:
|
Name |
Datatype |
Description |
|
transactionId |
string |
Request Id that was sent to the API |
|
Status |
string |
Indicates if the request was successfully moved to the automation queue for processing. If success, then the value will be success; else, it will be a failure. |
|
error
|
object |
Encapsulate any error information. See below for a response object with an error object populated. |
|
error_msg |
string |
Failure description of the request |
|
response |
string |
This is used in sync mode to populate with response return by the robot after processing the request. |
Rest of the keys are same as in the request payload.
Status: Failure
A response from the API if it there is an error.
|
{ "timestamp": "2022-02-23T12:52:27.919Z", "errors": [ { "code": "BsnErr002", "message": "Queue is not available hence message moved to fallout queue." } ], "instance": "ba76f1cf-b06e-442d-b7b1-a42b66b2f002" } |
Sync mode when isSync is set to true in the request body.
Status success :
Find below the response object returned after successful completion of the request by a robot. The properties are similar to as explained in Async mode except for the response property which in addition to containing request object sent also contains details about robot and inputs in a masked and anonymized format. Data protection of inputs is determined by the process design.
Status - failure, while the robot is processing.
Find below response object returned when some exception happens while the robot is processing the request.
|
NOTE: |
The status will still be a success as the failure happens while the request was being processed. To get more error details, read from the response.response.ErrorDetailObject |
ErrorDetailObject is an array containing error information.
|
\"ErrorDetailObject\":[ { \"Priority\":0, \"Code\":\"BsnErr109\", \"Description\":\"Incorrect automation input parameter count mismatch.\", \"Type\":\"Business\" } ] |
Status - failure, before being moved to automation queue
In sync mode, if the request fails for any reason before being moved to the automation queue response object will be similar to what we receive in Async mode on failures.