AE REST API - General Info
As a developer or system administrator, you can use the REST API to communicate with the Automation Engine system using a technology-independent, state-of-the-art interface.
This page includes the following:
The AE REST API provides an interface for third-party applications to interact with the Automation Engine. The AE REST API also allows the user to target the Automation Engine not only from Java, but from many programming languages.
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 sslEnabled parameter in the Automation Engine configuration file ucsrv.ini. For more information, see HTTPS/SSL set up for AE REST API in Installing the JCP.
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.
The AE REST API can be installed multiple times. The installation can be either with different port numbers on one node or on different nodes with the same port number.
Notes:
-
All timestamp values are returned as saved in the database and are not converted by the Automation Engine. The REST client is in charge of any conversion.
-
The Automation Engine does not check if a time zone object exists when executing an object. The AE REST API does not check it either.
-
When you use AE authentication and you import a User object, the User is locked. It must be unlocked in Client 0 and a new password must be set. This behavior does not apply when using LDAP authentication. For more information, see Authenticating Login Data via LDAP and/or LDAP Sync.
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 it and maintain the object version and 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. For more information, see ILM - Information Lifecycle Management.
Important! The AE REST web service automatically detects if there are any ongoing ILM actions and, if so, it 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.
Localization
REST API messages are by default in English. The AE REST API does not support any other language.
Setting up Multiple REST API Processes
The JCP installation is relevant for the AE REST API and for the advanced object search. You can install a single JCP. In this case, all REST requests are sent to this single AE REST API instance and no REST API is available if the JCP is down. For more information, see Installing the JCP.
You can also set up a system with multiple JCPs. In this case, two JCPs are used in a cluster but only one of both is available at the time.
Important! 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 connects successfully while the others terminated upon trying to register the same REST port if both run on the same node. An error message is written to the log file of the JCP stating the reason for termination.
Setting up a system with multiple JCPs can be convenient for balancing and to provide failover capabilities, because the REST requests are sent and distributed only to available JCPs.
To use this configuration, a JCP must be installed on each node. Port1 and port2 can have the same port number (for example, 8088, the default value in the configuration file) because the JCPs/REST web services are running on different hosts (host1 and host2). Host3:port3 must be public available as single point of contact for all AE REST API requests. Host1:port1 and host2:port2 must be known only by the HTTP/HTTPS proxy.
If a virtual IP is being used, both JCPs can be reached through the same IP address, which means that the endpoints have the same base URI: http(s)://{host}:{port}/ae/api/v1/{client}/....
The REST client or a HTTP/HTTPS proxy periodically sends a /ping request to check the JCPs availability. Depending on the result, the HTTP/HTTPS proxy knows which JCPs are available at the moment.
- In a High Availability active/active setting, both are intended to be available.
- In a High Availability active/passive setting, only one of them is intended to be available.
The REST client or HTTP/HTTPS then decides where to send the REST requests, depending on the selection strategy of the proxy. When the REST client sends requests to the HTTP/HTTPS proxy (host3:port3), the proxy dispatches them automatically to a JCP/REST web service.
- In a High Availability active/active setting, it sends it to one of both available. Which one is used depends on the selecting strategy of the proxy (for example, lowest load or connections).
- In a High Availability active/passive setting, it sends it to the one that is available.
The AE REST API provides two different health checks:
-
a fast /ping request to be used by HTTP/HTTPS proxies to ensure that the JCP and REST web service is available. This health check does not provide any details on the required backend components:
../ping
-
a system information health check which provides details on the JCP and REST web service. This health check also provides details on the required backend components:
../{client}/system/health
Authentication
The AE REST API supports basic authentication. The client, user, department, and password information are part of the HTTP(S) header and of the URI and therefore used for basic authentication. The Automation Engine decides whether a REST request in the user context is allowed or not and responds accordingly.
The request is processed if the client number entered in the authentication information is the same as in the URI. If the client number differs, an error is returned.
The AE REST API does not support password encryption for the password that is stated in the REST request. It is recommended to use HTTPS to secure the transmission of this information. For more information, see Encoding Passwords.
Authorizations
An efficient and secure system to protect the access to data is a key part of our security concept. Security at data level can be as broad as administrator access to a role, or as granular as Read access to only one job in one specific folder. For more information, see Access Control.
The AE REST API also requires certain authorizations to perform different operations and checks if they are in place when performing them.
-
To retrieve variables, comments, and reports of an execution (GET) you need the authorization S - Executions.
-
To add comments to an execution (POST), you need the authorization M - Modify at runtime.
For more information, see Granting Automation Engine Authorizations.
Generate at Runtime
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 not started. For more information, see Attributes Page.
By setting this attribute the RunID is 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.
Note: When restarting an execution, the attribute Generate Task at Runtime is not set.
AE REST API Polling
You can poll the server to check the status of a REST request/response sequence in case 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 through the AE REST API:
Input through PromptSet
PromptSet variables can be passed through the AE REST API request on execution given the objects to be executed have at least one PromptSet assigned.
Example of REST request content:
-
"&TEXT1#"
Field type: Text field
-
"&NUMBER1#
Field type: Number field
-
"&CHECKBOX_ARRAY#"
Field type: Checkbox field
It is recommended to define a Checkbox field as Array when used to pass values through the AE REST API.
Recommendations: Array=true
-
&CHECKBOX_STRING#
Field type: Text field
Recommendations: Array = false, separator = ";"
-
"&MULTILINE1#"
Field type: Text field
Recommendations: Attribute "Multi-line" checked, \n for line breaks
Notes:
-
The attribute "Array" of the PromptSet field CHECKBOX_ARRAY has to be set to true because the Automation Engine must handle it as an array.
-
No object variables can be set here.
-
Some REST requests contain the inputs parameter, which lists PromptSet variables. This context implies that they are all variables and there is no need to state explicitly a leading "&". The trailing "#" depends on the variable definition. For more information, see Variables and VARA Objects.
Filter for Execution List
The request GET ../v1/{client}/executions returns a list of all executions. You can add query parameters as part of the URI to filter the them.
Note: The Automic Web Interface has different settings for list views that are relevant when applying filters. The hierarchical view, which, when using filters, affects only parent tasks and the list view, which affects both, parent and child tasks. The AE REST API supports only the list view.
You can apply filters for the following execution parameters:
-
name
Enter the name (..?name=[NAME]) or part of the name (..?name=[NAM]*) of the execution you are searching for.
Note: You can only use the query parameter once.
-
name_exclude
Use this parameter to exclude the executions with a certain name.
-
alias
The alias is an optional, additional name that is given to a task when it is part of a workflow. If defined, the alias is displayed instead of its name.
Enter the alias (..?alias=[NAME]) or part of the alias (..?alias=[NAM]*) of the execution you are searching for.
Note: You can only use the query parameter once.
In case you want to set special characters for the execution alias, you must define the key ALIAS_SPECIAL_CHARACTERS in the UC_CLIENT_SETTINGS variable in the relevant client, see ALIAS_SPECIAL_CHARACTERS .
-
type
You can add query parameters to filter for the following Object Types: CALL, SCRI, JOBD, CPIT, JOBG, C_PERIOD, JOBF, REPORT (agent job reports only), JSCH, JOBP, JOBS, JOBQ, EVNT, API, C_HOSTG.
Note: This parameter allows you to use multiple values. You can either use the parameter once and separate the values with comas (type=JOBS,JOBP) or use the parameter more than once in a request (type=JOBS&type=JOBP).
-
Time frame
Use a combination of the following parameters to find executions within a given time frame.
-
time_frame_option: Use this parameter to define which kind of executions you want to find within a certain timeframe. The values that are allowed are:
-
all: all executions that start, end, or run within the specified timeframe
-
activation: all executions that are activated within the specified time frame
-
start: all executions that started within the specified time frame
-
end: all executions that ended within the specified time frame
-
-
time_frame_from: starting date and time frame
-
time_frame_to: final date and time frame
-
-
status
Use this parameter to search for any possible status that is recorded by the Automation Engine. For more information, see System Return Codes of Executable Objects.
Note: This parameter allows you to use multiple values. You can either use the parameter once and separate the values with comas (status=1900,1800) or use the parameter more than once in a request (status=1900&status=1800).
-
agent
Enter the agent name (..?agent=[NAME]) or part of the agent name (..?agent=[NAM]*) of the execution you are searching for.
Note: You can only use the query parameter once.
-
agent_exclude
Use this parameter to exclude the executions processed by a particular agent name.
-
platform
Use this parameter to find executions that have been processed by a specific agent type. For example, all executions processed by Windows Agents.
Note: This parameter allows you to use multiple values. You can either use the parameter once and separate the values with comas (platform=WIN,LINUX) or use the parameter more than once in a request (platform=WIN&platform=LINUX).
-
queue
Use this parameter to search for execution queues.
Note: This parameter allows you to use multiple values. You can either use the parameter once and separate the values with comas (queue=CLIENT_QUEUE,PRIO_QUEUE) or use the parameter more than once in a request (queue=CLIENT_QUEUE&queue=PRIO_QUEUE).
-
include_deactivated
Use include_deactivated to include deactivated executions in the search when applying filters, because they are not considered by default.
This parameter can have an impact on the time frame:
-
If the parameter is =false or missing and no time frame is defined, the internal default for the time frame is unlimited
-
If the parameter is =true and no time frame is defined, the internal default for the time frame is 12 hours.
-
-
run_id
Use this parameter to search for an execution with a specific RunID.
-
user
Enter the name of the User that owns the executions you are searching for.
Note: If the User object name is defined by the {user}/{department}, the query needs to reflect it (user=smith/development). If the department is not relevant, you can use user alone or followed by a wildcard (user=smith, user=smith*).
-
user_exclude
Use this parameter to exclude executions owned by a certain User.
-
archive_key1 and archive_key2
Archive keys are freely definable keywords that can be assigned to objects to help users.
Enter one or both archive keys of the executions you are searching for.
-
archive_key1_exclude and archive_key2_exclude
Use these parameters to exclude executions with certain archive keys.
-
commented_only
Use this parameter to search only for executions that contain a comment.
-
modified_only
Use this parameter to search only for executions of workflows (JOBP) modified at runtime.
-
Remote status number and text
Use these parameters to search for executions processed by external systems based on their status in those applications.
Note: These parameters can be used in SAP, Database and Rapid Automation Jobs (JOBS), and for the RemoteTaskManager (JOBQ). In the case of SAP, SAP RemoteTaskManager and database jobs, you must define the message number of the remote status.
-
remote_status_number
Enter the message number of the execution you are searching for in the remote system.
The following values are possible:
-
SAP
6500 - scheduled
6501 - released
6502 - ready
6503 - running
6504 - finished
6505 - canceled
6514 - hold
2004972 - Waiting for SAP Server
-
DB
2012025 - Waiting for Database
-
-
remote_status_text
Enter the status of the execution in the remote system.
-
-
zdu_version
When upgrading the Automation Engine with the Zero Downtime Upgrade, both the current and the new versions run simultaneously, ensuring that all your processes can continue despite the upgrade.
Use zdu_version to search for executions processed in your current (B) or new (T) system, respectively.
-
sync_usage
Executions that do not start or finish due to dependencies defined in the Sync (SYNC) object assigned to them, receive the status Waiting for Sync.
Use sync_usage to search for executions that contain the relevant Sync object.
Note: This parameter allows you to use multiple values. You can either use the parameter once and separate the values with comas or use the parameter more than once in a request.
Important! Parameters that allow you to exclude certain properties are only effective in combination with their counterparts.
Example
name and name_exclude
-
../executions?name=SCRI1
The request includes executions with the name SCRI1.
-
../executions?name=SCRI&name_exclude=true
The request excludes executions with the name SCRI1.
You can combine the query parameters as required to build simple or complex filters. For example, you can:
-
Search for a specific execution name excluding deactivated executions
../executions?name=JOBS.24
-
Search for a specific execution name including deactivated executions
../executions?name=JOBS.24&include_deactivated=true
-
Search for a specific set of execution types
../executions?type=JOBP&type=JOBS
../executions?type=JOBP,JOBS
-
Search for an absolute time frame
../executions?time_frame_option=all&time_frame_from=2017-07-04T12:43:45Z&time_frame_to=2017-07-04T06:23:12Z
-
Use wildcards (supported for name, alias, agent, user and archive_key1&2)
../executions?name=NAME
../executions?alias=NAM*
-
Use complex filters
../executions?name=OBJECT&type=JOBP&type=JOBS&queue=CLIENT_QUEUE&queue=PRIO_QUEUE&status=1900,1800&include_deactivated=true&time_frame_option=all&time_frame_from=2017-07-04T12:43:45Z&time_frame_to=2017-07-04T06:23:12Z
../executions?name=OBJECT& type=JOBP,JOBS&platform=WIN,LINUX,BS2000&queue=CLIENT_QUEUE&status=1900&archive_key1=hallo&archive_key1_exclude=true&include_deactivated=true&commented_only=true&modified_only=true
Pagination for Child Task Executions and Execution Lists
Pagination can be useful if a request to the AE REST API returns numerous results, because the result set, which can change fast and often, 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:
-
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.
URI Structure with Pagination Parameters
The URI including the pagination parameters consists of the following elements:
http://{host}:{port}/ae/api/v1/{client}/executions/{runid}/children?max_results={number}&start_at_run_id={runid}
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 1
Request URI: ../executions/1003003/children?max_results=10
Response Payload: List of the first 10 executions
RunID of last execution listed =1003045
"hasmore"=true(*)
"total"=25(**)
Comment: If the parameter start_at_run_id is omitted, the first page is returned.
-
Page 2
Request URI: ../executions/1003003/children?max_results=10&start_at_run_id=1003045
Response Payload: List of the next 10 executions
RunID of first execution listed <1003045
RunID of last execution listed =1003034
"hasmore"=true(*)
"total"=25(**)
Comment: The RunID of the first execution on page 2 is lower than the RunID of the last execution on page 1, thus avoiding duplicate listings.
-
Page 3
Request URI: ../executions/1003003/children?max_results=10&start_at_run_id=1003034
Response Payload: List of the next 5 executions
RunID of first execution listed <1003034
RunID of last execution listed =1003028
"hasmore"=false(*)
"total"=25(**)
Comment: "hasmore"=false indicates that this is the last page.
-
* total: indicates the total number of resources in the collection and helps determine how many pages the result would have.
-
**hasmore: has the following possible values:
-
true = more pages are available
-
false = you have reached the last page
-
Notes:
-
The executions that are displayed on a given page are ordered by activation time and RunID descending.
-
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 is not listed neither on page P nor in any following page.
Pagination for Reports
Pagination is also useful when a report is rather large and its content is split into report pages. The AE REST API paginates these report pages.
Limit Parameters
-
max_results
Defines the maximum number of entries (report pages) returned.
Default value: 1
If this parameter is set to zero (0), no entries are returned.
-
start_at
Defines the number of the start page (entry/report page) returned.
Default value: 1
If this parameter is not defined, the entries returned start with the first report page. If the value defined is larger than the number of entries available, no information is returned, because the request exceeds the range of report pages available.
Example
-
...exectutions/{run id}/reports/REP returns the whole report (all report pages)
-
...exectutions/{run id}/reports/REP?max_results=3 returns the first chunk of three (3) report pages (report pages 1, 2, and 3)
-
...exectutions/{run id}/reports/REP?max_results=3&start_at=4 returns the second chunk of three (3) (report pages 4, 5, and 6)
-
...exectutions/{run id}/reports/REP?start_at=2 returns all report pages except the first one
-
Important! The AE REST API can only request the content of reports available in the AE database. A job report is stored in the database only if the Store to: Database option has been selected in the Job Report section of the job definition page. This option is selected by default.
Tracing
All REST activities can be traced for analysis purposes. To do so select a JCP and right-click to select Advanced Options. This action 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 RA Web Service REST Agent are:
- 0: Tracing disabled
- 1: Traces REST headers and content
- 2: Traces also login information
Web Server Configuration
The Automation Engine REST web service uses a web server which largely uses a predefined configuration. As a system administrator, you can customize the parameters that are listed here in [REST] section of the Automation Engine configuration file ucsrv.ini:
-
Cross-Origin Resource Sharing / Same Origin Policy (CORS/SOP)
-
corsSupportEnabled
-
corsAccessControlAllowOrigin
-
-
GZIP Compression
-
gzipSupportEnable
-
-
ThreadPool
-
minPoolSize
-
maxPoolSize
-
idleTimeout
-
CORS/SOP
The Same Origin Policy (SOP) prevents web clients from carrying out cross-origin requests. You can circumvent this policy using Cross-Origin Resource Sharing (CORS) to allow origins explicitly.
For example:
Host 3 requests a web document from origin 1 (Host 1, web server) at http://host1:80 (default http port). Host 3 then requests information from origin 2 (Host 2, AE) at http://host2:8080 (default AE REST web service port). The most common web browsers check whether cross domain requests are allowed or not. If not, the request to the second origin http://host2:8080 is not allowed.
To allow such cross origin requests, the AE REST web service must explicitly tell the web browser to allow the request. You can define it using the following CORS parameters in the [REST] section of the Automation Engine configuration file ucsrv.ini:
- corsSupportEnabled=1
- corsAccessControlAllowOrigin=http://host1:80
If the web server runs on the same local host as the browser or web client (Host1 = Host3), you must implement a simple web-based REST client by setting the parameter corsAccessControlAllowOrigin to http://localhost:80.
Compression
A REST client can state in a request that the response payload should be compressed to improve performance. If the REST web service supports compression, it sends back the payload in gzip format.
Compression support is disabled by default. You can enable it using the gzipSupportEnabled parameter in the [REST] section of the Automation Engine configuration file ucsrv.ini.
Thread Pooling
The web server that is used by the JCP/REST web service processes requests with help of threads. The more threads are used, the more REST requests can be processed in parallel.
A thread pool keeps multiple threads waiting to process REST requests. The more requests come in, the more threads the web server automatically makes available within the range that is defined in minPoolSize >= N <= maxPoolSize. If some of the N threads remain unused for a period longer than the timeout period defined in the idleTimeout parameter, these are killed to free resources on the JCP process.
See also:
- REST API Reference
- Analytics REST API - General Info
- Analytics REST API Key Management