Providing a workflow variable input file

This topic describes the format of the editable properties file that is called the workflow variable input file. With this file, you can supply preset values for the variables that you use in your workflow definition file. By including a variable input file with your workflow definition file, you save users from having to manually enter values for some or all of the variables in your workflow.

How a workflow variable input file is used

A workflow variable input file is an optional properties file that you, the workflow author, can use to pre-specify one or more of the input variables that are defined in the workflow definition. By supplying variable values in this way, you make it possible for the user to create a workflow without having to interactively enter the inputs in the Workflows task Step Perform wizard. The Workflows task treats any variables set through the workflow variable input file the same as if the user entered them manually.

If you provide a workflow variable input file, include it with the other materials that you supply to the workflow user, such as the workflow definition file and the other files that comprise your workflow definition. Ensure that the documentation for your workflow definition makes note of the file name, and provides any related instructions for editing or storing the file on the user’s z/OS system. The Workflows task accesses the workflow variable input file under the user’s identity, thus, the file must be read-accessible by the user who is creating the workflow.

At workflow creation time, the user imports the workflow variable input file into the Workflows task, along with the workflow definition file. The Workflows task reads in the contents of the file and saves its values for use with the created workflow. The Workflows task uses the variable input file in addition to any global variables that are already defined to Workflows task. Any new variables that are defined with a global scope become available to the other workflow instances on the user’s system. After the Workflows task imports the file, the task no longer refers to the file.

Creating a workflow variable input file

As the workflow author, you can create a workflow variable input file as a text file, by using an editor of your choice. The file must be encoded in either of the following formats: ASCII or IBM-1047 (EBCDIC). Use a file type of .txt or .properties. Do not use Unicode encoding, such as UTF-8, for this file.

In the variable input file, specify the properties (variables and their respective values) as one or more key-value pairs. Valid separator characters are equal signs (=), colons (:), or spaces. Figure 1 shows the valid formats for specifying properties in the variable input file.

Figure 1. Format of a workflow variable input file

key1 = value1
key2 : value2
key3   value3

Figure 2 shows an example of the contents of a workflow variable input file.

Figure 2. Example of a workflow variable input file

Boolean1 = false
String3  = SYS1.LINKLIB
Integer2   35
Decimal2 : 3.3
Time2      03:03:00
Date1 = 2013-11-11

The example in Figure 2 is designed to work with the file workflow_sample_variables.xml, which is supplied as a sample with z/OSMF. For a description of this file and other coding examples, see Sample XML files for your reference.

The Workflows task does no syntax checking of the properties that are specified in the workflow variable input file. Therefore, you must ensure that valid values are specified for each of the properties.

Also, observe the following considerations:

Each property that is specified in the variable input file must correspond to a variable named in the workflow definition file. Otherwise, the Workflows task ignores the property.
If the variable input file specifies a property that matches a variable that is already defined to the Workflows task as a global variable, the Workflows task detects the conflicting definitions and prompts the user for a selection. See Avoid conflicting variable definitions

You can provide the workflow variable input file in either a z/OS UNIX file or a z/OS data set. For a z/OS data set, use a sequential data set, a member of a partitioned data set (PDS), or partitioned data set extended (PDSE).

If you create the workflow variable input file on a workstation, it is recommended that you use File Transfer Protocol (FTP) in binary mode to transfer the XML files to a z/OS system. Doing so helps to ensure that the files are encoded properly for use on z/OS.

Saving properties to an output file

As an alternative to defining properties in a workflow definition file or a variable input file, you can design steps to define properties dynamically within a workflow. That is, you can add a step to run a job to create properties and settings, and save the properties in an output file. Doing so makes the properties available for use by other steps in the same workflow instance (as instance variables) or other workflows (as global variables).

To specify a default data set name or UNIX path name for the output file, include the optional subelement <output> on the <step> element.

When an output file is saved, the Workflows task scans the file to determine whether the file contains any workflow input variables (properties that are written as name-value pairs). If so, the Workflows task attempts to add the variables to the variables pool. The input variables then become available for use by subsequent steps in the workflow instance. In practice, a step might submit a batch job to create some input variables, which are then used by a subsequent step, thus saving the Workflows task user from having to enter the input variables manually.

Create step-specific values with the _output variable

When you include the <output> element in the step definition, a special use variable that is called _output is defined implicitly. The _output variable takes on the value that is specified on the <output> element.

For a step that saves its properties to an output file, you can use the <output> element to name the output file that is created by the step. The output element specifies a default data set name or UNIX path name for the output file, as described in Saving properties to an output file. The user can override the value of the <output> element and choose a different output file, if wanted.

For example:

<output>some.file.${instance-var1}</output>

In this example, if the instance variable var1 has the value "name," the variable _output has the value "some.file.name" after substitution. You can use ${_output} within the step, perhaps within the body of a script. Note that the variable has a step-specific value. If the element <output> is not specified for the step, the variable _output is not available for that step.

You can find an example of this technique in the workflow_sample_output.xml file that is provided with z/OSMF. The following figure shows a portion of the sample XML file:

<!-- Declare a set of variables for use -->
<variable name="outputFileNameVariable">
    <label>File name for output file</label>
    <abstract>Enter a name for the output properties file</abstract>
    <description>This value is required. It is included in the JCL for output file path.
    </description>
    <category>Output File</category>
    <string>
        <default>testOutput</default>
    </string>
</variable>
⋮
<variable name="st_user">
⋮
<variable name="setting0" scope="global">
⋮
<step name="submitEmptyJCL">

⋮
<!-- This step demonstrates how to load variables from a JCL/REXX/Shell script execution".
<step name="output">
    <title>A step with an output property file</title>
    <description>In this step, you run a job to create an output property file
    </description>
    <variableValue name="st_user" required="true"/>
    <variableValue name="setting0" required="true" scope="global"/>
    <variableValue name="outputFileNameVariable" required="true"/>
    <instructions>In this example step, some variable values are generated into a pre-specified 
                  output file and after perform, those variables will be loaded into workflows 
                  task after user resolves the variable conflicts if any.</instructions>
    <weight>5</weight>
    <skills>System Programmer</skills>
    <template>
            <inlineTemplate substitution="true">
# shell script to generate some variables from workflows task to the output property file
echo st_user USER001 >> ${_output}
echo setting0 global001 >> ${_output}
            </inlineTemplate>
            <submitAs maxRc="0">shell-JCL</submitAs>
            <output substitution="true" needResolveConflicts="false">
                         /u/tmp/${instance-outputFileNameVariable}
            </output>
            </template>
</step>

As shown in the example, you can use the _output variable in the shell script to assist with producing the properties file. The script uses the output file name as specified by the user who performed the step.

Avoid conflicting variable definitions

If the Workflows task detects that an imported variable conflicts with an existing global variable, the user is prompted to choose the appropriate value. The user can select to use the input file variable in place of existing global variables, or ignore the input file variable, and use the existing global variable instead. The user’s selection determines which version of the variable is saved in the Workflows task global variable pool for use with other workflow instances. Thus, the user’s selection affects any other workflows that refer to the same global variable.

It is recommended that you choose unique names for variables to avoid possible naming conflicts with unrelated workflows. Consider your naming conventions carefully and avoid using unspecific variable names. Similarly, consider qualifying your variables, for example, with the three-character prefix associated with your software product, or a unique identifier.

Depending on your design, you might determine that the output file variables must always be used in place of a workflow’s existing instance variables. If so, you can include the need-resolve-conflicts attribute (needResolveConflicts) on the output subelement, and set it to false. If so, the Workflows task uses the output file variables in place of any existing values without prompting the user. This setting applies to instance variables only; global variables are not overridden. The default is true; if variable conflicts exist, the user is prompted to resolve the conflicts.