AE REST API - General Info

By using the AE REST API you can rely on a technology-independent state-of-the-art interface to interact with the Automation Engine

This topic provides information on the following:

Overview

The AE REST API provides an interface for third party applications to interact with the Automation Engine. It allows the user to target the Automation Engine not only from Java, but from many programming languages. Currently, the AE REST API supports the following features:

The REST requests and responses contain JSON structured data:

Optional properties with value null might be omitted in the response payload.

The AE REST API supports both HTTP and HTTPS (recommended). HTTPS can be set with the parameter sslEnabled in the Automation Engine configuration file (ucsrv.ini). For more information see HTTPS/SSL set up for AE REST API.

The current version of the AE REST API is v1. This information is reflected in the URI and is therefore relevant when accessing your AE REST API interface.

AE REST API and ILM

During the daily operation of an Automation Engine system, large amounts of reporting, statistical and historical data accumulate. Partitioning the database with ILM is an efficient method to deal with this and maintain the object version as well as the deleted object data. ILM actions require switching out parts of the Automation Engine database tables; therefore, no database actions should take place while working with ILM.

The AE REST web service automatically detects if there are any ongoing ILM actions and, if so, blocks specific REST requests. In this case, an error message is returned, indicating that the REST API is momentarily not available due to ILM actions.

Setting up Multiple REST API Processes

The JCP installation is relevant for the AE REST API as well as for the advanced object search.

When using multiple JCPs it is imperative that each JCP uses its own Automation Engine configuration file (ucsrv.ini).

If only one INI file is used for more than one JCP, the first one will connect successfully while the others will terminate upon trying to register the same REST port if both run on the same node. An error message is written to the JCP's log file stating the reason for termination.

The AE REST API can be installed multiple times, either with different port numbers on one node or on different nodes (in this case the same port number may be used).

The following scenarios are supported:

Single JCP

In this case a single JCP is used and all REST requests are sent to this single AE REST API instance. This means that no fail-over capabilities are provided and no AE REST API is available if the JCP is down.

Clustered JCPs

In this case two JCPs are used in a cluster but only one of both is available at the time, thus providing fail-over capabilities. All REST requests are sent to only one of the two AE REST APIs, depending on their respective availability.

To use this configuration a JCP needs to be installed on each node but both JCPs share the same Automation Engine configuration file (assuming the cluster shares the same installed resources). If a virtual IP is being used, both JCPs can be reached via the same IP address. This means the endpoints have the same base URI: http(s)://{host}:{port}/ae/api/v1/{client}/...

Please note that a configuration with multiple JCPs is not intended for load balancing purposes.

Authentication

The AE REST API supports Basic Authentication.

The user, department, and password information is part of the HTTP(S) header and used for Basic Authentication. The Automation Engine decides whether a REST request in the user context is allowed or not and responses accordingly.

Generate at Runtime

In order to avoid request timeouts, the objects to be executed must have the attribute "Generate Task at Runtime" set. When executing and object, the system checks if this attribute has been set accordingly. If it has not been set, the execution is canceled.

By setting this attribute the RunID will be returned immediately, so that the REST response follows the request straightaway.

If this attribute is set to "Generate Task at Activation Time", long processing might prevent immediate REST response which may result in a timeout.

Please note that when restarting an execution, the system does not check if the attribute "Generate Task at Runtime" has been set.

AE REST API Polling

It is possible to poll the server to check the status of a REST request/response sequence if the desired result is not yet available. For example, you could poll the server after executing an object and getting the RunID to check if the execution has ended.

The following sample shows how polling for execution status can be done via AE REST API:

Input via PromptSet

PromptSet variables can be passed via the AE REST API request on execution if the objects to be executed have at least one PromptSet assigned.

Example of REST request content:

PromptSet variable Field type Recommendations
"&TEXT1#" Text field  
"&NUMBER1#" Number field  
"&CHECKBOX_ARRAY#" Checkbox field* Array=true
&CHECKBOX_STRING# Checkbox field Array = false, separator = ";"
"&MULTILINE1#" Multi-line text field Attribute "Multi-line" checked, \n for line breaks

* Automic recommends to define a Checkbox field as Array when used to pass values via the AE REST API.

The attribute "Array" of the PromptSet's field CHECKBOX_ARRAY hast to be set to true since the Automation Engine needs to handle it as an array.

Please note that no object variables can be set here.

Tracing

All REST activities can be traced for analysis purposes. To do so select a JCP and right-click to select Advanced Options. This opens a dialog where you can specify trace flags:

The trace flag can also be set in the Automation Engine configuration (INI) file. To do so set the JCL key in the TRACE section of the INI file. The relevant values for the AE REST web services are the following:

Value Specification
0 Tracing disabled
1 Traces REST headers and content
2 Traces login information in addition

Pagination

Pagination can be very useful if a request to the AE REST API returns a lot of results, since the result set is divided into chunks (pages) per request/response. For example, if you send a request to get all the child task executions of a specific execution, thousands of records may be retrieved. In AE REST API you can use pagination to make results easy to handle.

Limit Parameters

AE REST API allows you to set the following limit parameters:

Parameter Description
max_results

Defines the maximum number of results per page.

Default value: 50

If this parameter is omitted the default value is used.
start_at_run_id

Defines the RunID of the last entry of the previous page.

If this parameter is omitted the first page is returned.

URIs Structure

The URI including the pagination parameters consist of the following elements:

http://{host}:{port}/ae/api/v1/{client}/executions/{runid}/children?max_results={number}&start_at_run_id={runid}

For example:

http://192.168.40.116:8088/ae/api/v1/100/executions/1003003/children?max_results=10&start_at_run_id=100301

In this example, the requested parent execution 1003003 has 25 child task executions requested. The paginated response is distributed as follows:

Page Request URI Response Payload Comment
1 ../executions/1003003/children?max_results=10

List of the first 10 executions

RunID of last execution listed=1003045

 

"hasmore"=true(*)

"total"=25(**)

 If the parameter start_at_run_id is omitted the first page is returned
2 ../executions/1003003/children?max_results=10&start_at_run_id=1003045

List of the next 10 executions

RunID of last execution listed=1003054

 

"hasmore"=true(*)

"total"=25(**)

 The RunID of the first execution on page 2 is greater than the RunID of the last execution on page 1, thus avoiding duplicate listings
3 ../executions/1003003/children?max_results=10&start_at_run_id=1003054

List of the next 5 executions

 

"hasmore"=false(*)

"total"=25(**)

 "hasmore"=false indicates this is the last page

The executions displayed on a given page are ordered by activation time and RunID ascending.

Be aware that pagination might provide an incomplete list of child task executions. For example, if a requested page "P" lists all executions with activation time >=T1 and RunID > R1 and a new execution "E" is generated at a later point with the same activation time but with RunID < R1, the execution "E" will not be listed neither on page "P" nor in any following page.

Localization

REST API messages are by default in English. The AE REST API does not support any other language.

See also: