Invoking the Listener API

Follow the below mentioned steps for invol=king the Listener API:

 

To invoke the Listener API:

  • URL to call – http|https://server:portname/api/a/automation. For example. https://prodservername:8099/api/a/automation
  • 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 the jwt token generated by the API framework. If you don’t have jwt token, do the following for the rest call to generate token.
 

URL to call – http|https://server:portname/<tenantname>/api/Token 

E.g.  https://prodservername:8099/<tenantname>/api/a/automation 

HTTP verb – POST

Body –

{

    "username": "valid instance user",

    "password": "password"

}

If the response of the above rest call is 200, copy token and pass it to the below Authorization header.

 

If the response of the above rest call is 500, then connect with SysAdmin.

 

Security

 

Header information to pass

 

Content-Type: application/json

Authorization: Bearer {token}

 

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.

 

 

Request Body

The request body which needs to be part of the request body is attached below.

For more information, see Request object section in Anatomy of the API

 

Response

For more information, see  Response object section in Anatomy of the API

 

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 - success status indicates that request was successfully moved to the automation queue for processing (http code 200 OK). In case of any error, errors object will be sent with error details. Read below on how to interpret the status value.

transactionId - every request sent to the API is assigned a unique id and is stored in transactionId.

errors - an object which stores error information in the message property.


‎

How to interpret the response

A Http Status 200 does not mean that the end goal has been achieved. It 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

status property in the response object will let us know if it is a success or not. A success here indicates the request has been moved to the automaton queue. In case of any error, inspect the message property in the errors object.

 

Synchronous mode

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. For error information, inspect the message property in the errors object.
    A failure at this stage indicates the request has been moved to the fallout queue. errors object has been described in Anatomy of the API
  2. Failure while the robot is processing the request.

    Here, the status property in the response object is always set to success.

    Further, even if the status has success check for ErrorDetailsObject. This will have details of any robot processing failures. TransactionDescription property under response.response object is another property that will let us know if the message processing by the robot has been successful or not. A value SearchSuccessful indicates processing of the request has been successful, or else the other message will have the description of an error occurred while robot was processing the request.

    Http Status 422/500

    For Server level errors like service not found or network/authentication issues, check the underlying library properties which are used to make the REST call. This should give informative messages as to what went wrong. E.g., 401 -Unauthorized. 422 – Bad Request – when the json sent is in incorrect format, 404 – service not found, etc.

‎