How to refer to a variable

For examples of the various variable types and features, see file workflow_sample_variables.xml, which is supplied with z/OSMF in the /samples subdirectory of the product file system.

Using braces around variable references is optional, but recommended as a good programming practice. The braces help to ensure that variables are clearly identified in the workflow. More importantly, the braces prevent ambiguity when it comes time for variable substitution, such as in conditional expressions, and jobs and scripts. For example, the variables $st_userFRED and ${st_user}FRED are evaluated differently by the Workflows task. In the former case, the Workflows task searches for a variable called st_userFRED. In the latter case, it is clear that the variable is st_user.

A variable reference can contain an underscore or a hyphen. For example, both of the following references are valid: ${instance_st_user} == "IBMUSER" and ${instance-st_user} == "IBMUSER".

More examples of how variables are referenced and used are provided in Defining steps for your workflow.

Simplified instance variable format in substitution and conditions

If you need to define many instance variables in a workflow definition file, you can save some typing by using the simplified variable format. That is, you can omit the prefix instance- from the names of instance variables. To use this variable name format, you must enable it by including the optional schema element (<workflowSettingInfo>) with its only subelement (<variablesSetting>) and attribute isInstanceWithoutPrefix set to "true". You must also ensure that none of the instance variables in the workflow definition are prefixed by instance-, either in variable definitions or in conditional expressions.

Note: Though the simplified variable format is supported, it is recommended that you use the standard format, for example: "${instance-varName}" or "${global-varName}", as a good programming practice.

Use care with the simplified variable format when specifying variables in substitutions, to ensure that the variables are specified consistently. In the following example, the simplified format is used for instance variable references. In the example, Step 3 is not performed unless Step 1 and Step 2 complete with a return code zero and the instance variable ${st_user} is IBMUSER.

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

<Step name=Step3">
	<title>A conditional step based on return code</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" && 
                  ${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>
    ⋮
<template>
<inlineTemplate substitution="true">
//STEP3 EXEC PGM=IKJEFT01,DYNAMNBR=20
//SYSTSPRT DD SYSOUT=A
//SYSTSIN DD *
ADDGROUP ${st_group} OMVS(GID($st_gid))
/*
</inlineTemplate>
<submitAs>JCL</submitAs>
</template>
</step>