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.
-
type
You can add query parameters to filter for the following object types: CALL, CBCK, 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.
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.
-
More information:
- ALIAS_SPECIAL_CHARACTERS
- Object Types
- System Return Codes of Executable Objects
- Zero Downtime Upgrade
- Sync (SYNC)
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
-
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
See also: