Managing a task definition from the Orchestration CLI

In this topic you can find the syntax to manage a task definition.

In a HCL Universal Orchestrator distributed environment, tasks can be defined either independently from workflows or within a workflow definition.

When creating an item, you can define it in a folder. If no folder path is specified, then the item definition is created in the default folder. By default, it is the root (/) folder, but you can customize it to a different folder path. For more information, see: Configuring the Orchestration CLI.

To create new task definitions, the file must start with $jobs. Each task definition has the following format and arguments:

Syntax

[[folder/]workstation#][folder/]jobname
   {task job_definition }
   [description "description"]

   [succoutputcond Condition_Name "Condition_Value"]
   [outputcond Condition_Name "Condition_Value"]

To add dependencies to a task definition, you must include them in a workflow definition.

Note: It is important to correctly type the keywords, otherwise they are considered as the task name of a new task definition and it can cause errors during the creation process.

When assigning an alias to a task, ensure that the name is not already used for another task in the same workflow.

The following example shows how the renaming of a task definition can affect the tasks:

Table 1. Example: renaming the task definition
Original task definition names in workflows	Rename task definition	Outcome
SCHEDULE `[folder/]`WKS#/APPS/DEV/WF : `[folder/]`WKS#/APPS/DEV1/A `[folder/]`WKS#/APPS/DEV1/B as C END	Rename task A to D	SCHEDULE`[folder/]` WKS#/APPS/DEV/WF : `[folder/]`WKS#/APPS/DEV1/D `[folder/]`WKS#/APPS/DEV1/B as C END
	Rename task B to D	SCHEDULE WKS#WF : WKS#/APPS/DEV1/A WKS#/APPS/DEV1/D as C END
	Rename task /APPS/DEV1/A to C	An error occurs when renaming task A to C because task C already exists as the alias for task B.

Arguments

[folder/]workstation#

Using this keyword, you can define the name of the workstation on which tasks run. The default workstation is the one defined as defaultws in the Orchestration CLI configuration file. A number sign (#) must be placed after the workstation keyword.

[folder/]jobname

Using this keyword, you can define the name of the folder that contains the task definition.

The name must start with a letter, and can contain alphanumeric characters, dashes, and underscores.

If no folder is defined for an item, the default folder (/) is used. For more information, see: Configuring the Orchestration CLI.

task job_definition

Using this keyword, you can define a task definition. Each task type has a specific syntax.

For more information about syntax and all supported integrations, see Automation Hub.

description "description"

Using this keyword, you can specify a description for the task.

The content must be enclosed within double quotation marks. To use quotation marks ("), place a backslash (\) before.

Affinity

You can add this optional attribute in the task definition to run a specific task on the same workstation where the main task runs. For more information, see Affinity.

succoutputcond Condition_Name "Condition_Value"

Using this condition, a successor task starts only after the predecessor task or workflow has successfully completed. When this condition is satisfied, the task status is set to SUCC. You can also use this condition to define alternative flows in workflows by specifying the conditions the predecessor task or workflows needs to satisfy before the successor task can start running. Any JSONata boolean expression is accepted. For more information, see: Proprietary functions for JSONata

You can define one or more conditions as follows:

A return code

You can define which return code indicates that the task has successfully completed. Return codes can be expressed in the following ways:

Comparison expression

You can use the following syntax to define a return code for a task:

(RC operator operand)

RC

You can use this keyword to specify the return code.

operator

You can use this keyword to specify a comparison operator. You can find the possible values below:

Table 2. Comparison operators
Example	Operator	Description
RC<value	<	Less than
RC<=value	<=	Less than or equal to
RC>value	>	Greater than
RC>=value	>=	Greater than or equal to
RC=value	=	Equal to
RC!=value	!=	Not equal to

operand

You can use this keyword to specify an integer.

Boolean expression

You can use the following syntax to specify a logical combination of comparison expressions:

comparison_expression operator comparison_expression

comparison_expression

Expressions are evaluateted from left to right. You can assign a priority to the expression evaluation by using parenthesis ().

operator

You can use this keyword to specify a logical operator. You can find the possible values below:

Table 3. Logical operators
Example	Operator	Result
expr_a and expr_b	and	TRUE if both expr_a and expr_b are TRUE.
expr_a or expr_b	or	TRUE if either expr_a or expr_b is TRUE.
$not (expr_a)	$not	TRUE if expr_a is not TRUE.

For example, you can define a successful task as a task that ends with a return code less than or equal to 3 or with a return code not equal to 5, and less than 10 as follows:

SUCCOUTPUTCOND "(RC<=3) or ((RC!=5) and (RC<10))"

A task state

You can define which task status indicates that the task has successfully completed.

An output variable

You can use output variables to qualify a task as successfully completed. You can set a success condition or other conditions for a task in the following ways:

Analyzing the task properties:
```
$this().File.1.Size>0
```
The expression in the example qualifies a file transfer task as successful when the size of the file that has been transferred is greater than zero.
Analyzing the task properties or the task output of another task in the same workflow:
```
$this().NumberOfTransferredFiles=
job.DOWNLOAD.NumberOfTransferredFiles
```
The expression in the example qualifies a file transfer task as successful when the number of files that have been uploaded in the task equals the number of the files that have been uploaded in another task (named DOWNLOAD), in the same workflow.
All JSONata functions and expressions are supported, for the above conditions, in the succoutputcond field:
- String comparisons (contains, starts-with, matches, and so on)
- String manipulations (concat, substring, uppercase, and so on)
- Numeric comparison (=, !=, >, and so on)
- Functions on numeric values (abs, floor, round, and so on)
- Operators on numeric values (add, sum, div, and so on)
- Boolean operators

outputcond Condition_Name "Condition_Value"

When satisfied, this output condition defines which task runs as successor. You can define the conditions with the same format used for SUCCOUTPUTCOND. You can find some examples of output conditions below.

You can define an output condition that indicates that the predecessor task has completed with errors in the following way:

OUTPUTCOND STATUS_ERR1 "RC=1": Using this format, you create a condition that is named "STATUS_ERR1" which indicates that if the predecessor task has completed with a return code equal to 1, then the task has completed with errors.

OUTPUTCOND BACKUP_FLOW "RC != 5 and RC > 2": Using this format, you create a condition that is named "BACKUP_FLOW", which indicates that if the predecessor task satisfies that condition, then the successor task runs.

Examples

The following example defines a task named JOB1 that runs the netstat-an command:

$JOBS
WS_AGT_0#/FOLDER1/TASK1
DOCOMMAND "netstat -an"
 STREAMLOGON "wauser"
 TASKTYPE WINDOWS
RECOVERY STOP

After saving the definition, you can see it displayed as follows:

$job

/WS_AGT_0#/FOLDER1/TASK1
  TASK
    {
      "executable" : {
        "script" : "netstat -an",
        "credential" : {
          "userName" : "wauser",
          "password" : "${password:wauser}"
        }
      }
    }
  RECOVERY STOP

The following example defines a task named TASKDEF1 that runs the ls command:

$JOBS

WS_AGT_0#TASKDEF1
  TASK
    <?xml version="1.0" encoding="UTF-8"?>
    <jsdl:jobDefinition xmlns:jsdl="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdl" xmlns:jsdle="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdle">
    <jsdl:application name="executable">
    <jsdle:executable interactive="false">
    <jsdle:script>ls</jsdle:script>
    </jsdle:executable>
    </jsdl:application>
    </jsdl:jobDefinition>
  DESCRIPTION "Sample jsdl Task Definition"
  SUCCOUTPUTCOND COND1 "RC>=0"

After saving the definition, you can see it displayed as follows:

$job

/WS_AGT_0#/TASKDEF1
  DESCRIPTION "Sample jsdl Task Definition"
  TASK
    {
      "executable" : {
        "interactive" : false,
        "suffix" : "",
        "script" : "ls",
        "credential" : { }
      }
    }
  SUCCOUTPUTCOND COND1 "RC>=0"
  RECOVERY STOP

The following example defines a task named TASKDEF1, without specifying a workstation:

$JOBS

JOBDEF1
  TASK
    <?xml version="1.0" encoding="UTF-8"?>
    <jsdl:jobDefinition xmlns:jsdl="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdl" xmlns:jsdle="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdle">
    <jsdl:application name="executable">
    <jsdle:executable interactive="false">
    <jsdle:script>dir</jsdle:script>
    </jsdle:executable>
    </jsdl:application>
    </jsdl:jobDefinition>
  DESCRIPTION "Sample jsdl Task Definition"

By default, if the workstation is not specified, the task is saved on the workstation defined in the config.yaml file. After saving the definition, you can see it displayed as follows:

$job

/WS_AGT_0#/TASKDEF1
  DESCRIPTION "Sample jsdl Task Definition"
  TASK
    {
      "executable" : {
        "interactive" : false,
        "suffix" : "",
        "script" : "dir",
        "credential" : { }
      }
    }
  RECOVERY STOP

Managing a task definition from the Orchestration CLI

Syntax

Arguments

See also