If you can't find the product or version you're looking for, visit support.ataccama.com/downloads

Workflow Variables

When to use workflow variables?

Workflows support defining and using variables for the following use cases:

Passing information from the outside to the tasks inside the workflow.
Storing and passing information read by tasks (for example, Read SQL Result) to other tasks or links inside the workflow.
Passing information to ONE plans.

Naming conventions

Variable names are case insensitive and must match the following regular expression: [a-zA-Z_][a-zA-Z0-9_]+.

Do not use the prefix ewf_ when naming user-defined variables as it is reserved for system variables.

Variable types

Input variables

Input variables provide a means for passing a value to the workflow before the workflow is started.

Examples

The path to a text file, which is passed as a parameter to the Text File Reader or Writer step.
The path to the plan file that should be executed.
As a parameter in an SQL query.
Specifying a source and target files to be moved or copied.
Using the input value to determine which of the links leading from a task are triggered.

Derived variables

Derived variables provide a means to calculate a value before the workflow is started without user input. The values of these variables are hard-coded when the variables are defined.

Derived variables are a convenient way of defining a value in one place and using it in different tasks across the workflow. If you need to change anything, it is enough to edit the variable only once.

Examples

Calculating today’s date in a predefined format, for example, tostring(DATEADD(now(),-1,'DAY'),'yyyyMMdd'), and then using it in SQL queries ("select records with this timestamp") or get input files that contain a timestamp of a specific format in their name.
Output folders for files processed by ONE plans.
Specification of the output file names structure: assume that you have many tasks that output .txt files with a predefined name structure. If you need to change the structure, for example, add a timestamp, you can do it in the derived variables.

System variables

System variables are predefined reserved variables that provide some basic information about the environment where the workflow is run. All of these variables are named using the ewf_ prefix, so we recommend not using this prefix when naming user-defined variables in order to avoid confusion between system and user-defined variables.

Variable name Description

ewf_execution_id

Returns the ID of the current workflow instance (execution).

ewf_workflow_id

Contains the identification of the workflow this instance is created from (identification is the filename of the workflow definition).

ewf_private_folder

Returns execution’s resource folder that is suitable for storing temporary files. The folder returned is the one where task resource folders are stored in.

The folder is automatically deleted once the related instance is removed from the workflow component history.

ewf_user_name

Populated for the following actions:

Launch workflow
Resume
Forced resume

These actions are performed from the ONE Runtime Server Admin via user interaction secured using Keycloak.

Username is not stated when Keycloak is not used.
Username is not stated when the workflow is executed via onlinectl command.

Task variables

Some tasks can store values that they obtain during their execution as variables to be used by other tasks. These variables can be either predefined or user-defined, depending on the task.

Examples

Run a SELECT statement with the Read SQL Result task, store one or several columns values as variables, and then use them in other tasks.

Define workflow variables

To define variables for a workflow, double-click the canvas and in Global Properties open the Variables node. Fill in a unique variable Name, and for derived variables define an Expression that is used to calculate the variable’s value.

Use variables in a workflow

In semi-expression task properties

Some task properties can expect string values. These properties are marked with "semi-expression" in the task documentation. For more detailed information about semi-expressions, see Expressions in Workflows.

To pass variables to these fields, use the following notation:

${var01}

For example, consider a variable used in the Run Windows Command task:

Variables in semi-expression task properties

In expression task properties

Some workflow configuration fields are treated as expressions (usually any configuration field called Expression). These properties are marked with "expression" in the task documentation. In this context, a variable can be used as it is. For detailed information about the expression context, see Expressions in Workflows.

For example, consider an input variable filevar. The following example shows how this variable can be used in the Run DQC task.

In SQL task properties

Properties of tasks that expect an SQL query, for example, Read SQL Result or Execute SQL, are a special case of the semi-expression context. When passing variables values to such tasks, there are two notations depending on where they are used:

${table_name_var} - Used for table and column names.
${var01} - Used for values in WHERE clauses and INSERT and UPDATE statements. This notation is the implementation of bind variables in workflows with all the performance and security benefits that they offer.

For example:

SELECT ${column_name_var} FROM ${table_name_var} WHERE id = ${var01}

INSERT INTO my_table(batch_ID,time_stamp) VALUES (${var_batch_id},CURRENT_TIMESTAMP)

UPDATE my_table SET time_stamp = ${variable_with_value} WHERE batch_id = ${var_batch_id}

In links

When used in link conditions, variables can be used like in expressions. For example, see the var01 variable used in the following link condition.

In other variables

A variable can also be used in other variables. For example, an input or task variable can be used in a derived variable. A frequent reason for this is to change the data type of a variable, which is always string. For more information, see Change the variable data type.

Using task variables

Task variables are passed to tasks using the ewfGetTaskVariable expression.

For example:

Task variable used in Run Windows Command

echo ${ewfGetTaskVariable('10_Check_Db_Structure', 'table_name')}

Task variable used in Run Shell Script

echo $%ewfGetTaskVariable('10_Check_Db_Structure','table_name')%

Task variable used in Read SQL Result

SELECT ${column} FROM ${ewfGetTaskVariable('10_Check_Db_Structure', 'table_name')} WHERE id = ${var01}

Pass input variable values on execution

See Execute Workflows for more information about how to pass input variables when executing workflows.

Pass variables as parameters to ONE components

In a ONE component, map a step property as a parameter. See Component Steps.
In your workflow, use the Run DQC or Run DQC Process task.
Open the task properties and switch to the Configuration tab.
Under Parameters, for each parameter in the component, do the following:
1. Enter the parameter name into the Name field.
2. Use a variable in the Expression field.

The Expression is evaluated within the workflow task and only the expression result is passed to the component. Make sure you use the expression syntax (see Expressions in Workflows) and that the expression results in a datatype or expression expected by the relevant component property.

Change the variable data type

Sometimes it is necessary to change the data type of the variable value to use it in certain tasks or expressions. For example, you might want to use a variable in an INSERT SQL statement, which expects a datetime or an integer value.

Here is what you should keep in mind:

Input variables are always STRING. A data type of the derived variable depends on the defining expression.
Inside the workflow, the derived variable retains its data type, but you can apply a conversion (recast it) wherever needed.
When you pass variables to ONE plans, they leave the workflow with the data type according to the defining expression (that is, they have the same data type as the result of the expression defined in the place where the variable is passed).

To change the data type of a variable from STRING to another type, do a recast. For example, if you have an input variable inputVar, which you want to use as a datetime, you can recast it in two ways:

Define a derived variable named derivedVar as follows:

toDateTime(inputVar,"MM/dd/yyyy","en-us") //copy the content of inputVar and change the data type according to the format of inputVar

Use this derived variable directly in a particular task. The following is an example of an INSERT statement in a Execute SQL task:

INSERT INTO my_table(time_stamp) VALUES (${derivedVar})

Apply a conversion expression in a particular task (without a derived variable, but a conversion must be done wherever needed):

INSERT INTO my_table(time_stamp) VALUES (${toDateTime(inputVar,"MM/dd/yyyy","en-us")})

Note that because the SQL statement in the Execute SQL task is written into a semi-expression field, the whole expression is wrapped into ${}. For more information, see Expressions in Workflows.

The same applies to expressions in a link. You can either use a derived variable as it is or recast it locally.

For example:

var01=5 //var01 is a derived variable of type INTEGER so you can use it as it is
toInteger(var02)=5 //var02 is STRING but you need to use it as INTEGER; apply a conversion first

Was this page useful?