Using variables in template steps

You can add customization capabilities to template steps through the use of step-specific variables and other techniques for designing steps, as described in this topic.

As the workflow author, you might want to:

Specify certain variables as being able to be used in a JOB statement.
Use the same JCL repeatedly over a number of steps, but with a different set of values substituted for each job submission.

This topic describes techniques that you can use to add flexibility to template steps, in the following topics:

Variable substitution in the JOB statement
Predefined variables in a step

Variable substitution in the JOB statement

As the workflow author, you might want to indicate that certain variables in the workflow can be used in a JOB statement. To make a variable available for user selection, include the exposeToUser (<exposeToUser>) element on the variable element tag. This element indicates that the variable is to be included among the user-selectable variables in the List variables for substitution window of the Workflows task.

With the exposeToUser element, you can identify a certain set of variables that may be used (through substitution) in the JOB statement when the step owner is performing the step. To use a variable, the step owner would have to modify the JOB statement to add the variable reference. The step owner can then view the substitution to see if the JOB statement is as desired. The step owner can optionally designate the edited JOB statement be used for all steps in the workflow instance, but must understand the impact of doing so.

Suppose, for example, that you want to allow the user to select a notification user ID for the job. The system will send a message to this user ID when the job completes.

You can use the following technique to present the user with a selectable user ID FRED that is intended to be used with the NOTIFY= keyword parameter in the JOB statement. On the variable definition, include the exposeToUser element:

<variable name="notify-user">
<label>Notify user ID</label>
<abstract>This user ID can be selected for job notifications</abstract>
<description>Simple string variable.</description>
<exposeToUser>
<usage>Use this variable with the NOTIFY= parameter of the JOB statement
so that its value will designate who is notified when the job completes.</usage>
</exposeToUser>
<category>exposeToUser variables</category>
<string>
<default>FRED</default>
</string>
</variable>

In the workflow step, when the user displays the Create JOB statement page, the default JOB statement for the workflow is shown. For example, the following JOB statement is supplied with z/OSMF:

//IZUWFJB JOB (ACCTINFO),CLASS=A,MSGCLASS=0,
               MSGLEVEL=(1,1),REGION=0M,NOTIFY=IBMUSER

On the Create JOB statement page is the option List variables for substitution. If the user clicks this option, the Workflows task displays the variables in the workflow that include the exposeToUser element. The user can make JOB statement substitutions by manually copying these variables into the JOB statement.

In this example, the notify-user variable would be displayed in the List variables for substitution window. To use the notify-user variable for the notification user ID, the user can copy it into the JOB statement, as follows:

//IZUWFJB JOB (ACCTINFO),CLASS=A,MSGCLASS=0,
               MSGLEVEL=(1,1),REGION=0M,NOTIFY=${instance-notify-user}

On selecting the View JOB Statement Substitutions option, the user can display the substituted values to verify that the JOB statement is correct. In this example, the notification user ID is resolved to the value FRED:

//IZUWFJB JOB (ACCTINFO),CLASS=A,MSGCLASS=0,
               MSGLEVEL=(1,1),REGION=0M,NOTIFY=FRED

Predefined variables in a step

Suppose that your workflow contains a number of steps that run the same job repeatedly, with the exception of some values in the body of the job that must change each time the job is submitted. As an alternative to maintaining a slightly different copy of the JCL for each step, you can use the same job and call it from multiple steps. This technique requires that each step supply its own substitution values or predefined variables for each job submission. Doing so allows you as the workflow author to adjust the contents of the job dynamically to suit each step, based on the predefined variables.

To specify a predefined variable for a step, include the predefined variable (<predefinedVariable>) element on the step element tag, with the following element attribute:

name=: Name of the variable (a string).

A predefined variable is treated as a string substitution for the current step only. You can specify multiple predefined variables per step. To avoid overriding the variables defined for the workflow, use a unique name for the predefined variable.