Working with Workflow Variables

By PenchalaRaju.Yanamala

This chapter includes the following topics:

Working with Workflow Variables Overview

Predefined Workflow Variables
User-Defined Workflow Variables

Working with Workflow Variables Overview

You can create and use variables in a workflow to reference values and record
information. For example, use a variable in a Decision task to determine whether
the previous task ran properly. If it did, you can run the next task. If not, you can
stop the workflow.

Use the following types of workflow variables:

Predefined workflow variables. The Workflow Manager provides predefined

workflow variables for tasks within a workflow. For more information, see
Predefined Workflow Variables.
User-defined workflow variables. You create user-defined workflow variables
when you create a workflow. For more information, see User-Defined Workflow
Variables.

Use workflow variables when you configure the following types of tasks:

Assignment tasks. Use an Assignment task to assign a value to a user-defined

workflow variable. For example, you can increment a user-defined counter
variable by setting the variable to its current value plus 1. For more information
about using workflow variables in Assignment tasks, see Working with the
Assignment Task.
Decision tasks. Decision tasks determine how the Integration Service runs a
workflow. For example, use the Status variable to run a second session only if
the first session completes successfully. For more information about using
workflow variables in Decision tasks, see Working with the Decision Task.
Links. Links connect each workflow task. Use workflow variables in links to
create branches in the workflow. For example, after a Decision task, you can
create one link to follow when the decision condition evaluates to true, and
another link to follow when the decision condition evaluates to false. For more
information about using workflow variables in Link tasks, see Working with
Links.
Timer tasks. Timer tasks specify when the Integration Service begins to run the
next task in the workflow. Use a user-defined date/time variable to specify the
time the Integration Service starts to run the next task. For more information
about using workflow variables in Timer tasks, see Working with the Timer Task.

Use the Expression Editor to create an expression that uses variables. When you
build an expression, you can select predefined variables on the Predefined tab.
You can select user-defined variables on the User-Defined tab. The Functions
tab contains functions that you use with workflow variables. Use the point-and-
click method to enter an expression using a variable.
Use the following keywords to write expressions for user-defined and predefined
workflow variables:

AND
OR
NOT
TRUE
FALSE
NULL
SYSDATE
Related Topics:

Predefined Workflow Variables

Each workflow contains a set of predefined variables that you use to evaluate
workflow and task conditions. Use the following types of predefined variables:

Task-specific variables. The Workflow Manager provides a set of task-specific

variables for each task in the workflow. Use task-specific variables in a link
condition to control the path the Integration Service takes when running the
workflow. The Workflow Manager lists task-specific variables under the task
name in the Expression Editor.
Built-in variables. Use built-in variables in a workflow to return run-time or
system information such as folder name, Integration Service Name, system
date, or workflow start time. The Workflow Manager lists built-in variables under
the Built-in node in the Expression Editor. For more information about built-in
variables, see the PowerCenter Transformation Language Reference.

Tip: When you set the error severity level for log files to Tracing in the
PowerCenter Server setup, the workflow log displays the values of workflow
variables. Use this logging level for troubleshooting only.

Table 4-1 lists the task-specific workflow variables available in the Workflow
Manager:

Table 4-1. Task-Specific Workflow Variables

Task-Specific Description Task Datatype
Variables Types
Condition Evaluation result of decision condition Decision Integer
expression.
If the task fails, the Workflow Manager
keeps the condition set to null.
Sample syntax:
$Dec_TaskStatus.Condition = <TRUE |
FALSE | NULL | any integer>
EndTime Date and time the associated task ended. All tasks Date/Time
Precision is to the second.
Sample syntax:
$s_item_summary.EndTime >
TO_DATE('11/10/2004 08:13:25')
ErrorCode Last error code for the associated task. If All tasks Integer
there is no error, the Integration Service sets
ErrorCode to 0 when the task completes.
Sample syntax:
 $s_item_summary.ErrorCode = 24013
Note: You might use this variable when a
task consistently fails with this final error
message.
ErrorMsg Last error message for the associated task. All tasks Nstring*
If there is no error, the Integration Service
sets ErrorMsg to an empty string when the
task completes.
Sample syntax:
$s_item_summary.ErrorMsg = 'PETL_24013
Session run completed with failure
Note: You might use this variable when a
task consistently fails with this final error
message.
FirstErrorCode Error code for the first error message in the Session Integer
session.
If there is no error, the Integration Service
sets FirstErrorCode to 0 when the session
completes.
Sample syntax:
$s_item_summary.FirstErrorCode = 7086
FirstErrorMsg First error message in the session. Session Nstring*
If there is no error, the Integration Service
sets FirstErrorMsg to an empty string when
the task completes.
Sample syntax:
$s_item_summary.FirstErrorMsg =
'TE_7086 Tscrubber: Debug info… Failed to
evalWrapUp'
PrevTaskStatus Status of the previous task in the workflow All tasks Integer
that the Integration Service ran. Statuses
include:
-
ABORTED
-
FAILED
-
STOPPED
-
SUCCEEDED
Use these key words when writing
expressions to evaluate the status of the
previous task.
Sample syntax:
$Dec_TaskStatus.PrevTaskStatus =
FAILED
SrcFailedRows Total number of rows the Integration Service Session Integer
failed to read from the source.
Sample syntax:
$s_dist_loc.SrcFailedRows = 0
SrcSuccessRows Total number of rows successfully read from Session Integer
the sources.
Sample syntax:
$s_dist_loc.SrcSuccessRows > 2500
StartTime Date and time the associated task started. All tasks Date/Time
Precision is to the second.
Sample syntax:
$s_item_summary.StartTime >
TO_DATE('11/10/2004 08:13:25')
Status Status of the previous task in the workflow. All tasks Integer
Statuses include:
-
ABORTED
-
DISABLED
-
FAILED
-
NOTSTARTED
-
STARTED
-
STOPPED
-
SUCCEEDED
Use these key words when writing
expressions to evaluate the status of the
current task.
Sample syntax:
$s_dist_loc.Status = SUCCEEDED
TgtFailedRows Total number of rows the Integration Service Session Integer
failed to write to the target.
Sample syntax:
$s_dist_loc.TgtFailedRows = 0
TgtSuccessRows Total number of rows successfully written to Session Integer
the target
Sample syntax:
$s_dist_loc.TgtSuccessRows > 0
TotalTransErrors Total number of transformation errors. Session Integer
Sample syntax:
$s_dist_loc.TotalTransErrors = 5
* Variables of type Nstring can have a maximum length of 600 characters.

All predefined workflow variables except Status have a default value of null. The
Integration Service uses the default value of null when it encounters a predefined
variable from a task that has not yet run in the workflow. Therefore, expressions
and link conditions that depend upon tasks not yet run are valid. The default
value of Status is NOTSTARTED.

Related Topics:
Evaluating Task Status in a Workflow

Using Predefined Workflow Variables in Expressions

When you use a workflow variable in an expression, the Integration Service

evaluates the expression and returns True or False. If the condition evaluates to
true, the Integration Service runs the next task. The Integration Service writes an
entry in the workflow log similar to the following message:
INFO : LM_36506 : (1980|1040) Link [Session2 --> Session3]: condition is TRUE
for the expression [$Session2.PrevTaskStatus = SUCCEEDED].

The Expression Editor displays the predefined workflow variables on the

Predefined tab. The Workflow Manager groups task-specific variables by task
and lists built-in variables under the Built-in node. To use a variable in an
expression, double-click the variable. The Expression Editor displays task-
specific variables in the Expression field in the following format:

$<TaskName>.<predefinedVariable>
2.Add a Start task and both sessions to the workflow.
3.Place a Decision task after the session that updates the local orders database.
Set up the decision condition to check to see if the number of workflow runs is
evenly divisible by 10. Use the modulus (MOD) function to do this.
4.Create an Assignment task to increment the $$WorkflowCount variable by one.
Link the Decision task to the session that updates the database at
headquarters when the decision condition evaluates to true. Link it to the
5.Assignment task when the decision condition evaluates to false.

When you configure workflow variables using conditions, the session that
updates the local database runs every time the workflow runs. The session that
updates the database at headquarters runs every 10th time the workflow runs.

Workflow Variable Start and Current Values

Conceptually, the Integration Service holds two different values for a workflow
variable during a workflow run:

Start value of a workflow variable

Current value of a workflow variable

The start value is the value of the variable at the start of the workflow. The start
value could be a value defined in the parameter file for the variable, a value
saved in the repository from the previous run of the workflow, a user-defined
initial value for the variable, or the default value based on the variable datatype.

The Integration Service looks for the start value of a variable in the following
order:

1.Value in parameter file

2.Value saved in the repository (if the variable is persistent)
3.User-specified default value
4.Datatype default value

For more information about datatype default values, see Table 4-2.

For example, you create a workflow variable in a workflow and enter a default
value, but you do not define a value for the variable in a parameter file. The first
time the Integration Service runs the workflow, it evaluates the start value of the
variable to the user-defined default value.

If you declare the variable as persistent, the Integration Service saves the value
of the variable to the repository at the end of the workflow run. The next time the
workflow runs, the Integration Service evaluates the start value of the variable as
the value saved in the repository.

If the variable is non-persistent, the Integration Service does not save the value
of the variable. The next time the workflow runs, the Integration Service
evaluates the start value of the variable as the user-specified default value.

If you want to override the value saved in the repository before running a
workflow, you need to define a value for the variable in a parameter file. When
you define a workflow variable in the parameter file, the Integration Service uses
this value instead of the value saved in the repository or the configured initial
value for the variable.

The current value is the value of the variable as the workflow progresses. When
a workflow starts, the current value of a variable is the same as the start value.
The value of the variable can change as the workflow progresses if you create an
Assignment task that updates the value of the variable.

If the variable is persistent, the Integration Service saves the current value of the
variable to the repository at the end of a successful workflow run. If the workflow
fails to complete, the Integration Service does not update the value of the
variable in the repository.

The Integration Service states the value saved to the repository for each
workflow variable in the workflow log.

Datatype Default Values

If the Integration Service cannot determine the start value of a variable by any
other means, it uses a default value for the variable based on its datatype.

Table 4-2 lists the datatype default values for user-defined workflow variables:

Table 4-2. Datatype Default Values for User-Defined Workflow Variables

Datatype Workflow Manager Default Value
Date/Time 1/1/1753 00:00:00.000000000 A.D.
Double 0
Integer 0
Nstring Empty string
Related Topics:
Workflow Variable Start and Current Values

Creating User-Defined Workflow Variables

You can create workflow variables for a workflow in the workflow properties.

To create a workflow variable:

1.In the Workflow Designer, create a new workflow or edit an existing one.
2.Select the Variables tab.
3.Click Add.
4.Enter the information in Table 4-3 and click OK:
Table 4-3. Options for Declaring User-Defined Workflow Variables
Field Description
Name Variable name. The correct format is $$VariableName. Workflow
variable names are not case sensitive.
Do not use a single dollar sign ($) for a user-defined workflow
variable. The single dollar sign is reserved for predefined workflow
variables.
Datatype Datatype of the variable. You can select from the following datatypes:
-Date/Time
-Double
-Integer
-Nstring
Persistent Whether the variable is persistent. Enable this option if you want the
value of the variable retained from one execution of the workflow to
the next.
Default Default value of the variable. The Integration Service uses this value
Value for the variable during sessions if you do not set a value for the
variable in the parameter file and there is no value stored in the
repository.
Variables of type Date/Time can have the following formats:
-MM/DD/RR
-MM/DD/YYYY
-MM/DD/RR HH24:MI
-MM/DD/YYYY HH24:MI
-MM/DD/RR HH24:MI:SS
-MM/DD/YYYY HH24:MI:SS
-MM/DD/RR HH24:MI:SS.MS
-MM/DD/YYYY HH24:MI:SS.MS
-MM/DD/RR HH24:MI:SS.US
-MM/DD/YYYY HH24:MI:SS.US
-MM/DD/RR HH24:MI:SS.NS
-MM/DD/YYYY HH24:MI:SS.NS
You can use the following separators: dash (-), slash (/), backslash (\),
colon (:), period (.), and space. The Integration Service ignores extra
spaces. You cannot use one- or three-digit values for year or the
“HH12” format for hour.
Variables of type Nstring can have a maximum length of 600
characters.
Is Null Whether the default value of the variable is null. If the default value is
null, enable this option.
Description Description associated with the variable.
To validate the default value of the new workflow variable, click the Validate
5.button.
6.Click Apply to save the new workflow variable.
7.Click OK.