Every JSONata context root and Envoy helper function available in task expressions, with valid worked examples for each.

JSONata reference

Envoy evaluates JSONata expressions in task YAML: config strings on any step, the run_if and skip_if conditions, and the batch and spool properties. The transform and filter steps take a JSONata expression as their entire config. This page lists the context roots and helper functions those expressions can use; for a tutorial, see Working with JSONata.

Context roots

Every expression is evaluated with these roots in scope:

Root	Shape	Meaning
`input`	any	The current item — the output of the previous step.
`arguments`	object	Runtime arguments from the job template task node `arguments`, CLI `--arguments`, or the server API body.
`steps`	object	Previous step outputs, addressed as `steps.<stepName>.output`.
`variables`	object	Task variables declared in the task YAML, addressed as `variables.<varName>`.
`job_config`	object	Per-job runtime configuration from the job template's `job_config:` schema (or compatible dashboard input widgets). Snapshotted onto each run; `{}` for standalone runs.

One valid expression per root:

input.email

arguments.dry_run = false

steps.find_user.output.name

variables.table_name & "_staging"

$exists(job_config.ticket_field_map) ? job_config.ticket_field_map : []

input changes as the item moves through the pipeline: a call_method step's return value replaces it. Reach back to an earlier value through steps.<name>.output.

Helper functions

Envoy registers the functions below on top of the JSONata language. Standard JSONata built-ins ($string, $map, $filter, and the rest) are all available too — see jsonata.org for the language itself; they are not re-documented here. Expressions also run through @truto/truto-jsonata, which contributes its own extensions.

Connector access

Function	Arguments	Returns	Description
`$callMethod(config)`	`{ connector, method, ...args }` — flat, method args directly on the object	The method result; an async-iterable result is collected into an array	Call a Connector method from inside an expression. Use only for bounded single-record lookups (`find_one`, `count`); collection methods buffer entirely into memory.
`$destinationId(resource, sourceId)`	resource name, source ID string	The stored destination ID, or `null`	Mapping-store lookup shorthand. Available only when the task sets `lookup_connector` to a mapping-capable Connector slot.

Data and identity

Function	Arguments	Returns	Description
`$hash(obj, algorithm?)`	any value; `sha256` (default) or `md5`	hex digest string, or `null` for nullish input	Stable hash — object keys are sorted before hashing, so key order does not matter.
`$oid(value)`	24-character hex string or ObjectId-like value	BSON `ObjectId`	Build a MongoDB ObjectId for typed filters. Invalid input throws.
`$isNullish(value)`	any value	boolean	`true` for `null` and for missing values. Use instead of `= null`, which is `false` for missing keys.
`$fromJson(value)`	JSON string (non-strings pass through)	parsed value; `null` for unparseable strings or nullish input	Parse fields stored as JSON text, such as a raw column in SQLite.

Strings and text

Function	Arguments	Returns	Description
`$fixEmail(str, returnNullOnInvalid?)`	email string; optional boolean (default `false`)	repaired email string, or `null` when invalid and the flag is `true`	Normalize and repair a malformed email address.
`$stripInvisibleChars(str)`	string	string	Remove zero-width and other invisible characters.
`$mostSimilar(str, candidates, threshold?)`	string, string array, optional threshold (default `0.8`)	best-matching candidate, or `null`	Fuzzy match against a candidate list using Jaro–Winkler similarity.
`$adfToHtml(value)`	ADF object or JSON string of one	HTML string; non-ADF strings pass through unchanged; `null` for nullish or unconvertible input	Convert Atlassian Document Format to HTML. Safe to apply unconditionally.

Phone numbers

Function	Arguments	Returns	Description
`$parsePhone(str, region?)`	phone string, optional region (default `US`)	`{ country, nationalNumber, number, isValid }`, or `null`	Parse a phone number into its components.
`$isValidPhone(str, region?)`	phone string, optional region (default `US`)	boolean	Whether the string is a valid phone number.
`$formatPhoneE164(str, region?)`	phone string, optional region (default `US`)	E.164 string, or `null` when invalid	Format a valid phone number as E.164.

Files and multipart bodies

Function	Arguments	Returns	Description
`$formData(descriptor)`	`{ fields?: {...}, files?: [{ field?, filename?, content_type?, base64? or blob? }] }`	`FormData`	Build a multipart body. Not JSON-serializable — pass it straight into a `$callMethod` or `call_method` call in the same expression.
`$setBlobName(blob, filename)`	a `Blob` and a non-empty string	the same `Blob`	Set the filename on a Blob before uploading it.

PII masking

Masking is controlled by the task-level masking: block. When disabled (the default), every masking function returns its input unchanged, so the same task YAML is safe in production.

Function	Arguments	Returns	Description
`$mask(value, type?, options?)`	value; type `email`, `phone`, `name`, `text` (default), `id`, `number`, or `partial`; options object	deterministic redaction token (format depends on type)	Replace a PII value with a format-preserving token derived from the value and the masking seed. Nullish and empty values pass through.
`$maskEmail(value, options?)`	value; options such as `preserve_domain`	masked email	Shortcut for `$mask(value, 'email', options)`.
`$maskPhone(value)`	value	masked phone digits	Shortcut for the `phone` type.
`$maskName(value)`	value	masked name token	Shortcut for the `name` type.
`$maskText(value)`	value	masked text token	Shortcut for the `text` type.
`$maskingEnabled()`	—	boolean	Whether masking is enabled for this task.

Worked examples

A guard that skips a step when a value is missing or null — $isNullish catches both, where = null misses absent keys:

$isNullish(input.destination_id)

A bounded mapping lookup merged with the current item, keeping the original fields:

{
  "source_id": $string(input.id),
  "email": $fixEmail(input.email, true),
  "destination_id": $callMethod({
    "connector": "mapping_db",
    "method": "find_one",
    "table": "resource_mapping",
    "filter": { "resource": "contact", "source_id": $string(input.id) }
  }).destination_id
}

A multi-statement expression that builds a normalized payload with a change-detection hash — variable bindings need the parenthesized sequence form:

(
  $phone := $formatPhoneE164(input.telephone1);
  $payload := {
    "name": $trim(input.name),
    "email": $fixEmail(input.email, true),
    "phone": $isNullish($phone) ? null : $phone
  };
  $merge([$payload, { "content_hash": $hash($payload) }])
)

Working with JSONata — tutorial with patterns and footguns
transform — the step whose entire config is one expression
Task YAML schema — where expressions appear in a task definition