Sub-elements of the variable element

This topic describes the sub-elements and types that make up a variable definition.

The <variable> element can contain the following sub-elements:

label (required)
abstract (required)
description (required)
exposeToUser (optional)
category (required)
datastore (optional)

Variables require a label (<label>) and an abstract (<abstract>). These values are displayed in the Workflows task when it prompts for input. In addition, the Workflows task displays a description (<description>) for the variable if the user clicks the information icon for the abstract.

You can specify a category (<category>) for a variable to assign it to a logical group of related variables. For a given step, all variables with the same category are displayed on the same web page. When viewed through the Workflows task, the workflows Step Perform wizard proceeds through each of the categories that you define for the step. In this way, you can logically organize many variables to provide context and an easier user experience for users who enter variable values.

Variable definition type-specific elements

A variable definition includes a type-specific element that contains elements and attributes specific to that type. The supported types and corresponding element names are described as follows:

boolean

The Workflows task displays a simple check box to prompt the user for this variable. Specify a default value of true or false to indicate whether the check box is initially displayed to the user as checked. If you do not provide a value, true is used by default.

string

The Workflows task displays the variable in a text box, initially primed with an optional default value, if you specify one. Use the "multiLine=" attribute (Boolean) of the string element (<string>) to specify whether the text box is small or large.

You can specify a number of choices for the variable. If so, the Workflows task displays the text box with a menu from which the user can select a value for the variable. The "valueMustBeChoice=" attribute (Boolean) of the string element specifies whether the user must choose from the predefined values or can enter a custom value.

You can specify more validation criteria for the variable in one or more of the following ways:

Minimum length (<minLength>) or maximum length (<maxLength>), or both, of the string value
Predefined validation type (<validationType>) to be provided by the Workflows task. You can request validation for common constructs, such as data set names, data set qualifiers, z/OS user IDs. For a list of available validation types, see Variable definition elements and types summary.
Regular expression (<regularExpression>) that you provide when neither of the other mechanisms meet your requirements. The regular expression must adhere to the JavaScript standard; see the document posted at http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf.

The criteria that you specify are enforced by the Workflows task in real time as the user types the input value. If the user specifies incorrect syntax, for example, the Workflows task displays the variable in red, along with a default error message, which you can override by providing the error message element (<errorMessage>). Any default or choice value that you specify in the variable definition is also subject to these criteria.

The Workflows task cannot load an XML file that violates the criteria. Similarly, you cannot define the "valueMustBeChoice=" attribute with a value of true without defining any choices.

integer

The Workflows task displays the variable in a text box, initially set to a value that you can optionally specify. The Workflows task restricts the user’s input value to a signed 31-bit value (in the range of -2147483648 to 2147483647). You can optionally specify a minimum value (<minValue>) and maximum value (<maxValue>) for the integer. The Workflows task validates the default value against the minimum and maximum when the workflow definition file is imported into z/OSMF.

decimal

The Workflows task displays the variable in a text box, initially set to a value that you can optionally specify. A decimal is an integer with a "decimalPlaces=" attribute on the <decimal> element. A decimal value allows the same whole number value as an integer, plus up to six decimal places (that is, a value in the range of -2147483648.999999 to 2147483647.999999). The "decimalPlaces=" attribute has a default value of 1. You can optionally specify a minimum value (<minValue>) and maximum value (<maxValue>) for the decimal. The Workflows task validates the default value against the minimum and maximum when the workflow definition file is imported into z/OSMF.

time

The Workflows task displays the variable in a timebox. By default, the time is displayed in 15-minute increments, based on your specified default, or the current time, if you do not specify a default. The user can type in a value, also. You can optionally specify a minimum value (<minValue>) and maximum value (<maxValue>) for the time. The Workflows task restricts the user input to the range you specify.

Note:

You specify this variable in hours-minutes-seconds format (hh:mm:ss), but the timebox displays the time in a slightly different format.
The schema allows slight variations of this format, but the Workflows task does not. Using a time format other than hh:mm:ss can have an unpredictable result.

date

The Workflows task displays the variable in a calendar, for which the date is based on your specified value, or the current date, if you do not specify a value. The user can type in a value, also. You can optionally specify a minimum value (<minValue>) and maximum value (<maxValue>) for the date. The Workflows task restricts the user input to the range you specify.

Note:

You specify this variable in year-month-day format (yyyy-mm-dd), but the calendar displays the date in a slightly different format.
The schema allows slight variations of this format, but the Workflows task does not. Using a date format other than yyyy-mm-dd might have an unpredictable result.

password

By defining a password variable, you can add a password prompt to your workflow. If you do so, the user is prompted to provide a password on the Input Variables tab of the Workflows task. In the user interface, the password variable is displayed as an input field. For a Provisioning workflow, the input field replaces the user's typed characters with masking characters, such as asterisks ('********'). For General workflows and Configuration workflows, the input field is not masked; the password is shown as it is typed.

You must specify either of the following types of validation checking for a password variable:

Minimum length (<minLength>) or maximum length (<maxLength>), or both, of the password value.
Match with a regular expression (<regularExpression>). The expression must adhere to the JavaScript standard; see the document posted at http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf.

The criteria that you specify are enforced by the Workflows task in real time as the user types the input value. If the user specifies an incorrect syntax, for example, the Workflows task displays the variable in red, along with a default error message, which you can override by providing the error message element (<errorMessage>).

The password variable type has no default value.