Making a step conditional

A conditional step is available to be performed when a logical condition is satisfied on the z/OS system or in the Workflows task. A conditional step might become Ready (eligible to be performed), for example, if a job run by another step ends with a particular return code. A conditional step remains Not Ready (unavailable to be performed) as long as the condition is not satisfied.

Understand that a conditional step, which depends on a logical condition, is different than a dependent step, which depends on a particular step being completed, to satisfy a prerequisite.

In the Workflows task user interface, conditional steps:

Are indicated to users in the Details tab on the Step Properties page.
Are shown in the Not Ready state until the condition is true (satisfied) — even when the prerequisite steps, if any, are complete.

A conditional step becomes ready for performing only when a specific condition is satisfied in the current step or a preceding step. Thus, the expression being tested and a text description are required sub-elements of the condition element.

Target states

Optionally, you can specify a desired target state for a conditional step. The target state specifies the state the step is to assume when the condition is true. Typically, the target state is Ready, which is the default value, if you choose to omit this sub-element.

The following target states are valid:

Ready
Skipped.

Types of conditional expressions

The following types of conditional expressions are supported:

Expressions using logical operators AND (&) and OR (|). For example:

${step1.returnCode} == "0000" || (${step2.returnCode} == "0000" && ${step2.stepOwner} == “IBMUSER”)

Expressions based on ternary operators. For example:

    condition ? value_if_true : value_if_false

Mathematical functions. For example:

Math.max(${step1.returnCode} , ${step2.returnCode} ) > 0

Design considerations for conditional steps

Observe the following design considerations for conditional steps:

A conditional step must be a leaf step (a step with no substeps). A parent step cannot be a conditional step.
When coding the step element, specify whether the step is conditional by including the condition attribute on the step element (<step>). Also, specify both the expression being tested for (typically a mathematical or logical expression) and a text description of the condition. Both the expression and its description are displayed to the end user in the Details tab on the Step Properties page.
A conditional expression can refer only to preceding steps in the workflow.
You can include workflow input variables in conditional expressions. Doing so allows conditional steps to resolve to true or false, based on installation-specific conditions.
You can use the following step attributes in conditional expressions: <stepState> and <returnCode>.
<returnCode> is a string type attribute; you cannot use it in a mathematical comparison. To compare a return code with a second return code or another numerical value, such as zero (0), you can write the condition expression like this: ${step2.returnCode} ) > "0000". Represent the return code string with four characters, for example "0000" or "0008".

Example

As an example, assume that Step 3 should not be performed unless Step 1 and Step 2 complete with a return code zero. Here, the XML for Step 3 could be coded as follows:

Figure 1. You can designate a step as conditional by adding the condition element to the <step> element tag.

<Step name=Step3">
	<title>A conditional step based on return code</title>
	<description>This conditional step is not ready until 
									the two preceding steps complete with RC 0
	</description>
	<instructions>Run this job.</instructions>
	<condition>
			<expression>${step1.returnCode} == "0000" || (${step2.returnCode} == "0000"
			</expression>
		<description>This step requires that Steps 1 and 2 have 
										completed successfully.
	</description>
	</condition>
	<targetState>Ready</targetState>

The previous example can be expanded to include a condition, based on a variable value. In Figure 2, Step 3 is not performed unless Step 1 and Step 2 complete with a return code zero and the variable ${instance-st_user} is IBMUSER.

Figure 2. You can use variable values in the condition to be satisfied.

<Step name=Step3">
	<title>A conditional step based on return code and user ID</title>
	<description>This conditional step is not ready unless 
									the two preceding steps complete with RC 0
               variable st_user value is IBMUSER 
	</description>
	<instructions>Run this job.</instructions>
	<condition>
			<expression><![CDATA[${step1.returnCode} == "0000" && 
                  ${step2.returnCode} == "0000" && 
                  ${instance-st_user} == "IBMUSER" ]]>	
     </expression>
		<description>This conditional step is not ready unless the two 
                 preceding steps complete with RC 0 and the variable 
                 st_user value is IBMUSER.</description>
	</condition>
	<targetState>Ready</targetState>
    ⋮
</step>

Note that a variable reference can contain an underscore, for example: ${instance_st_user} == "IBMUSER" or a hyphen, for example: ${instance-st_user} == "IBMUSER".