Using Velocity templates for variable substitution and other functions

The z/OSMF symbol replacement mechanism uses the open source Velocity engine created by the Apache Velocity Project. Though the Velocity engine can be used for simple string replacement, it also contains conditional directives that allow you to generate different strings, based on the presence or value of any variable that is referenced by the step. The type of the variable, as defined in the XML, is passed in to the Velocity engine so that the expected behavior is preserved, except for time and date, which are passed in as strings.

The following example shows a simple step with manual instructions.

<step name="Step1" >
        <title>
            Define the started task user ID to SAF.
        </title>
        <description>
            Define the started task user ID to SAF.
        </description>
        <instructions>
            You must define the user ID to your security product.
            For example, for RACF:<br/>
                  ADDUSER STASK OMVS(UID(18136) HOME(/u/stask))
            <br/><br/>
            After you have entered this command from the TSO command line, 
            press <strong>Finish</strong> to complete the step.
        </instructions>
        <weight>2</weight>
        <skills>Security administration</skills>
</step>

Suppose that you want to prompt the user for input, which might then be substituted in the command image that is contained in the instructions. To do so, you can modify this step to include a variable. In the example that follows, the reference to UID 18136 in the previous example is replaced with a variable that is used to prompt the user for a UID.

<step name="Step1" >
        <title>
            Define the started task user ID to SAF.
        </title>
        <description>
            Define the started task user ID to SAF. You will be
		         prompted for the UNIX UID to assign to the user.
        </description>
        <variableValue name="uid" required="true"/>
        <instructions substitution="true">
            You must define the user ID to your security product.
            For example, for RACF:<br/>
                  ADDUSER STASK OMVS(UID($instance-uid) HOME(/u/stask))
            <br/><br/>
            After you have entered this command from the TSO command line, 
            press <strong>Finish</strong> to complete the step.
        </instructions>
        <weight>2</weight>
        <skills>Security administration</skills>
</step>

In the example, observe the following considerations:

User input is defined by using the variableValue element. In this example, the variable is named uid.
Substitution is performed by using a variable reference, which is $instance-uid in this example.
A variable reference follows this format:
- Dollar sign ($)
- Scope, which is either instance or global
- Hyphen (-)
- Variable name, for example, uid.

For more examples of how to code symbolic variable references within instructions and templates, see file workflow_sample_wizards.xml, which is supplied with z/OSMF in the /samples subdirectory of the product file system.

Note:

When you are using Velocity comparison operators in the instructions, do not use the less than ("<") and greater than (">") characters, as they interfere with XML. Instead, use the alternative notation: lt, le, gt, and ge.
White space (newlines, tabs, spaces) is collapsed before text is displayed in the Workflows task. The indenting that is shown in this example is included for readability only. To obtain the desired spacing for your workflow in the Workflows task, you must provide the appropriate HTML formatting tags. You might need to experiment with the spacing somewhat.

For more information about the Velocity engine, see the following website: http://velocity.apache.org.