AE REST API documentation
http[s]://{host}:{port}/ae/api/{version}
The AE REST API provides an interface for 3rd party applications to interact with the Automation Engine. It allows you to target the AE from many programming languages, not only from Java. The AE REST API will eventually expose the most important AE API features for 3rd party developers. Currently it only supports the following features:
- triggering/monitoring of executions
- object searches
Please see the AE Java API if you are looking for a more comprehensive API.
Required URI Parameters:
- host: required (string)
The host (IP address or hostname) on which the JCP is running
- port: required (string)
Port of the JCP as configured in the REST section of ucsrv.ini
- version: required (string)
API version, must be v1
/{client_id}
search the process assembly for objects
Example https://localhost:8088/ae/api/v1/100/search
post /{client_id}/search
search the process assembly for objects
Example https://localhost:8088/ae/api/v1/100/search
URI Parameters
- client_id: required (string - minLength: 4 - maxLength: 4 - pattern: [0-9]{4})
Number/ID of the client.
Body
Media type: application/json
Type: object
Properties- filters: required (string)
- type: required (array of filter)
Items: filter
- filter_identifier: required (string)
name of the filter
- filter_parameter_1: required (string)
parameter of filter
- filter_parameter_N: required (string)
n-th parameter of filter
- filter_identifier: required (string)
- description: required (array of filter objects that specifies your search query. Only objects that match all filters are included in the result list. Each filter consists of a filter identifier and various parameters. Please see FILTER DOCU section below for the different filters and their arguments)
- _FILTER_DOCU_: (object)
this objects documents the search filters and their settings. It exists for documentation reasons only and must not be included in the request POST body.
- location: (filter)
finds objects by their folder location
- filter_identifier: required (string)
must be 'location'
- location: required (string)
the path to which the search should be restricted, using \\ as separator
- include_links: (boolean - default: false)
whether links should also be included in the search
- include_subfolders: (boolean - default: false)
whether subfolders of path should be included in the search
- filter_identifier: required (string)
- object_name: (filter)
searches for object names, also supports placeholder signs
- filter_identifier: required (string)
must be 'object_name'
- object_name: required (string)
the object name to look for including ? and * placeholder signs
- filter_identifier: required (string)
- object_type: (filter)
finds objects by their object type
- filter_identifier: required (string)
must be 'object_type'
- object_types: required (array of string)
list of object-types the search result can include
- filter_identifier: required (string)
- time_frame: (filter)
searches for objects that were created create/modified/used within the given timeframe. Note: queries for object usage only return results if the LAST_USE property has been enabled in UC_SYSTEM_SETTINGS.
- process: (filter)
search in scripts of the process sheet (full-text)
- filter_identifier: required (string)
must be 'process'
- query: required (string)
the text you want to search for
- filter_identifier: required (string)
- archive_key: (filter)
search in archive keys
- filter_identifier: required (string)
must be 'archive_key'
- query: required (string)
the text you want to search for
- filter_identifier: required (string)
- title: (filter)
search in object titles
- filter_identifier: required (string)
must be 'title'
- query: required (string)
the text you want to search for
- filter_identifier: required (string)
- variable_key: (filter)
searches for variable keys inside of STATIC VARA objects
- filter_identifier: required (string)
must be 'variable_key'
- query: required (string)
the variable key to look for
- filter_identifier: required (string)
- variable_value: (filter)
searches for variable keys inside of STATIC VARA objects
- filter_identifier: required (string)
must be 'variable_value'
- query: required (string)
the variable value to look for
- all_columns: required (string)
true if secondary variable value is to be included in search as well, false if only primary value (Value 1) is to be searched
- type: required (one of ANY, NUMBER, TEXT, TIME, DATE, DATETIME)
data type of the value
- filter_identifier: required (string)
- documentation: (filter)
search in object's documentation(full-text)
- filter_identifier: required (string)
must be 'documentation'
- query: required (string)
the text you want to search for
- filter_identifier: required (string)
- calendar_event: (filter)
searches for events with the given event name that are valid on the given date
- filter_identifier: required (string)
must be 'calendar_event'
- query: required (string)
name of the calendar event (may contain placeholder characters).
- valid_on_date: (integer)
the date the calendar event must be valid on, given in Unix time
- filter_identifier: required (string)
- location: (filter)
- max_results: required (integer)
the maximum number of results the query should return
- start_at: required (integer)
- sort_columns: required (object)
determines sort order of result columns
- location_path: (boolean)
- name: (boolean)
- title: (boolean)
- modification_date: (boolean)
- archive_key1: (boolean)
- archive_key2: (boolean)
Example:
{
"filters": [{
"filter_identifier": "object_name",
"object_name": "*JO*"
}, {
"filter_identifier": "location",
"location": "\\PACKAGES\\PCK.AUTOMIC_ANALYTICS\\SOURCE",
"include_subfolders": true
}],
"max_results": 3
}
HTTP status code 200
OK - the server has processed your request successfully.
Body
Media type: application/json
Type: object
Properties- total_size: required (integer)
Number of total elements matching query data.
- data: required (array of result)
Return data.
Items: result
- name: required (string)
Unique name of the object
- type: required (string)
Object type
- id: required (string)
DB id of object
- title: required (string)
Objects title
- archive_key1: required (string)
First archive key
- archive_key2: required (string)
Second archive key
- folder_path: required (string)
Path to parent folder in folder hierarchy
- folder_id: required (string)
DB id of parent folder
- modified_date: required (long)
Last modification date of object
- last_used_date: required (long)
Last usage date of object
- link: required (boolean)
True if object is a link
- score: required (float)
Search relevancy score to the searched term
- creation_date: required (long)
Date of the actual object creation. (Not link creation)
- name: required (string)
- update_timestamp: required (long)
timestamp of the index update that this result list was created from.
Example:
{
"data": [
{
"name": "JOBS",
"type": "FOLD",
"id": "1000203",
"title": null,
"archive_key1": null,
"archive_key2": null,
"folder_path": "\\PACKAGES\\PCK.AUTOMIC_ANALYTICS\\SOURCE\\DATASTORE_INFO\\INTERNAL",
"folder_id": "1000201",
"modified_date": 1502112498000,
"last_used_date": null,
"link": false,
"score": 0.3235811,
"creation_date": 1502112498000
},
{
"name": "JOBS",
"type": "FOLD",
"id": "1000196",
"title": null,
"archive_key1": null,
"archive_key2": null,
"folder_path": "\\PACKAGES\\PCK.AUTOMIC_ANALYTICS\\SOURCE\\DATASTORE_DELETE\\INTERNAL",
"folder_id": "1000194",
"modified_date": 1502112498000,
"last_used_date": null,
"link": false,
"score": 0.3235811,
"creation_date": 1502112498000
},
{
"name": "JOBS",
"type": "FOLD",
"id": "1000210",
"title": null,
"archive_key1": null,
"archive_key2": null,
"folder_path": "\\PACKAGES\\PCK.AUTOMIC_ANALYTICS\\SOURCE\\DATASTORE_RESTORE\\INTERNAL",
"folder_id": "1000208",
"modified_date": 1502112498000,
"last_used_date": null,
"link": false,
"score": 0.3235811,
"creation_date": 1502112498000
}
],
"total": 18,
"hasmore": true,
"update_timestamp": 1502119443058
}
HTTP status code 400
Bad Request - the server could not understand the request due to invalid syntax (e.g. wrong JSON attributes or data types). Do not send the request again before you fixed its errors.
Body
Media type: application/json
Type: object
Properties- message: required (string)
- details: (string)
a more detailed explanation of the error containing information for debugging
HTTP status code 401
Unauthorized - the client lacks valid authentication credentials, i.e. you used a non-existing username/password. Also triggered if the authorisation service is not available.
Body
Media type: application/json
Type: object
Properties- message: required (string)
- details: (string)
a more detailed explanation of the error containing information for debugging
Example:
{
"details": "The credentials (user/dept/pwd) are not valid.",
"code": 45107,
"error": "Cannot logon to Automation Engine."
}
HTTP status code 404
Not found - the server could not find the requested resource, i.e. you probably have a typo in the REST endpoint URL.
Body
Media type: application/json
Type: object
Properties- message: required (string)
- details: (string)
a more detailed explanation of the error containing information for debugging
HTTP status code 500
Internal Server Error - the request failed due to an unexpected server condition (e.g. misconfiguration, temporary overload). Try to resend the request and contact the server administrator if the issue persists. Note that HTTP 500 also serves as a "catch-all" code if none of the other error codes apply.
Body
Media type: application/json
Type: object
Properties- message: required (string)
- details: (string)
a more detailed explanation of the error containing information for debugging
Example:
{
"details": "The credentials (user/dept/pwd) are not valid.",
"code": 45107,
"error": "Cannot logon to Automation Engine."
}
Execute an object with or without input parameters (promptsets variables).
Example https://localhost:8088/ae/api/v1/100/executions
post /{client_id}/executions
Execute an object with or without input parameters (promptsets variables).
Example https://localhost:8088/ae/api/v1/100/executions
URI Parameters
- client_id: required (string - minLength: 4 - maxLength: 4 - pattern: [0-9]{4})
Number/ID of the client.
Body
Media type: application/json
Type: object
Properties- object_name: required (string - minLength: 1 - maxLength: 200 - pattern: [A-Z0-9-_.@]{1,200})
Name of the object to be executed.
- inputs: (object)
Optional list of promptsets variables to be passed.
- type: required (object)
Defines a variable as string:string pair ("variable":"value")
- [A-Z0-9$@._-]{31}[#]: required (string)
- type: required (object)
Examples:
Without:
{
"object_name": "SCRI.NEW.1"
}
With:
{
"object_name": "SCRI.NEW.1",
"inputs":
{
"TEXT1#": "passed text",
"NUMBER1#": "1234",
"COMBOBOX1#": "Installation",
"RADIOGROUP1#": "Windows",
"CHECKBOX1#": ["Low", "Critical", "Irrelevant"],
"DATETIME1#": "170730",
"TEXT100#": "another passed text",
"NUMBER100#": "7777"
}
}
HTTP status code 200
Object successfully executed, RunId returned.
Body
Media type: application/json
Type: integer
Example:
{
"run_id": 1074003
}
HTTP status code 400
Bad request - request data is invalid or does not fit the business logic
Code | Description |
---|---|
45111 | Object to be executed has to have the attribute "generate at runtime" set |
45113 | Given string is not a valid object name |
45114 | Given string is not a valid execution option |
45115 | Object to be executed is not an execuable one |
Body
Media type: application/json
Type: object
Properties- code: (integer - minimum: 1 - maximum: 99999999)
Optional error number.
- error: (string - maxLength: 1024)
General error information.
- details: (string)
Detail error information.
Example:
{
"code": 45106,
"error": "The request is invalid and cannot be processed by the Automation Engine.",
"details": "The object to be executed is not an executable one."
}
HTTP status code 401
Unathorized accesss - login data not valid.
Body
Media type: application/json
Type: object
Properties- code: (integer - minimum: 1 - maximum: 99999999)
Optional error number.
- error: (string - maxLength: 1024)
General error information.
- details: (string)
Detail error information.
HTTP status code 403
Forbidden - the user is not allowed to access the resource.
Body
Media type: application/json
Type: object
Properties- code: (integer - minimum: 1 - maximum: 99999999)
Optional error number.
- error: (string - maxLength: 1024)
General error information.
- details: (string)
Detail error information.
HTTP status code 404
The resource is not available.
Body
Media type: application/json
Type: object
Properties- code: (integer - minimum: 1 - maximum: 99999999)
Optional error number.
- error: (string - maxLength: 1024)
General error information.
- details: (string)
Detail error information.
HTTP status code 500
Internal error occured.
Body
Media type: application/json
Type: object
Properties- code: (integer - minimum: 1 - maximum: 99999999)
Optional error number.
- error: (string - maxLength: 1024)
General error information.
- details: (string)
Detail error information.
Get details about an execution by RunId.
Example https://localhost:8088/ae/api/v1/100/executions/2004015
get /{client_id}/executions/{run_id}
Get details about an execution by RunId.
Example https://localhost:8088/ae/api/v1/100/executions/2004015
URI Parameters
- client_id: required (string - minLength: 4 - maxLength: 4 - pattern: [0-9]{4})
Number/ID of the client.
- run_id: required (integer - minimum: 1000000 - maximum: 99999999)
RunID of the execution.
HTTP status code 200
Returns information about specific execution.
Body
Media type: application/json
Type: object
Properties- description: (string)
Description text of the executed object.
- status_text: required (string)
Status text description.
- parent: (integer - minimum: 1000000 - maximum: 99999999)
RunID of the parent execution (subordinated tasks only).
- run_id: required (integer - minimum: 1000000 - maximum: 99999999)
RunID of the execution.
- name: required (string - minLength: 1 - maxLength: 200 - pattern: [A-Z0-9-_.@]{1,200})
Name of the executed object.
- start_time: (datetime-only)
Time the execution was started.
- type: required (one of AgentGroup Container, CallAPI, Cockpit, Dynamic Job, Event, FileTransfer, Group, Job, Notification, Period Container, RemoteTaskManager, Report, Schedule, Script, Workflow)
Execution type that describes how the execution has been started.
- agent: (string - minLength: 1 - maxLength: 200 - pattern: [A-Z0-9-_.@]{1,200})
Name of agent that ran the execution (agent related executions only).
- end_time: (datetime-only)
Time the execution ended.
- status: required (integer)
Current status of the execution.
- runtime: required (integer)
Runtime of the execution.
- activation_time: required (datetime-only)
Time the execution was activated.
- user: required (string - minLength: 1 - maxLength: 200 - pattern: [A-Z0-9-_.@/]{1,200})
Name of the user (user object) that started the execution.
- platform: (string)
Platform of agent that ran the execution (agent related executions only).
Example:
{
"name": "WIN.START_TOMCAT",
"type": "Job",
"run_id": 2003103,
"status": 1900,
"status_text": "ENDED_OK - Task ended normally.",
"runtime": 60,
"description": "The best task ever",
"activation_time": "2015-04-15T06:37:59Z",
"start_time": "2015-04-15T06:37:59Z",
"end_time": "2015-04-15T06:38:59Z",
"agent": "WIN01",
"platform": "WIN64",
"parent": 2003101,
"user": "AUTOMIC/AUTOMIC"
}
HTTP status code 400
Bad request - request data is invalid
Code | Description |
---|---|
45109 | The requested resource cannot be found |
Body
Media type: application/json
Type: object
Properties- code: (integer - minimum: 1 - maximum: 99999999)
Optional error number.
- error: (string - maxLength: 1024)
General error information.
- details: (string)
Detail error information.
Example:
{
"code": 45106,
"error": "The request is invalid and cannot be processed by the Automation Engine.",
"details": "The object to be executed is not an executable one."
}
HTTP status code 401
Unathorized accesss - login data not valid.
Body
Media type: application/json
Type: object
Properties- code: (integer - minimum: 1 - maximum: 99999999)
Optional error number.
- error: (string - maxLength: 1024)
General error information.
- details: (string)
Detail error information.
HTTP status code 403
Forbidden - the user is not allowed to access the resource.
Body
Media type: application/json
Type: object
Properties- code: (integer - minimum: 1 - maximum: 99999999)
Optional error number.
- error: (string - maxLength: 1024)
General error information.
- details: (string)
Detail error information.
HTTP status code 404
The resource is not available.
Body
Media type: application/json
Type: object
Properties- code: (integer - minimum: 1 - maximum: 99999999)
Optional error number.
- error: (string - maxLength: 1024)
General error information.
- details: (string)
Detail error information.
HTTP status code 500
Internal error occured.
Body
Media type: application/json
Type: object
Properties- code: (integer - minimum: 1 - maximum: 99999999)
Optional error number.
- error: (string - maxLength: 1024)
General error information.
- details: (string)
Detail error information.
Changes the status of an execution.
Example https://localhost:8088/ae/api/v1/100/executions/2004015/status
post /{client_id}/executions/{run_id}/status
Changes the status of an execution.
Example https://localhost:8088/ae/api/v1/100/executions/2004015/status
URI Parameters
- client_id: required (string - minLength: 4 - maxLength: 4 - pattern: [0-9]{4})
Number/ID of the client.
- run_id: required (integer - minimum: 1000000 - maximum: 99999999)
RunID of the execution.
Body
Media type: application/json
Type: object
Properties- action: required (one of restart, cancel)
- restart: (object)
Set of restart parameters (in case of "action"="restart").
- queue: required (string - minLength: 1 - maxLength: 200 - pattern: [A-Z0-9-_.@]{1,200})
- cancel: (object)
Cancel execution (in case of "action"="cancel").
- recursive: (boolean - default: false)
Optionally cancel revursive for workflows, schedules, and group objects
- recursive: (boolean - default: false)
Examples:
Restart:
{
"action": "restart"
}
Cancel:
{
"action": "cancel",
"cancel": {
"recursive": true
}
}
HTTP status code 200
Execution status has been changed successfully?.
Body
Media type: application/json
Type: object
Properties- run_id: (integer - minimum: 1000000 - maximum: 99999999)
System-wide and unique identification number of an execution.
Example:
Restart:
{
"run_id": 1074003
}
HTTP status code 400
Bad request - request data is invalid.
Body
Media type: application/json
Type: object
Properties- code: (integer - minimum: 1 - maximum: 99999999)
Optional error number.
- error: (string - maxLength: 1024)
General error information.
- details: (string)
Detail error information.
Example:
{
"code": 45106,
"error": "The request is invalid and cannot be processed by the Automation Engine.",
"details": "The object to be executed is not an executable one."
}
HTTP status code 401
Unathorized accesss - login data not valid.
Body
Media type: application/json
Type: object
Properties- code: (integer - minimum: 1 - maximum: 99999999)
Optional error number.
- error: (string - maxLength: 1024)
General error information.
- details: (string)
Detail error information.
HTTP status code 403
Forbidden - the user is not allowed to access the resource.
Body
Media type: application/json
Type: object
Properties- code: (integer - minimum: 1 - maximum: 99999999)
Optional error number.
- error: (string - maxLength: 1024)
General error information.
- details: (string)
Detail error information.
HTTP status code 404
The resource is not available.
Body
Media type: application/json
Type: object
Properties- code: (integer - minimum: 1 - maximum: 99999999)
Optional error number.
- error: (string - maxLength: 1024)
General error information.
- details: (string)
Detail error information.
HTTP status code 500
Internal error occured.
Body
Media type: application/json
Type: object
Properties- code: (integer - minimum: 1 - maximum: 99999999)
Optional error number.
- error: (string - maxLength: 1024)
General error information.
- details: (string)
Detail error information.
Gets all immediate execution children.
Example https://localhost:8088/ae/api/v1/100/executions/2004015/children?max_results=10&start_at_run_id=2030130
get /{client_id}/executions/{run_id}/children
Gets all immediate execution children.
Example https://localhost:8088/ae/api/v1/100/executions/2004015/children?max_results=10&start_at_run_id=2030130
URI Parameters
- client_id: required (string - minLength: 4 - maxLength: 4 - pattern: [0-9]{4})
Number/ID of the client.
- run_id: required (integer - minimum: 1000000 - maximum: 99999999)
RunID of the execution.
Query Parameters
- max_results: (integer - default: 50)
Pagination info - maximum number of executions for a page result set. If this parameter is omitted the default value 50 is applied.
- start_at_run_id: (integer)
Pagination info - requested page starts with execution with RunID > this parameter. If this parameter is omitted (no offset) the very first page is returned.
HTTP status code 200
Returns a list of children executions
Body
Media type: application/json
Type: object
Properties- hasmore: required (boolean)
Pagination info - indicates if there are more results than currently returned.
- total: required (integer)
Pagination info - determines the total number of items.
- data: required (array of Execution)
Items: Execution
- description: (string)
Description text of the executed object.
- status_text: required (string)
Status text description.
- parent: (integer - minimum: 1000000 - maximum: 99999999)
RunID of the parent execution (subordinated tasks only).
- run_id: required (integer - minimum: 1000000 - maximum: 99999999)
RunID of the execution.
- name: required (string - minLength: 1 - maxLength: 200 - pattern: [A-Z0-9-_.@]{1,200})
Name of the executed object.
- start_time: (datetime-only)
Time the execution was started.
- type: required (one of AgentGroup Container, CallAPI, Cockpit, Dynamic Job, Event, FileTransfer, Group, Job, Notification, Period Container, RemoteTaskManager, Report, Schedule, Script, Workflow)
Execution type that describes how the execution has been started.
- agent: (string - minLength: 1 - maxLength: 200 - pattern: [A-Z0-9-_.@]{1,200})
Name of agent that ran the execution (agent related executions only).
- end_time: (datetime-only)
Time the execution ended.
- status: required (integer)
Current status of the execution.
- runtime: required (integer)
Runtime of the execution.
- activation_time: required (datetime-only)
Time the execution was activated.
- user: required (string - minLength: 1 - maxLength: 200 - pattern: [A-Z0-9-_.@/]{1,200})
Name of the user (user object) that started the execution.
- platform: (string)
Platform of agent that ran the execution (agent related executions only).
- description: (string)
Example:
{
"data":
[
{
"name": "WIN.START_TOMCAT",
"type": "Job",
"run_id": 2003103,
"status": 1900,
"status_text": "ENDED_OK - Task ended normally.",
"runtime": 60,
"description": "The best task ever",
"activation_time": "2015-04-15T06:37:59Z",
"start_time": "2015-04-15T06:37:59Z",
"end_time": "2015-04-15T06:38:59Z",
"agent": "WIN01",
"platform": "WIN64",
"parent": 41220406,
"user": "AUTOMIC/AUTOMIC"
},
{
"name": "MY.WF.56",
"type": "Workflow",
"run_id": 2003105,
"status": 1900,
"status_text": "ENDED_OK - Task ended normally.",
"runtime": 21,
"description": "Onboarding workflow",
"activation_time": "2015-04-13T08:12:23Z",
"start_time": "2015-04-13T08:12:23Z",
"end_time": "2015-04-13T08:12:44Z",
"user": "AUTOMIC/AUTOMIC"
}
],
"total": 2,
"hasmore": false
}
HTTP status code 400
Bad request - request data is invalid.
Body
Media type: application/json
Type: object
Properties- code: (integer - minimum: 1 - maximum: 99999999)
Optional error number.
- error: (string - maxLength: 1024)
General error information.
- details: (string)
Detail error information.
Example:
{
"code": 45106,
"error": "The request is invalid and cannot be processed by the Automation Engine.",
"details": "The object to be executed is not an executable one."
}
HTTP status code 401
Unathorized accesss - login data not valid.
Body
Media type: application/json
Type: object
Properties- code: (integer - minimum: 1 - maximum: 99999999)
Optional error number.
- error: (string - maxLength: 1024)
General error information.
- details: (string)
Detail error information.
HTTP status code 403
Forbidden - the user is not allowed to access the resource.
Body
Media type: application/json
Type: object
Properties- code: (integer - minimum: 1 - maximum: 99999999)
Optional error number.
- error: (string - maxLength: 1024)
General error information.
- details: (string)
Detail error information.
HTTP status code 404
The resource is not available.
Body
Media type: application/json
Type: object
Properties- code: (integer - minimum: 1 - maximum: 99999999)
Optional error number.
- error: (string - maxLength: 1024)
General error information.
- details: (string)
Detail error information.
HTTP status code 500
Internal error occured.
Body
Media type: application/json
Type: object
Properties- code: (integer - minimum: 1 - maximum: 99999999)
Optional error number.
- error: (string - maxLength: 1024)
General error information.
- details: (string)
Detail error information.