Introduction

The If Instruction is used for conditional processing in a workflow. It allows return codes and return values of previous jobs to be checked and can be used to evaluate order variables.
The If Instruction optionally allows use of an Else branch if the condition evaluates to false.
An If Instruction evaluates an expression that includes order variables and that results in a true/false value. Some basic use cases include:
- checking the return code (exit code) of a previous job and deciding which jobs or instructions to be continued with,
- checking the return value (variables returned by a previous job) to decide about further processing,
- checking order variables to determine the next instructions to process.
The If Instruction does not modify an order's state. However, if an If Instruction fails due to an error in the expression or syntax, then the order is considered to have failed.

Feature Video

This video explains how to create conditional processing in a workflow.

Syntax

The If Instruction evaluates an expression from a predicate and returns a Boolean value true or false.
Therefore Boolean algebra is applied, for example, to evaluate expressions such as $returnCode.toNumber == 0.
For details see JS7 - Expressions for Variables

Binary Operations

The If Instruction knows of two binary operations, which are and (conjunction) and or (disjunction) with the syntax && and ||.
- Possible operations correspond to the following matrix:
  x y x && y x || y
  false false false false
  true false false true
  false true false true
  true true true true
- Round brackets should be used to group multiple expressions and to control the order of evaluation.
- Conjunction beats disjunction if grouping is not used, i.e.
  - x && y || z is the same as (x && y) || z
  - x || y && z is the same as x || (y && z)
- Both operations using the basic elements true and false cover a number of algebraic laws such as associativity, commutativity and distributivity. For more details see Wikipedia.

Unary Operation

The If Instruction knows a single unary operation not (negation) for which the syntax is !.
- The unary operation results in the following matrix:
  x !x
  false true
  true false
- A negation can be used for a single expression or for a group of expressions that are enclosed by round brackets.
- The unary operation particularly satisfies De Morgan's law:
  - !x && !y = !(x || y)
  - !x || !y = !(x && y)

Variables

The predicate supports checking of the values of job arguments and of order variables.
Variables support the following data types: string, number, Boolean.
Any jobs can add or modify order variables while an order is passing a workflow.
A number of syntactical notations for variables are supported that provide access to:
- the current value of a variable (may have been modified by a previous job),
- the value that was returned by a specific JS7 - Job Instruction,
- the original value of the variable as carried by the order.
If a predicate makes use of a variable that does not exist then the order stops with a FAILED state, except when a default value has been specified for the variable.

Current Value of a Variable

The following syntax can be used to access the current value of a variable:
- $varName
- ${varName}
- variable("varName") or variable('varName')
- variable(key = "varName") or variable(key = 'varName')
To avoid an order failing due to a non-existent variable, a default value can be specified with the following syntax:
- variable("varName", default = "aString") or variable('varName', default = 'aString')
- variable(key = "varName", default = "aString") or variable(key = 'varName', default = 'aString')
- Default values use one of the supported data types: string, number, Boolean.
- If the variable name is used with the key attribute then the order of appearance of the key and default attributes is arbitrary, i.e. variable(default = "aString", key = "varName")is possible too.
- If the variable name is used without the key attribute then the variable name has to be used as the first argument of variable(...).

Original Value of an Order Variable Value

The following syntax can be used to access the original value of an order variable:
- argument("varName") or argument('varName')
- argument(key = "varName") or argument(key = 'varName')
An argument can specify a default value as well (see the previous section).

Value of a variable from a specific Job Instruction

Each label for a JS7 - Job Instruction has to be unique in a workflow.
The following syntax can be used to access the value of a variable as returned by a specific Job Instruction:
- variable("varName", label = aLabel) or variable('varName', label = aLabel)
- variable(key = "varName", label = aLabel) or variable(key = 'varName', label = aLabel)
- Note that the value of the label is not quoted!
A default value can be added as well (see previous chapter)
- The order of appearance for label and default is arbitrary.

Return Code

The return code is a variable holding an object that can be converted to a number if provided from a shell job. For such jobs the operating system exit code is handed over as the return code.
The return code is provided from the most recently executed job.
The return code is a built-in variable that can be used in a predicate like this: $returnCode
Hint; the returnCodeMeaning attribute can be set using the JS7 - Job Instruction. This states the return codes (exit codes) that are considered signaling success or error of a job run. If the return code is not included with the list of successful return codes or is included in the list of return codes signaling an error then the order fails. If you want to handle such job execution results with an If Instruction then the rerelevant return code has to be added to the list of successful return codes or has to be exempted from the list of return codes signaling errors.

Functions

timedOut

The timedOut function returns a Boolean value true that indicates if the previous job was terminated due to a timeout constraint. If the job did terminate for other reasons then the function returns the false value.
- Example for checking job termination due to timeout constraints in an If Instruction:
- $returnCode != 0 && timedOut
Use of the timedout function for a failed job requires use of the If Instruction inside the catch block of a Try/Catch Instruction.

FEATURE AVAILABILITY STARTING FROM RELEASE 2.7.2

JS-2164 - Getting issue details... STATUS

Data Types

String

Strings can be represented by the value of a variable or by an expression like "this is a string" or 'this is a string'.
Note that a string that is not the value of a variable requires to be quoted: either single quotes or double quotes can be used.
If a single quoted string contains a single quote than this has to be escaped with a backslash, e.g. 'De Morgan\'s law'.
If a double quoted string contains a double quote than this has to be escaped with a backslash too.
An empty string has to be specified with double quotes like this: "".

Number

Numbers include any integer or floating point numbers. The decimal character for floating point numbers is a dot. Numbers are not quoted.
Numeric values are provided e.g. from the return code variable ($returnCode) of the previous job, from a converted variable value or from an expression containing digits, one optional dot and one optional leading minus sign.
A variable value that holds a string can be converted to a number by use of the toNumber method with the following syntax:
- ${varName}.toNumber
- variable(...).toNumber
If the variable value is not numeric then the order fails with the If Instruction.

Boolean

Boolean values are represented by the keyword true, the keyword false or by a converted variable value
The keyword syntax with the predicate of an If Instruction is: true, false.
A variable value of data type "string" can be converted to a Boolean data type with the toBoolean method using the following syntax:
- ${varName}.toBoolean
- variable(...).toBoolean
If the variable value is not a Boolean data type then the order fails with the If Instruction.

Comparisons

String Comparison

Three operators are provided to compare strings. These are ==, != and matches.
- "stringA" == "stringB" is true if stringA and stringB are equal.
- "stringA" != "stringB" is true if stringA and stringB are not equal.
- "stringA" matches "a regular expression" is true if stringA matches the regular expression.
  - The syntax of the regular expression is a quoted string and has to be Java® compliant.
  - It is necessary for an expression including matches to be enclosed in round brackets if it is not the only expression in a predicate:
    - (variable("myVar") matches ".*") && variable("myVar") != ""

Number Comparison

Seven operators are provided to compare numbers. These are ==, !=, <, <=, >, >= and in.
- numberA == numberB is true if numberA and numberB are equal.
- numberA != numberB is true if numberA and numberB are not equal.
- numberA < numberB is true if numberA is less than numberB.
- numberA <= numberB is true if numberA is less than numberB or equal.
- numberA > numberB is true if numberA is greater than numberB.
- numberA >= numberB is true if numberA is greater numberB or equal.
- numberA in [numberB,numberC,numberD] is true if numberA is equal to numberB or equal to numberC or equal to numberD.
  - The in operator expects an array of numbers with a minimum of one number included. Array elements are separated by comma and are enclosed by square brackets.
  - It is necessary for an expression incliding in to be enclosed in round brackets if it is not the only expression in a predicate:
    - (variable("myVar").toNumber in [0,42,255]) && variable("myVar") != ""

Examples

Examples for predicates

variable('aString') matches "(?i)x.*" //true if the value of variable('aString') starts with "x" or "X" (case insensitive)
variable('aString') matches ".*x.*"   //true if the value of variable('aString') contains "x"
variable('aString') == "x"            //true if the value of variable('aString') equals "x"
variable('aNumber').toNumber == 42    //true if the value of variable('aNumber') equals "42"
variable('aBoolean').toBoolean        //true if the value of variable('aBoolean') equals "true"

Workflow Instruction: If

Use Case: Return Code Checking

Download Workflow Example (.json upload): pdiConditionalReturnCode.workflow.json

Explanations:

Return Codes come in two flavors:
- for shell jobs the return code corresponds to the operating system exit code.
- for any other job types the return code is provided by the relevant job indicating success or failure.
The job definition specifies which return codes indicate success or failure:
- For the above workflow example job1 considers the return codes 0,1,2,3,4 to signal success and any other return codes to indicate errors.
Therefore a return code > 0 does not necessarily indicate failure but can be used, e.g. for workflow control, to indicate which jobs should be executed next.
If a given return code is not present in the list of successful return codes then the order will be considered to have failed. However, if the return code is available in the list of successful return codes then an If Instruction can check the return code value and can continue with specific jobs if the If Instruction evaluates to true or to false.

Use Case: Return Value Checking

Download Workflow Example (.json upload): pdiConditionalResult.workflow.json

Explanations:

Return values are different from return codes as they do not indicate success or failure of a job. Instead they return variables and values indicating the processing result of a job, e.g. the number of records from a database table that have been processed by a job.
Such return values can be used to implement conditional processing. An If Instruction can evaluate the rerelevant return value and determine what jobs to execute next.

Use Case: Variable Checking

Download Workflow Example (.json upload): pdiConditionalVariables.workflow.json

Explanations:

Technically this use case is not too different from the checking return values use case described above. However, the focus is not on a specific job but on specific values of variables.
Note that order variables can be modified by users when adding an order. The above example therefore checks an order variable to decide which job a workflow is to be started for.
Note also that the same check can be performed for any step in a workflow.

Resources

How To ... Instructions

Space shortcuts

Page tree

Introduction

Feature Video

Syntax

Binary Operations

Unary Operation

Variables

Current Value of a Variable

Original Value of an Order Variable Value

Value of a variable from a specific Job Instruction

Return Code

Functions

timedOut

Data Types

String

Number

Boolean

Comparisons

String Comparison

Number Comparison

Examples

Workflow Instruction: If

Use Case: Return Code Checking

Use Case: Return Value Checking

Use Case: Variable Checking

Resources

How To ... Instructions

x	y	x && y	x \|\| y
false	false	false	false
true	false	false	true
false	true	false	true
true	true	true	true

Space shortcuts

Page tree

JS7 - If Instruction

Introduction

Feature Video

Syntax

Binary Operations

Unary Operation

Variables

Current Value of a Variable

Original Value of an Order Variable Value

Value of a variable from a specific Job Instruction

Return Code

Functions

timedOut

Data Types

String

Number

Boolean

Comparisons

String Comparison

Number Comparison

Examples

Workflow Instruction: If

Use Case: Return Code Checking

Use Case: Return Value Checking

Use Case: Variable Checking

Resources

How To ... Instructions