JSONata expressions

A reference guide to writing JSONata expressions in the automation builder.

Overview

JSONata is a lightweight expression language for querying and transforming data. In the automation builder, JSONata expressions are used wherever a field accepts a dynamic value:

  • Step input fields: values passed to action steps, such as a record ID or an address string
  • Variable definitions: expressions evaluated in a Variables step and stored for reuse
  • Choice conditions: expressions evaluated in a Choice step to determine which branch to follow

Variable namespaces

Workflow variables always start with $. The variable picker (click the $ icon next to any field, or type $ into a field) shows all variables available at that point in the workflow, organized by namespace.

Namespace Source Details
$trigger The trigger that started the workflow: shape depends on the trigger type Triggers
$stepName The output of a named action step, for example, $createRecord Actions and the Action Reference
$variableName A named value defined in a Variables step, for example, $fullName Variables

Working with strings

Concatenation with &

The & operator joins two strings together. Chain multiple & operators to combine more than two values:

$trigger.current.FirstName & ' ' & $trigger.current.LastName

Result: Jane Smith

'Initial needs assessment for: ' & $trigger.current.FirstName & ' ' & $trigger.current.LastName

Result: Initial needs assessment for: Jane Smith

Joining an array with $join

$join(array, separator) concatenates an array of strings into a single string, inserting the separator between each element.

$join([$trigger.current.MailingStreet, $trigger.current.MailingCity, $trigger.current.MailingState, $trigger.current.MailingPostalCode], ', ')

Result: 123 Main St, Springfield, IL, 62701

Other useful string functions

Function Description Example
$string(value) Converts a value to a string $string(42) → "42"
$trim(str) Removes leading and trailing whitespace $trim(' hello ') → "hello"
$uppercase(str) Converts to uppercase $uppercase('hello') → "HELLO"
$lowercase(str) Converts to lowercase $lowercase('HELLO') → "hello"
$substring(str, start, length) Extracts a portion of a string $substring('hello world', 0, 5) → "hello"
$substringBefore(str, chars) Returns the part of the string before the first occurrence of chars $substringBefore('hello@world.com', '@') → "hello"
$substringAfter(str, chars) Returns the part of the string after the first occurrence of chars $substringAfter('hello@world.com', '@') → "world.com"
$contains(str, pattern) Returns true if the string contains the pattern $contains('hello world', 'world') → true
$replace(str, pattern, replacement) Replaces occurrences of a pattern $replace('hello world', 'world', 'there') → "hello there"

Working with numbers

Standard arithmetic operators work as expected:

$trigger.current.Duration + 15

$trigger.current.Quantity * $trigger.current.UnitPrice
Function Description Example
$number(value) Converts a string or boolean to a number $number('42') → 42
$abs(number) Absolute value $abs(-5) → 5
$round(number, precision) Rounds to the given number of decimal places $round(3.456, 2) → 3.46
$floor(number) Rounds down to the nearest integer $floor(3.9) → 3
$ceil(number) Rounds up to the nearest integer $ceil(3.1) → 4
$formatNumber(number, picture) Formats a number as a string using a picture string $formatNumber(1234.5, '#,###.00') → "1,234.50"

Comparisons and logic

These expressions are most commonly used in Choice step conditions.

Comparison operators

Operator Meaning Example
= Equal to $trigger.current.Status = 'Active'
!= Not equal to $trigger.current.AccountId != null
< Less than $trigger.current.Duration < 60
> Greater than $trigger.current.Duration > 60
<= Less than or equal to $trigger.current.Duration <= 30
>= Greater than or equal to $trigger.current.Duration >= 30

Logical operators

Operator Meaning Example
and Both conditions must be true $trigger.current.Type = 'Break Fix' and $trigger.current.Priority = 'High'
or At least one condition must be true $trigger.current.Status = 'Queued' or $trigger.current.Status = 'Pending Dispatch'
not(expr) Negates the result not($trigger.current.Urgent)

Checking for null and existence 

$trigger.current.AccountId != null

$exists($trigger.current.Description)

Conditional (ternary) expressions

JSONata supports inline conditional expressions using the ? : syntax:

$trigger.current.Description != null ? $trigger.current.Description : 'No description provided'

Working with arrays

Step outputs that return multiple results are exposed as arrays. Use square bracket notation to access individual elements by index (zero-based):

$getJobsForResource.result.data.Jobs[0].Name
Function Description Example
$count(array) Returns the number of elements in an array $count($getJobsForResource.result.data.Jobs)
$sum(array) Returns the sum of all numbers in an array $sum([1, 2, 3]) → 6
$max(array) Returns the maximum value $max([1, 5, 3]) → 5
$min(array) Returns the minimum value $min([1, 5, 3]) → 1
$append(array1, array2) Combines two arrays $append([1, 2], [3, 4]) → [1, 2, 3, 4]

Working with dates and times

Function Description Example
$now() Returns the current date and time as an ISO 8601 string $now() → "2025-06-15T09:30:00.000Z"
$toMillis(timestamp) Converts an ISO 8601 timestamp to milliseconds since epoch $toMillis('2025-06-15T00:00:00Z')
$fromMillis(millis, picture) Converts milliseconds to a formatted date string $fromMillis($toMillis($now()), '[D] [MNn] [Y]') → "15 June 2025"

For example, to format a date field from a trigger record for display:

$fromMillis($toMillis($trigger.current.StartDate), '[D01] [MNn] [Y]')

See also