/
Task Functions

Task Functions

Sept 25, 2023

Overview

The command line syntax for each execution of the CLI command, uagcmd, must specify a single CLI function, required / optional Global parameters, and required / optional function-specific parameters. You must use the required Global parameters to connect to OMS Servers and to log on to a Controller (User ID and Password).

Universal Controller supports the following CLI functions for Tasks, which are listed alphabetically on this page.

Syntax, parameters, and examples for each function are provided.

Cancel Task

Description

Cancels the specified task instance.
 
See Cancelling a Task Instance for a description of behavior and restrictions.

Syntax

uagcmd ops-task-cancel global parameters {task-instance-id=ID | task-instance-name=name} [instance-criteria=criteria] [workflow-instance-name=name]
 

Note

For backward-compatibility, you can exclude uagcmd from the command line for this function and all pre-6.2.0.0 CLI functions.

Parameter

  • task-instance=
    Required; An internal Universal Controller identifier.

Deprecated

Replaced by task-instance-id= parameter; the command first will check for task-instance=; if it is not specified, the command will check for task-instance-id=.

  • task-instance-id=
    Required if task-instance-name= is not specified; sys_id of the task instance to run the command on.

  • task-instance-name=
    Required if task-instance-id= is not specified; Name of the task instance to run the command on. (If instance-criteria= is not specified, the oldest active task instance with the matching name will apply.)

  • instance-criteria=
    Optional if task-instance-name= is specified; One of the following (not case-sensitive): oldest_active_instance (default), oldest_instance, newest_active_instance, newest_instance

  • workflow-instance-name=
    For a task instance in a workflow, optional; Name of the workflow instance.

Example

uagcmd ops-task-cancel -c config.cfg task-instance-name=Task A

Clear All Dependencies

Description

Clears all dependencies of a task instance.

Syntax

uagcmd ops-task-clear-dependencies global parameters {task-instance-id=ID | task-instance-name=name} [instance-criteria=criteria] [workflow-instance-name=name]

Parameters

  • task-instance-id=
    Required if task-instance-name= is not specified; sys_id of the task instance to run the command on.

  • task-instance-name=
    Required if task-instance-id= is not specified; Name of the task instance to run the command on. (If instance-criteria= is not specified, the oldest active task instance with the matching name will apply.)

  • instance-criteria=
    Optional, if task-instance-name= is specified; One of the following (not case-sensitive): oldest_active_instance (default), oldest_instance, newest_active_instance, newest_instance.

  • workflow-instance-name=
    For a task instance in a workflow, optional; Name of the workflow instance.

Example

uagcmd ops-task-clear-dependencies -c config.cfg task-instance-name=Task A

Clear Virtual Resource Dependencies

Description

Clears all virtual resource dependencies of a task instance.

Syntax

uagcmd ops-task-clear-resources global parameters {task-instance-id=ID | task-instance-name=name} [instance-criteria=criteria] [workflow-instance-name=name] resource-name=name

Parameters

  • task-instance-id=
    Required if task-instance-name= is not specified; sys_id of the task instance to run the command on.

  • task-instance-name=
    Required if task-instance-id= is not specified; Name of the task instance to run the command on. (If instance-criteria= is not specified, the oldest active task instance with the matching name will apply.)

  • instance-criteria=
    Optional, if task-instance-name= is specified; One of the following (not case-sensitive): oldest_active_instance (default), oldest_instance, newest_active_instance, newest_instance.

  • workflow-instance-name=
    For a task instance in a workflow, optional; Name of the workflow instance.

  • resource-name=
    Required; One of the following:

    • Name of the virtual resource dependency to clear.

    • An asterisk ( * ) to clear all virtual resource dependencies.

Example

uagcmd ops-task-clear-resources -c config.cfg task-instance-name=Task A resource-name=Resource A

Clear Exclusive Dependencies

Description

Clears all exclusive dependencies of a task instance.

Syntax

uagcmd ops-task-clear-exclusive global parameters {task-instance-id=ID | task-instance-name=name} [instance-criteria=criteria] [workflow-instance-name=name]

Parameters

  • task-instance-id=
    Required if task-instance-name= is not specified; sys_id of the task instance to run the command on.

  • task-instance-name=
    Required if task-instance-id= is not specified; Name of the task instance to run the command on. (If instance-criteria= is not specified, the oldest active task instance with the matching name will apply.)

  • instance-criteria=
    Optional, if task-instance-name= is specified; One of the following (not case-sensitive): oldest_active_instance (default), oldest_instance, newest_active_instance, newest_instance.

  • workflow-instance-name=
    For a task instance in a workflow, optional; Name of the workflow instance.

Example

uagcmd ops-task-clear-exclusive -c config.cfg task-instance-name=Task A

Clear Time Dependency

Description

Clears the time dependency of a task instance.

Syntax

uagcmd ops-task-clear-timewait global parameters {task-instance-id=ID | task-instance-name=name} [instance-criteria=criteria] [workflow-instance-name=name]

Parameters

  • task-instance-id=
    Required if task-instance-name= is not specified; sys_id of the task instance to run the command on.

  • task-instance-name=
    Required if task-instance-id= is not specified; Name of the task instance to run the command on. (If instance-criteria= is not specified, the oldest active task instance with the matching name will apply.)

  • instance-criteria=
    Optional, if task-instance-name= is specified; One of the following (not case-sensitive): oldest_active_instance (default), oldest_instance, newest_active_instance, newest_instance.

  • workflow-instance-name=
    For a task instance in a workflow, optional; Name of the workflow instance.

Example

uagcmd ops-task-clear-timewait -c config.cfg task-instance-name=Task A

Display All Tasks

Description

Displays all specified tasks.

Syntax

uagcmd ops-task-list global parameters task-name=name [task-type=type]
 

Note

For backward-compatibility, you can exclude uagcmd from the command line for this function and all pre-6.2.0.0 CLI functions.

Parameters

  • task-name=
    Optional; Name or partial name of one or more tasks. Wildcards are supported.

  • task-type=
    Optional; One of the following (not case sensitive): application_control, email, email_monitor, agent_file_monitor, ftp, remote_file_monitor, indesca / universal_command / ucmd, manual, sap, peoplesoft, sql, stored_procedure, system_monitor, task_monitor, timer, unix, variable_monitor, web_service, windows, workflow, zos.

Example

uagcmd ops-task-list -c config.cfg task-name=Task A task-type=timer

Display Task Instance Status

Description

Displays the status of all task instance(s) associated with the specified task.

Syntax

uagcmd ops-task-status global parameters task-instance-name=name [agent-name=name] [task-type=type] [task-status=status] [{workflow-instance-id=id] | [workflow-instance-name=name}] [workflow-instance-criteria=criteria] [options=v]
 

Note

For backward-compatibility, you can exclude uagcmd from the command line for this function and all pre-6.2.0.0 CLI functions.

Parameters

  • task-name=
    Required; Name or partial name of one or more tasks. Wildcards are supported. 

Deprecated

Replaced by task-instance-name= parameter; the command first will check for task-name=; if it is not specified, the command will check for task-instance-name=.

  • task-instance-name=
    Optional; Name of the task instance(s) to be listed. Wildcards are supported.

  • agent-name=
    Optional; Name of the agent the task instance(s) are running on.

  • task-type=
    Optional; One of the following (not case sensitive): application_control, email, email_monitor, agent file_monitor, ftp, remote_file_monitor, indesca / universal_command / ucmd, manual, sap, peoplesoft, sql, stored_procedure, system_monitor, task_monitor, timer, unix, variable_monitor, web_service, windows, workflow, zos.

  • task-status=
    Optional; List of comma-separated task status codes and/or names (not case sensitive): status code or name,status code or name,...,status code or name. An exclamation mark (!) preceding a task status code or name excludes task instances with that status.

  • workflow-instance-id=
    For a task instance in a workflow, optional if workflow-instance-name= is not specified; sys_id of the workflow instance.

  • workflow-instance-name=
    For a task instance in a workflow, optional if workflow-instance-id= is not specified; Name of the workflow instance. (If workflow-instance-criteria= is not specified, the oldest active Workflow instance with the matching name will apply.)

  • workflow-instance-criteria=
    Optional, if workflow-instance-name= is specified; One of the following (not case-sensitive): oldest_active_instance (default), oldest_instance, newest_active_instance, newest_instance.

  • options=
    Optional; v (Return verbose results.)

Example

uagcmd ops-task-status -c config.cfg task-instance-name=mantask agent-name=managent task-type=manual

Task Instance Status Types

The following table describes all possible task instance statuses for all task types.

Note

The format of multi-word task status names specified in the Task Instance Status CLI function differs from the format of task status names used in the Controller user interface. In Task Instance Status, the words are separated by an underscore character; in the user interface, they are separated by a space.

Status Name

Status Code

Task Type

Description

Action_Required

60

Manual

When a manual task launches, it goes into Action Required status, meaning a user must perform some manual activity. For details, see Manual task.

Cancel_Pending

99

Agent-based

A process running on the Agent needs to be terminated. When the Cancel command is issued, the task instance will go into a Cancel Pending status until the Agent reports back that the process has been cancelled. At that point, the task instance will transition into the Cancelled status.

Cancelled

130

All

The task was cancelled by a user.

Confirmation_Required

125

z/OS