z/OSMF Workflow variables are used to store information to be referenced and manipulated within the workflow. A variable is a value that can change, depending on conditions or on information passed to the workflows. Setting variable values dynamically during workflow execution makes your workflow more flexible.
For example, if you want to determine what to do based on the result of the previous workflow step, you can design different steps and determine which step to be executed next by judging the value of the variable in the previous step.
In this article, we will discuss a few ways of setting variable values dynamically during workflow execution to add significant flexibility to your workflow.
1. Set the variable values through a data set or Unix file.
You can design a workflow step to submit a JCL to create key-value pairs and save them to a properties file. When the properties file is saved successfully, the Workflows task reads in the contents of the file and set variable values for use by other steps in the same workflow.
To specify the default name and location of the properties file that is used by the step, include the element <output> on the step element. The properties file can be a data set, a UNIX file, or a JES spool file.
Following is an example about how to set the variable values through a JCL, then save them to a UNIX properties file. The properties file contains variables and values that are used by subsequent steps.
<template>
<inlineTemplate substitution="true"># shell script to generate some variables from workflows task to the output property file
echo server_name server1 >> $_output
echo server_url https://server1.ibm.com/zosmf >> $_output
</inlineTemplate>
<submitAs maxRc="0">shell-JCL</submitAs>
<output needResolveConflicts="true" substitution="true">/u/myuser/outputFile</output>
</template>
After the above step is performed, the value of variable “server_name” is set to “server1”, and the value of variable “server_url” is set to “https://server1.ibm.com/zosmf”. They can be used in subsequent steps. You can determine the next steps based on the different variable values obtained in this step.
Here is an example:
<step name="step2" optional="false">
<title>The step for server1</title>
<description>This step will be performed on server1 only. </description>
<prereqStep name="step1"/>
<prereqTargetStateSet>
<description>The state of this step will become Ready if the server name is server1, other wise it will become Skipped.</description>
<extendStateExpression>
<description>The state of this step will become Skipped when server name is not server1</description>
<expression>${instance-server_name} !== "server1"</expression>
<targetState>skipped</targetState>
</extendStateExpression>
</prereqTargetStateSet>
<instructions substitution="true">Submit a job to server1.</instructions>
<weight>5</weight>
<skills>System Programmer</skills>
<autoEnable>true</autoEnable>
<canMarkAsFailed>false</canMarkAsFailed>
<rest>
<httpMethod>PUT</httpMethod>
<uriPath substitution="false">/zosmf/restjobs/jobs</uriPath>
<requestBody substitution="false">
//IZUWFJO2 JOB
//STEP1 EXEC PGM=IEFBR14
//SYSEXEC DD DUMMY
//* PRINT DD SYSOUT=A
/*
</requestBody>
<expectedStatusCode>201</expectedStatusCode>
<requestHeaders substitution="false">{
"X-CSRF-ZOSMF-HEADER":"zosmf",
"content-type":"text/plain; charset=UTF-8"
}
</requestHeaders>
</rest>
</step>
<step name="step3" optional="false">
<title>The step for server2</title>
<description>This step will be performed on server2 only.</description>
<prereqStep name="step1"/>
<prereqTargetStateSet>
<description>The state of this step will become Ready if the server name is server2, other wise it will become Skipped.</description>
<extendStateExpression>
<description>The state of this step will become skipped if server name is not server 2.</description>
<expression>${instance-server_name} !== "server2"</expression>
<targetState>skipped</targetState>
</extendStateExpression>
</prereqTargetStateSet>
<instructions substitution="true">Send a GET request to server2.</instructions>
<weight>5</weight>
<skills>System Programmer</skills>
<autoEnable>true</autoEnable>
<canMarkAsFailed>false</canMarkAsFailed>
<rest>
<httpMethod>GET</httpMethod>
<uriPath substitution="false">/zosmf/restjobs/jobs?prefix=IZUWF*</uriPath>
<expectedStatusCode>200</expectedStatusCode>
</rest>
</step>
In the above sample, there are two steps, but at most one will be executed, and the other one or both will be skipped according to the value of the variable “server_name” in the first step: if its value is server1, step 2 will be performed and mark the step 3 as Skipped; if the value is server2, step 2 will be marked as Skipped, and step 3 will be performed; if the value is neither server1 nor server2, both steps will be marked as Skipped.
2. Set the variable values through a JES spool file.
As mentioned in #1, you can also save the variable values into a spool file instead of a data set or USS file, if you wish to do so, set the “sysoutDD” to true as part of a step’s <output> element, by using the following syntax:
[step.]ddname
Where:
l step is the name of the job step that creates the spool file. This value is optional.
l ddname is the DD name of the step. This value is required.
Use the same example as above, we will add the element sysoutDD, and change the USS file location to a spool file location:
<template>
<inlineTemplate substitution="true"># shell script to generate some variables from workflows task to the output property file
echo server_name server1
echo server_url https://server1.ibm.com/zosmf
</inlineTemplate>
<submitAs maxRc="0">shell-JCL</submitAs>
<output sysoutDD="true" substitution="true">XBATCH.STDOUT</output>
</template>
In this example, you set the sysoutDD to true, it indicates the properties file is a JES spool file that is produced by the job step in the executed job. The location that is specified is XBATCH.STDOUT, which must be a valid DD name. After the step is performed, the variable values will be stored in the STDOUT spool file of step XBATCH.
3. Set the variable values through an executable program.
You can choose to set variable values when running an executable program (a REXX exec or UNIX shell script) in real time.
You can specify a meaningful prefix that identifies a string as an output variable in the executable program. To do so, add the element <outputVariablesPrefix> to the <submitAs> element.
In the following example, the string "outvar:" is applied to the names of any variables that are set by the step:
<outputVariablesPrefix needResolveConflicts="true">outvar:</outputVariablesPrefix>
Example:
<template>
<inlineTemplate substitution="false">#!/bin/sh
echo "this is a sample to submit shell script to run immediately."
echo outvar:st_user = CAROL
echo "This symbol is used to indicate success"</inlineTemplate>
<submitAs maxRc="0">TSO-UNIX-shell</submitAs>
<successPattern>success.*</successPattern>
<outputVariablesPrefix needResolveConflicts="false" loadOutputFileArrayValue="false">outvar:</outputVariablesPrefix>
</template>
After the above step is performed, the value of the variable st_user is set to CAROL.
4. Set the variable values through setVariable.
There is a simpler way to set variables: setVariable function. It can also dynamically set value to the workflow variable at the completion of one step (could be instruction step). It works like this:
<setVariable name="dsname" scope="instance" substitution="true">ZOSMF.WORKFLOW.DS1</setVariable>
This usage is very straightforward and simple. After the step is completed, the value of the variable daname is set to ZOSMF.WORKFLOW.DS1. By leverage variable substitution, you can set the value as what you want other than hard-coding. But please note setVariable only supports setting string type variables.