Array variables

When you need to map a list of values or name-value pairs, use an array variable. Array variables provide an alternative to defining multiple variables to represent multiple values.

The format of an array variable can be either a list of individual values (an array list) or a set of one or more name-value pairs (a JSON array).

Unlike other types of variables, an array variable cannot be modified manually by the user from the Workflows task user interface (UI). Instead, an array variable can be set by using an output file in a workflow step (an inline template step or file template step). Therefore, the Workflows task does not display array variables to the user.

An array variable has no default value.

Note: An excessively large properties file with many thousands of array variables can degrade the performance of the Workflows task.

Examples of using array variables

Examples:

This array variable is formatted in a list of individual items:
```
["ZOSV24T", "DB211T"]
```

This array variable is formatted as a JSON array (name-value pairs):

[{"property1":"tt1","dsName":"TEST.DSNAME.TT1"},
      {"property1":"tt2","dsName":"TEST.DSNAME.TT2"},
      {"property1":"tt3","dsName":"TEST.DSNAME.TT2"}]

This array variable is defined for a hybrid format (both list and JSON array):
```
 ["ZOSV24T", "DB211T", 
     {"property1":"tt1","dsName":"TEST.DSNAME.TT1"}]
```

Performing substitution with array variables

As with other types of variables, substitution with array variables follows the conventions of the velocity template. For more information, see Using Velocity templates for variable substitution and other functions.

In the following example, the array variable testJsonArrayVariable is used in a script that is run by a workflow step.

Figure 1. Example of how an array variable might be used in a workflow step.

#foreach($test in $instance-testJsonArrayVariable)
#set($test.dsn=$test.dsn + 500)
$test.dsn
#end

The array variable is treated as a string during substitution in the workflow, as shown in Figure 2.

Figure 2. Example of how an array variable might be used in a workflow step.

<step name="complexCondition"
<title>Install Product ABC</title>
<description>In this step, both prereqTargetStateSet and normal targetStateSet are used together.</description>.
<prereqStep name="basicStep1"/>
<prereqDescription>If Basic Step 1 is completed, this step becomes ready to perform.</prereqDescription>
<prereqTargetStateSet>
<condition>
     <expression><![CDATA[${instance_testJsonArrayVariable} == '[{"dsn":"TEST.SYS1.LINKLIB","dstype":"PDS"}]']]>
     </expression>
     <description>Example of using an array variable</description>
     <!-- Target step state (skipped) is specified in this conditional step -->
     <targetState>Skipped</targetState>
</condition>

In the example in Figure 2, if the value of the variable $instance-testJsonArrayVariable is [{"dsn":"TEST.SYS1.LINKLIB","dstype":"PDS"}], the step is skipped.