Expressions

Node parameters, and when using Set Variables also variables, can be calculated from expressions.

Using expressions with parameters

Selecting Expression from the drop-down list, the Value field changes to a code editor, where you can configure an expression:

Referencing variables and functions

To reference a variable, the notation $VariableName$is used. Type a $character, and the variable suggestion box will appear:

The expression language used is the OmniFi expression language used in the Calculated Columns modifier, and in various places in Autotest and the Web portal. While the OmniFi expression language is case-insensitive, the function suggestion box can be opened by typing an upper-case character:

Expressions and the Array data type

Workflow arrays are handled as Lists in the workflow engine, and expressions is a convenient way to create arrays:

You can even create 2-dimensional (jagged) arrays using expressions:

List()
+ (List() + "Header A" + "Header B")
+ (List() + $Value A$ + $Value B$)

Note however that arrays in Workflows are strongly typed, so all elements in an array, regardless of rank, must be of the same type, e.g. String. $Value A$and $Value B$must be String variables, since the data type of the 2D array is String[][].

Validating expressions

To validate the expression, close the expression editor by clicking anywhere outside it and click the debug button at the top-right of the expression field:

If the expression is invalid, an error icon appears, that can be hovered for more information.

Lists are untyped in the OmniFi expression engine, so List() + "text" + 42is technically a well formed expression even though the first element is a string and the second is a number. Workflow arrays are strongly typed, expecting all elements of an array to match the array element type, i.e. either string array or date etc., so the above expression is not well formed in a workflow.

When validating an array expression, the result is always inconclusive, since the expression has to execute in full context (running the workflow) to correctly validate the type of each element, i.e. array types can only be evaluated runtime.

Special cases

📘

Not all data types can be handled via expressions. The Passworddata type is a string, but guaranteed to be handled securely:

• Encrypted throughout the workflow execution and decrypted only when sent to a node.
• Never sent to the users web browser in clear-text or encrypted form.

For this reason, Passwordvalues cannot be calculated by expressions, and Passwordvariables cannot be referenced by expressions.

Another data type that _can be used in expressions is File. As shown previously, file arrays can be created using expressions and used e.g. as attachments to email combining the List()function and referencing file variables.

But like Password, Fileis a special type protecting against malicious reads and writes outside of the workflow execution folder. Certain nodes are allowed to import and export files outside of this folder, but you are not allowed to arbitrarily reference files on disk, only files within the working folder of the current workflow execution. For example, a file expression like "C:\Windows\System32\etc\hosts" is blocked runtime.

📘

Renaming a file

You can rename a file using the Copy File node, but a short-hand way is to do it using expressions. Workflow files support a syntax that provides a name for a file on the form <physical-path-to-file>?<new-file-name>.

This means you can use an expression like $Report Workbook$ + "?My File Name.xlsx"to rename a file in Set Variables instead, or you can rename files directly in e.g. the Send Email attachments expression:

Indexing into a file array

You can pick out a file element in a file array by using the ElementAt() function.

This allows you to for example loop over the output of a Report Task and conditionally treat each iteration individually.