Page History
Table of Contents |
---|
...
Introduction
- The If Instruction is used for conditional processing in a workflow. It allows to check return codes and return values of previous jobs jobs to be checked and it can be used to evaluate order variables.
- The If Instruction optionally allows to 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. The following Some basic use cases are suggestedinclude:- check checking the return code (exit code) of a previous job to decide and deciding which jobs or instructions to continue be continued with,
- check checking the return value (variables returned by a previous job) to decide about further processing,
- check order checking order variables to determine the next instructions to process.
- The If Instruction does not modify an order's state. However, however, if an If Instruction fails due to an error in the expression or syntax, then the order is considered being failed.to have failed.
Feature Video
This video explains how to create conditional processing in a workflow.
Widget Connector | ||
---|---|---|
|
Syntax
- The If Instruction evaluates an expression from a predicate and returns a boolean value Boolean value
true
orfalse
. - Therefore Boolean algebra is applied, e.g. , 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 no grouping is not used, i.e.
-
x && y || z
is the same as(x && y) || z
-
x || y && z
is the same asx || (y && z)
-
- Both operations using the basic elements
true
, andfalse
cover a number of algebraic laws such as associativity, commutativity and distributivity, for . For more details see Wikipedia.
...
Variables
- The predicate supports to check checking of the values of job arguments and of order variables.
- Variables support the following data types: string, number, booleanBoolean.
- While an order passes a workflow any job 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 (maybe 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 in case that when a default value has been specified for the variable.
...
- The following syntax can be used to access the current value of a variable:
$varName
${varName}
variable("varName")
orvariable('varName')
variable(key = "varName")
orvariable(key = 'varName')
- To avoid that an order fails failing due to a non-existent variable, a default value can be specified with the following syntax:
variable("varName", default = "aString")
orvariable('varName', default = 'aString')
variable(key = "varName", default = "aString")
orvariable(key = 'varName', default = 'aString')
- Default values use one of the supported data types: string, number, booleanBoolean.
- If the variable name is used with the
key
attribute then the order of appearance of thekey
attribute anddefault
attribute 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 ofvariable(...)
.
...
- The following syntax can be used to access the original value of an order variable:
argument("varName")
orargument
('varName')
argument(key = "varName")
orargument
(key = 'varName')
- An
argument
can specify a default value too as well (see the previous chaptersection).
Value of a variable from a specific Job Instruction
- Each label for a JS7 - Job Instruction has to be unique per 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)
orvariable('varName', label = aLabel)
variable(key = "varName", label = aLabel)
orvariable(key = 'varName', label = aLabel)
- Note that the value of the
label
is not quoted!
- A default value can be added too as well (see previous chapter)
- The order of appearance for
label
anddefault
is arbitrary.
- The order of appearance for
...
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 buildbuilt-in variable that can be used in a predicate like this:
$returnCode
Hint; with the JS7 - Job Instruction the
returnCodeMeaning
attribute can be set that 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 with 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 respective 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.
...
- 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 values are represented by the keyword
true
, the keywordfalse
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 Boolean data type with the the
toBoolean
method using the following syntax:${varName}.toBoolean
variable(...).toBoolean
- If the variable value is not a boolean Boolean data type then the order fails with the If Instruction.
...
- Three operators are provided to compare strings. These are
==
,!=
andmatches
."stringA" == "stringB"
is true ifstringA
andstringB
are equal."stringA" != "stringB"
is true ifstringA
andstringB
are not equal."stringA" matches "a regular expression"
is true ifstringA
matches the regular expression.- The syntax of the regular expression is a quoted string and has to be Java Java® compliant.
- It is required that necessary for an expression including
matches
is to be enclosed with in round brackets if it is not the only expression in a predicate:(variable("myVar") matches ".*") && variable("myVar") != ""
...
- Seven operators are provided to compare numbers. These are
==
,!=
,<
,<=
,>
,>=
andin
.numberA == numberB
is true ifnumberA
andnumberB
are equal.numberA != numberB
is true ifnumberA
andnumberB
are not equal.numberA < numberB
is true ifnumberA
is less thannumberB
.numberA <= numberB
is true ifnumberA
is less thannumberB
or equal.numberA > numberB
is true ifnumberA
is greater thannumberB
.numberA >= numberB
is true ifnumberA
is greaternumberB
or equal.numberA in [numberB,numberC,numberD]
is true ifnumberA
is equal tonumberB
or equal tonumberC
or equal tonumberD
.- 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 required that necessary for an expression with incliding
in
is to be enclosed with in round brackets if it is not the only expression in a predicate:(variable("myVar").toNumber in [0,42,255]) && variable("myVar") != ""
- The
...
Code Block | ||||
---|---|---|---|---|
| ||||
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" |
...
- 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 respective 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 signaling to signal success and any other return codes indicating 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 with in the list of successful return codes then the order will be considered being to have failed. However, if the return code is available with 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 tofalse
.
...
- 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 but instead . 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 respective 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 above checking of return values use case described above. However, the focus is not on a specific job but on specific values of variables.
- Consider 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 to start a workflow is to be started for.
- In addition, Note also that the same check can be performed for any step in a workflow.
Further Resources
Display content by label | ||||
---|---|---|---|---|
|