Managing a job definition from the Orchestration CLI

In a HCL Universal Orchestrator distributed environment, jobs can be defined either independently from job streams or within a job stream 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 Orchestration CLI.

To create new job definitions, the file must start with $jobs. Each job 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 job definition, you must include them in a job stream definition.

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

The following example shows how the renaming of a job definition can affect the jobs:

Arguments

[folder/]workstation#

Using this keyword, you can define the name of the workstation on which jobs 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 job 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 Orchestration CLI

task job_definition

Using this keyword, you can define a job definition. Each job 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 job.

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

succoutputcond Condition_Name "Condition_Value"

Using this condition, a successor job starts only after the predecessor job or job stream has successfully completed. When this condition is satisfied, the job status is set to SUCC. You can also use this condition to define alternative flows in job streams by specifying the conditions the predecessor job or job stream needs to satisfy before the successor job 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 job 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 job:

(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 job as a job 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 job state

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

An output variable

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

• Analyzing the job properties:

  
  $this().File.1.Size>0

  The expression in the example qualifies a file transfer job as successful when the size of the file that has been transferred is greater than zero.
• Analyzing the job properties or the job output of another job in the same job stream:

  
  $this().NumberOfTransferredFiles=
  job.DOWNLOAD.NumberOfTransferredFiles

  The expression in the example qualifies a file transfer job as successful when the number of files that have been uploaded in the job equals the number of the files that have been uploaded in another job (named DOWNLOAD), in the same job stream.
• 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
  For further information, see:

outputcond Condition_Name "Condition_Value"

When satisfied, this output condition defines which job 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 job 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 job has completed with a return code equal to 1, then the job 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 job satisfies that condition, then the successor job runs.

See also

For more information on how to start an Orchestration CLI session refer to Running commands from Orchestration CLI.