User-Defined Workflow Variables
Create user-defined workflow variables to capture task output or to make a workflow decision based on criteria that you specify. You can create a user-defined workflow variable of datatype boolean, date, integer, or string.
To use user-defined workflow variables, complete the following steps:
- 1. Create a workflow variable with an initial value.
The Data Integration Service uses the initial value of the variable when the workflow starts.
- 2. Configure the workflow to assign a run-time value to the variable.
As a workflow progresses, the Data Integration Service can calculate and change the initial variable value according to how you configure the workflow. You can assign a value to a user-defined variable using an Assignment task. Or, you can assign a value to a user-defined variable using task output.
- 3. Use the variable in a conditional sequence flow or in a task field so that the Data Integration Service uses the variable value at run time.
Creating a User-Defined Variable
Create a user-defined workflow variable to record run-time information.
1. Open the workflow in the editor.
2. Create a user-defined workflow variable in the workflow properties or in a task properties.
- - In the workflow Properties view, click the Variables tab. In the User view, click Add.
- - In a task Properties view, select the Input tab or Output tab. Select New Variable in the Value or Variable column.
The Add Variable dialog box displays.
3. Enter a name and optionally a description for the variable.
4. Select the variable datatype.
5. Enter an initial value for the variable.
6. Click OK.
Assign a Value with an Assignment Task
An Assignment task assigns a value to a user-defined workflow variable.
When you create a user-defined workflow variable, you enter an initial value. The Data Integration Service uses the initial value of the variable when the workflow starts. You can add an Assignment task to the workflow to assign another value to the variable. The Data Integration Service uses the assigned value for the variable during the remainder of the workflow.
For example, you create a counter variable and set the initial value to 0. In the Assignment task, you increment the variable by setting the variable to its current value plus 1.
When you add an Assignment task to a workflow, you select the user-defined variable whose value you want to change. Then, you write an expression to assign a value to the selected variable.
The following table lists the values that you can assign to a user-defined variable:
Value | Example |
|---|
Literal value | For example, to assign the value 500 to a user-defined variable, enter the following value in the expression: 500 |
Workflow parameter | For example, to assign the value of a workflow parameter to a user-defined variable, enter the following value in the expression: $par:MyParameter |
Workflow system or user-defined variable | For example, to assign the value of a workflow system or user-defined variable to another user-defined variable, enter the following value in the expression: $var:MyVariable |
Any valid expression using the transformation language functions and operators | The expression must return a boolean, date, integer, or string value. Use a conversion function to convert a return value with another datatype to one of the supported datatypes. For example, to assign the value of an expression to a user-defined variable, enter the following value in the expression: LENGTH('test') If you use the equality operator (=) in the expression, the Data Integration Service checks whether both sides of the expression are equal and returns true or false. For example, the following expression assigns either true or false to the selected user-defined variable: $var.MyVariable = 7 + 5 |
You cannot assign values to system workflow variables.
Parameters and Variables in Assignment Expressions
You can include workflow parameters and variables in the expression value that you assign to a user-defined workflow variable.
You can select a workflow parameter or variable from the Inputs tab in the Assignment Expression Editor, or you can type the parameter or variable name in the expression using the required syntax.
For example, you create a user-defined workflow variable named Counter and set the initial value to 0. Use the Assignment task to increment the value of the variable by 1. Enter the following expression in the Assignment task:
$var:Counter + 1
The Data Integration Service does not resolve workflow variable or parameter values that are included in a string literal in an assignment expression. For example, you use an Assignment task to assign the following value to a variable:
‘The mapping completed successfully: ${var:MappingIsSuccessful}’
The Data Integration Service does not evaluate the string literal, and so does not resolve the MappingIsSuccessful variable value. The Data Integration Service displays the variable name in the string.
Configuring an Assignment Task
Before you can use an Assignment task to assign a value to a user-defined workflow variable, you must create the workflow variable with an initial value.
1. Add an Assignment task to the workflow.
2. Select the Assignment task in the editor.
3. In the Properties view, click the Assignment tab.
4. In the User-defined Variable column, select a user-defined workflow variable.
5. Click the arrow in the Expression column.
The Assignment Expression Editor appears.
6. Enter the value or expression to assign to the variable.
The Functions tab lists transformation language functions. The Inputs tab lists workflow parameters and variables. Double-click a function, parameter, or variable name to include it in the expression.
Type operators and literal values into the expression as needed.
7. Validate the expression using the Validate button.
Errors appear in a dialog box.
8. Fix errors and validate the expression again.
9. Click OK.
Assign a Value with Task Output
Assign task output to a user-defined workflow variable when you want to pass output data produced by the task to the remainder of the workflow.
When you create a user-defined workflow variable, you enter an initial value. The Data Integration Service uses the initial value of the variable when the workflow starts. You use a task Output tab to assign another value to the variable. After the task completes, the Data Integration Service uses the task output value for the variable during the remainder of the workflow.
For example, you create a workflow variable named CommandStdOutput and set the initial value to "test." In the Command task Output tab, you assign the CommandStdOutput workflow variable to the standard output returned by the command. When the workflow starts, the Data Integration Service sets the workflow variable value to "test." If you use the echo command in the Command task to print the value of the CommandStdOutput variable, the Data Integration Service prints the initial value of "test." After the Command task completes, the Data Integration Service sets the workflow variable value to the standard output returned by the command.
You cannot assign task output to system workflow variables.
Assigning Task Output
You can assign task output values to user-defined workflow variables.
1. Open the workflow in the editor.
2. Select a task that produces output data in the editor.
3. In the Properties view, click the Output tab.
The tab lists all output data that the task produces.
4. Enter a string to search for an output.
You can use wildcard characters in the string. The string is not case sensitive.
5. Click the Variable column for an output.
6. Select a variable name or click New Variable to create and assign a new variable to the output.
7. To clear an output assignment, select an output and click Clear. Or, click Clear All to clear all output assignments.
Mapping Task Output