Purpose

• The If Instruction is used for conditional processing in a workflow. It allows to check return codes and return values of previous jobs and it can be used to evaluate any order variables.
• The If Instructions optionally allows to use 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 basic use cases are suggested:
  • check the return code (exit code) of a previous job to decide which jobs or instructions to continue with,
  • check the return value (variables returned by a previous job) to decide about further processing,
  • check any 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 broken.

Syntax

• The If Instruction evaluates an expression from a predicate and returns a Boolean value true or false.
• Therefore Boolean algebra is applied, e.g. to evaluate expressions such as $returnCode.toNumber == 0.

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 table:

    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 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, 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. This is "not" (negation) for which the syntax is !.

  • The unary operation results in the following table:

    x	!x
    false	true
    true	false

  • A negation can be used for a single expression or for a group of expressions which are enclosed by round brackets.
  • The unary operation satisfies particularly De Morgan's law: 
    • !x && !y    =    !(x || y) 
    • !x || !y    =    !(x && y)

Variables

• The predicate supports to check the value of job arguments and of order variables.
•  Variables support the following data types: string, number, boolean.
• While an order passes a workflow any job can add or modify order variables.
• A number of syntactical notations for variables are supported that provide access to
  • the current value of a variable (maybe 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 exists then the order stops with a FAILED state except that 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 that an order stops because of 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 key attribute and default attribute 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 too (see previous chapter).

Value of a variable from a specific Job Instruction

• Each Job-Instruction has a label that has to be unique per workflow.
• The following syntax can be used for 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 too (see previous chapter)
  • The order of appearance for label and default is arbitrary.

Data Types

String

• Strings can be either the value of a variable or an expression like "this is a string" or 'this is a string'.
• Note that a string which is not the value of a variable needs quotation; either single quotes or double quotes.
• 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.

Boolean

• Boolean values come in two flavors: true and false.

Workflow Instruction: If

Use Case: Return Code Checking

• Download Workflow Example: pdiConditionalReturnCode.json

Explanations:

• Return Codes come in two flavors:
  • for shell jobs the return code corresponds to the OS exit code.
  • for any other job types the return code is provided by the respective job indicating success or failure.
•  The job definition specifies which return codes indicate success or failure:
  • 
  • For the above workflow example the job1 considers return codes 0,1,2,3,4 signaling success and any other return codes indicating 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 the list of successful return codes then the order will be considered being failed. However, if the return code is available with 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: pdiConditionalResult.json

Explanations:

• Return values are different from return codes as they do not indicate success or failure of a job but instead 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 return value and determine what jobs to execute next.

Use Case: Variables Checking

• Download Workflow Example: pdiConditionalVariables.json

Explanations:

• Technically this use case is not too different from the above checking of return values. However, the focus is not on a specific job but on specific values of variables.
• Consider 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 for.
• In addition the same type of checks can be performed with any step in a workflow.