Invoking the Listener API For backward compatibility

To invoke the listener API:

URL to call – http|https://server:portname/listener/rpa/api/message

For example,. https://prodservername:8099/listener/rpa/api/message

HTTP verb - POST

 

NOTE:  

If AE server installation happens on default ports (80 for http and 443 for https) then the port is not mandatory.

 

API Authentication

 

API currently is authenticated based on Rabbit MQ credentials. The credentials of Rabbit MQ are sent as a base 64 encoded string in the form of – username: password in the header section (Header information to pass)

 

Security

 

Header information to pass

  1. Content-Type: application/json
  2. Authorization: Basic Base 64 encoded username and password of RabbitMQ in the form username: password. E.g., if RabbitMQ username is se and password is se then the header will be

    Authorization: Basic c2U6c2U=

NOTE:  
  • If the API is invoked in https, ensure server certificate (where API is deployed) is installed on the machine from where the API client is invoked. Further different language’s frameworks have different needs to invoke https calls. Please refer to the corresponding documentation.
  • While invoking API if you get 401, please connect with the system admin to create the user in rabbitmq.

 

Request Object

Following is the request object in json format accepted by the API.

{

    "payload":"{\"PerformAutomation\":{\"AutomationInputDictionary\":{\"Search.mask\":\"personalinformation\"},\"ProcessName\":\"test\",\"ProfileName\":\"Profile1\",\"APIVersion\":\"\",\"AppId\":\"\",\"CommandExecutionWindow\":\"\",\"CommandGenerationSource\":\"\",\"Country\":\"\",\"Instance\":\"\",\"PartnerId\":\"\",\"ReferenceCode\":\"\",\"Timestamp\":\"\",\"UserName\":\"userName\",\"ID\":\"\",\"RetryFlag\":false,\"Retry\":{\"PreviousRequestIds\":[],\"NoOfTimesRetry\":5,\"RetryCoolOffInterval\":30000}}}",

    "content_type": "json",

    "content_encoding": "application/json",

    "profile": "Profile1",

    "expiration": 100000,

    "wait_for_completion": false,

    "source_message_id": "Fiddler",

    "app_id": "1",

    "header": {}

  }

NOTE:  

If there is no search input defined for the process then AutomationInputDictionary can be empty. e.g. {\"AutomationInputDictionary\": {}, other properties}

 

Description of key properties

 

Name

Datatype

Required

Description

payload

string

Yes

 

AutomationInputDictionary

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 followed by search input name as defined in automation process

 

ProcessName

string

Yes

Name of the automation process to be run

 

ProfileName

string

Yes

Profile under which the process needs to be run

 

UserName

string

Yes

User name of the request sender

 

RetryFlag

Boolean

Yes

If set to true request will be re-tried in case of processing failures or times out due to expiration time exceeds

 

PreviousRequestIds

 

string array

 

Not required

Leave it empty as shown in request json

 

NoOfTimesRetry

integer

Yes, if RetryFlag is set to true

Number of retry attempts to be made when process fails or times out due to expiration time exceeds

RetryCoolOffInterval

integer

Optional

Time in milliseconds to wait before attempting a retry

 

content_type

string

Yes

Content type – e.g. json

Note: value for this is not checked right now by the API

 

content_encoding

string

Yes

Encoding type.

Note: value for this is not checked right now by the API

 

profile

string

Yes

Profile under which automation has to run

 

expiration

integer

Yes

Time in milliseconds after which this request times out. The time out applies to – request waiting in queue as well as time under which the request needs to be executed by the robot

 

wait_for_completion

boolean

Yes

Setting this to true (sync mode) means API will respond only after a bot has completed processing a request, while setting this to false (async mode) means API will just move the request to either automation or fall out queue and respond back.

 

source_message_id

 

string

Yes

Unique request id.

 

app_id

string

Yes

Id of the source from which the request is sent. e.g., Postman etc.

 

header

object

No

Just leave it empty as shown in json


 

Response Objects

Async mode (when “wait_for_completion” is set to false in request body)

 

Status: Success

{

    "instance_id": 1,

    "message_id": "ae8cb3d0-68a5-4b5c-aee3-37bfc433101c",

    "status": "success",

    "response": {

        "acknowledge": true

    },

    "error": {}

}

‎

 

Description of key properties:

 

Name

Datatype

Description

message_id

string

Id of the request that was sent to the API

 

status

string

Indicating if the request was successfully moved to automation queue for processing. If success then value will be success else it will be failure

 

error

 

object

Encapsulate any error information

 

See below for a response object with error object populated

 

error_msg

string

Description as to why the request processing failed

 

response

string

This will be used in sync mode to populate with response return by robot after processing the request

 

 

Status: Failure

A response from the API if it errors out.

{

    "instance_id": 1,

    "message_id": "45af2b3d-9723-493a-a4c2-05105d559d6d",

    "status": "failure",

    "response": {

        "acknowledge": true

    },

    "error": {

        "error_msg": "Queue is not available hence message moved to fallout queue.",

        "error_code": "BsnErr002"

    }

 

Sync mode (when “wait_for_completion” is set to true in request body)

 

Status success

Find below response object returned after a successful completion of the request by 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 masked and anonymized format. Data protection of inputs is determined by process designed.

 

Status - failure, while robot is processing

Find below response object returned when some exception happens while robot is processing the request

 

NOTE:  

The status will still be success as the failure happens while request was being processed. For more information, see error details from response.Response.ErrorDetailObject.

 

 

ErrorDetailObject is an array containing error information

"ErrorDetailObject": [

                {

                    "Type": "Business",

                    "Description": "Incorrect process name in the request.",

                    "Priority": 0,

                    "Code": "BsnErr111"

                }

            ],

 

Status - failure, before being moved to automation queue

In sync mode if the request fails for any reason before being moved to automation queue response object will be similar to what we receive in Async mode on failures

 

API Validation

When the API is called, request input is validated against the rules configured in API framework configurations.

 

Key properties to look for in response

 

status indicates success/failure of request processing. Read below on how to interpret the status value

message_id every request sent to the API is assigned a unique id and this is what is stored in message_id

error, an object which stores error information in the error_msg property

 

How to interpret the response

 

A Http Status 200 does not mean that the end goal has been achieved. It merely means the response has been processed by the API and moved to the automation queue for processing. Processing by the robot could lead to success or failure. This also depends on the mode of the API

 

Asynchronous mode (when “wait_for_completion” = true in request payload)

 

status property in the response object will let us know if it is a success or failure. For more error information, inspect the error_msg property in the error object. A failure here indicates the request has been moved to the fallout queue, while success means it has been moved to the automaton queue.

 

Synchronous mode (when “wait_for_completion” = false in request payload)

 

response property will have all the details of the robot processing including any errors.

 

Synchronous mode has two types of failures –

  1. Failure before the request has been moved to automation queue.
    status property in the response object will be set to failure and more information can be read from error object. A failure here indicates the request has been moved to fallout queue.
  2. Failure while the robot is processing the request.
    status property in the response object will be set to success.

    Further, even if the status has success check for ErrorDetailsObject. This will have details of any robot processing failures. AutomationQueueType property under response object is another property that will let us know if the message processing by the robot has been successful or not. A value of failurequeue means the request processing has failed, while successqueue indicates processing of the request has been successful.

    Http Status 422/500

    For Server level errors such as service not found, for network issues or authentication issues, verify the underlying library’s properties which are used to make the REST call. This will provide informative messages as to what went wrong. For example., 401 -Unauthorized. 422 – Bad Request – when say the json sent is in incorrect format, 404 – service not found, and so on.