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.

Using variable substitution in the workflow variable input file

It is possible to use variable substitution in the workflow variable input file. With this ability, you can define a value once in the file and refer to that value on subsequent lines to use the same value.

To use variable substitution in the workflow variable input file, you must include the following specification in the file:

IZU_VARIABLE_SUBSTITUTION_ON

Position this specification before any lines that refer to the variable.

Similarly, you can turn off variable substitution for subsequent lines in the file by including the following specification in the workflow variable input file:

IZU_VARIABLE_SUBSTITUTION_OFF

Thereafter, subsequent variables are interpreted as literal values.

If you omit IZU_VARIABLE_SUBSTITUTION_ON from workflow variable input file, the default is that no variable substitution is performed for the file.

Figure 1 shows an example of how you can turn on and turn off variable substitution in the same workflow variable input file.

Figure 3. Using variable substitution in a workflow variable input file

base = HelloWorld
IZU_VARIABLE_SUBSTITUTION_ON
var = ${base}
IZU_VARIABLE_SUBSTITUTION_OFF
var2 = ${base}

In Figure 1, notice that variable substitution is:

On when the variable var is processed. As a result, the variable is replaced by the string HelloWorld.
Off when the variable var2 is processed. As a result, the variable is replaced by the string {$base}.

Figure 2 shows how the previous example would be processed in the Workflows task Step Perform wizard. In this example, a variable input file that is named VariableInput.properties is provided for the workflow. Notice that substitution is performed for the first variable var, but not for the second variable var2.

Image showing how variable substitution in the workflow variable input file works with the Workflows task Step Perform wizard. — Figure 4. How variable substitution in the workflow variable input file works with the Workflows task Step Perform wizard.

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.

For an array variable, you can use the load-output-file-array-value attribute (loadOutputFileArrayValue) to manage potential variable conflicts. If set to true (the default), the workflow uses the array variable values from the output file, rather than from the Workflows task. Otherwise, if this attribute is set to false, the workflow uses the existing values from the Workflows task.