Workflow expressions let you evaluate, transform, and combine workflow data at runtime. You use expressions in fields such as conditions, mappings, data transformations, state variables, and list processing.
Workflow expressions use the JSONata expression language.
For an introduction to workflow variables, see Understand workflow variables.
Where expressions are used
Expressions are available in workflow actions that evaluate or manipulate data.
Common examples include:
- Condition
- Transform
- Set State
- Run Tool input mappings
- Wait configuration
- Process List
- Start input mappings
Expression fields support Insert Variable to help you reference workflow data.
Referencing workflow variables
Use workflow variable paths to reference values produced during a workflow run.
| Variable type | Example |
| Workflow input | $.inputs.employeeId |
| Action output | $.CreateRequest.requestId |
| State variable | $requestNumber |
| Current list item | $.item |
Expressions can combine multiple variables into a single result.
Operators
Use operators to compare values or build logical expressions.
Comparison
| Operator | Description |
| = | Equal to |
| != | Not equal to |
| > | Greater than |
| < | Less than |
| >= | Greater than or equal to |
| <= | Less than or equal to |
Logical
| Operator | Description |
| and | Both expressions are true |
| or | Either expression is true |
| not | Negates an expression |
Arithmetic
| Operator | Description |
| + | Add |
| - | Subtract |
| * | Multiply |
| / | Divide |
Common functions
Workflow expressions support standard JSONata functions.
Some commonly used functions include:
| Function | Purpose |
| $string() | Convert a value to text. |
| $number() | Convert a value to a number. |
| $boolean() | Convert a value to true or false. |
| $exists() | Check whether a value exists. |
| $count() | Count the number of items in an array. |
| $append() | Add items to an array. |
| $substring() | Return part of a string. |
| $uppercase() | Convert text to uppercase. |
| $lowercase() | Convert text to lowercase. |
Additional JSONata functions are also supported.
Example expressions
Compare a value
$.inputs.employeeType = "Manager"
Returns true when the employee type is Manager.
Check whether a value exists
$exists($.ManagerApproval.status)
Returns true if the value exists.
Combine values
$.inputs.firstName & " " & $.inputs.lastName
Returns the employee's full name.
Calculate a value
$.inputs.daysRequested * 24
Returns the requested number of hours.
Count list items
$count($.items)
Returns the number of items in the collection.
Using expressions in conditions
Condition actions evaluate an expression and follow the appropriate branch.
For example:
$.CreateRequest.status = "Approved"
If the expression evaluates to true, the workflow follows the True branch.
Otherwise, it follows the False branch.
Using expressions in transformations
Transform actions use expressions to reshape workflow data.
Typical scenarios include:
- Creating new objects
- Renaming properties
- Formatting values
- Combining multiple variables
- Preparing payloads for integrations
Expression validation
Workflow expressions are validated before a workflow is published.
Validation can detect problems such as:
- Invalid syntax
- Unknown variables
- Missing references
- Type mismatches
Resolve validation errors before publishing the workflow.
Best practices
When writing expressions:
- Keep expressions as simple as possible.
- Reuse workflow variables instead of repeating calculations.
- Use descriptive state variable names.
- Test complex expressions before publishing.
- Break large calculations into smaller Transform actions when appropriate.