Lead your team forward
OCT 24 / 9AM ET Register nowWorkflow 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:
These actions are performed from the ONE Runtime Server Admin via user interaction secured using Keycloak.
|
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:
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 inWHERE
clauses andINSERT
andUPDATE
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:
echo ${ewfGetTaskVariable('10_Check_Db_Structure', 'table_name')}
echo $%ewfGetTaskVariable('10_Check_Db_Structure','table_name')%
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:
-
Enter the parameter name into the Name field.
-
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?