Where to Use Workflow Variables
Use a workflow variable in an expression in a conditional sequence flow when you want the Data Integration Service to evaluate the variable value and then determine which object to run next. Use a workflow variable in a task field when you want the Data Integration Service to use the variable value for the field.
Depending on the expression or task field, you can select or type the workflow variable name.
The following table lists the objects and fields where you can use workflow variables:
Object | Tab or Dialog Box | Fields | Select or Type |
|---|
Sequence flow | Condition tab | Condition | both |
Assignment task | Assignment Expression Editor dialog box | Expression | both |
Command task | Command tab | Command | both |
Command task | Input tab | Advanced configuration properties assigned to task input | select |
Human task | Input tab | Number of items processed | select |
Mapping task | Input tab | User-defined mapping parameters Advanced configuration properties assigned to task input | select |
Notification task | Notification tab | Dynamic email content | type |
Notification task | Email Properties dialog box | Dynamic recipients Dynamic email addresses | select |
Notification task | Email Properties dialog box | Dynamic email content | both |
Assigning Variables to Task Input
Mapping and Command tasks include an Input tab where you specify the workflow variables that the task requires.
In a Mapping and Command task Input tab, you can assign task configuration properties to task input to define the value of the property in a workflow variable. The Advanced tab for a task lists the task configuration properties.
In a Mapping task Input tab, you can also assign user-defined mapping parameters to workflow variables to use workflow run-time data for the user-defined mapping parameter value.
1. Select a Mapping or Command task in the editor.
2. In the Properties view, click the Advanced tab to assign an advanced configuration property to task input.
In the Value column for a property, select Assigned to task input.
3. Click the Input tab.
4. Enter a string to search for an input.
You can use wildcard characters in the string. The string is not case sensitive.
5. Click the Value column for a configuration property or mapping parameter.
6. Assign the property or parameter to an existing workflow variable, to a new workflow variable, or to a literal value.
- - Select a workflow variable name.
- - Click New Variable. In the Add Variable dialog box, enter the name, type, and initial value for a workflow variable. The Developer tool creates the workflow variable and assigns the variable to the property.
- - Click New Value. In the Add Value dialog box, enter the literal value and datatype to assign to the property.
7. To clear an input assignment, select an input and click Clear. Or, click Clear All to clear all input assignments.
Variable Names in Expressions and Strings
When you use a workflow variable name in an expression or a string field, you can select the name from the Inputs tab or you can type the name using the required syntax.
The following table shows the required syntax for workflow variable names in expression and string fields:
Field | Syntax | Example |
|---|
Expression in a conditional sequence flow or in an Assignment task | - - $var:<variable_name> for user-defined variables
- - $var:sys.<variable_name> for system variables
| For example, you create a workflow variable named CommandExitCode and assign the exit code output value for a Command task to the variable. You create the following expression in the conditional sequence flow that connects the Command task to a Mapping task: $var:CommandExitCode = 0 The Data Integration Service evaluates the condition and runs the Mapping task if the previous Command task returned 0 in the exit code which indicates that the command succeeded. |
String field for a Command or Notification task | - - ${var:<variable_name>} for user-defined variables
- - ${var:sys.<variable_name>} for system variables
| When you enter a variable name in a string field for a Command or Notification task, you must include brackets around the variable name. For example, you create a workflow variable named MappingErrorRows and assign the number of error rows output value for a Mapping task to the variable. You enter the following text in the body of a Notification task: Mapping failed to write ${var:MappingErrorRows} rows to the target. |
If you do not include "var:" in the variable name, the Data Integration Service uses the name as a parameter. For example, if you enter $CommandExitCode or ${CommandExitCode}, the Data Integration Service uses $par:CommandExitCode or ${par:CommandExitCode}.
Escape Characters in Strings
When you use a workflow variable name in a string field, you can use an escape character so that the Data Integration Service displays the workflow variable name in the string instead of resolving the variable value.
Use the backslash (\) as an escape character before the ${...} syntax for workflow variable names.
For example, you have a workflow string variable named myVariable with a value of "test". You enter the following text in the body field for a Notification task:
Variable \${var:myVariable} has a value of ${var:myVariable}
When you run the workflow, the Data Integration Service displays the following string in the body field of the email:
Variable ${var:myVariable} has a value of test
Escape Characters in Directory Paths
If you use a workflow variable name within a directory path, you can use the escape character before the backslashes in the directory path.
The following table provides examples using the escape character with a variable name in a directory path:
Syntax in String Field | Output Value | Description |
|---|
C:\${var:myVariable} | C:${var:myVariable} | The Data Integration Service displays the variable name as a string. |
C:\\${var:myVariable} | C:\test | The Data Integration Service reads the backslash as a regular character and resolves the variable to its value. |
C:\temp\\${var:myVariable} | C:\temp\test | The Data Integration Service reads the backslash as a regular character and resolves the variable to its value. No escape character is required for the first backslash. |
C:\\\${var:myVariable} | C:\${var:myVariable} | The Data Integration Service reads the backslash as a regular character and displays the variable name as a string. |
C:\\\\${var:myVariable} | C:\\test | The Data Integration Service reads two backslashes as regular characters and resolves the variable to its value. |
Escape Characters in Command Tasks
Use a Command task to write the output of a command to a file. If the command output includes a variable name, use a backslash as an escape character to add the $ character before the variable name.
When you configure the Command task to run on a non-Windows operating system, use three backslashes. The first backslash is an escape character for the second backslash. The third backslash is an escape character for the $ character.
For example, you define the following command in the Command task:
echo \\\${var:myVariable} = ${var: myVariable} > file.txt
If the variable has a value of 10 when the workflow runs, the Command task writes the following string to file.txt:
${var:Var} = 10
Nested Variables
The Data Integration Service resolves one level of variable values. The Data Integration Service does not resolve variable values that are nested within another workflow parameter or variable.
For example, you create the following workflow variables with these datatypes and initial values:
- •Variable1 with an integer datatype and an initial value of 4
- •Variable2 with an integer datatype and an initial value of 3
- •Variable3 with a string datatype and an initial value of ${var:Variable1} + ${var:Variable2}
When you use Variable3 in an expression or task field, the Data Integration Service does not resolve the nested variables Variable1 and Variable2 to the value of 7. Instead, the Data Integration Service uses the following string value for Variable3:
${var:Variable1} + ${var:Variable2}
Mapping Task Input