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:

• AE REST API - General Info
• REST API Reference