JSONata expressions

Envoy uses JSONata for dynamic task configuration, transforms, conditions, dashboard derivation, and selected connector arguments.

Task context

Task expressions can read:

input
arguments
variables
job_config
steps.<step_name>.output
steps.<step_name>.error

input changes as the item moves through the pipeline. Capture an earlier value through steps.<name>.output when a connector call replaces it.

Static object or expression

Use YAML for static configuration:

config:
  connector: source
  method: count
  args:
    table: tickets

Use a block string when values depend on runtime context:

config: |
  {
    "connector": "destination",
    "method": "upsert",
    "args": {
      "table": variables.table,
      "data": {
        "id": $string(input.id),
        "email": $lowercase(input.email)
      }
    }
  }

Conditions

run_if: "arguments.dry_run = false"
skip_if: "$not($exists(input.email))"

JSONata equality is =, not JavaScript == or ===.

Use $exists() when a missing value differs from false, 0, or an empty string.

Common Envoy functions

$callMethod()

Calls a connector from within an expression. Use it only for a bounded lookup or aggregate:

$callMethod("mapping_db", "find_one", {
  "table": "contact_map",
  "where": { "source_id": input.id }
})

It collects the method result. Use a call_method step for a pageable collection.

$oid()

Constructs a MongoDB ObjectId from a valid string for typed filters:

{ "_id": $oid(arguments.record_id) }

Validate user input before conversion.

$hash()

Produces a deterministic hash for a normalized value. Keep field selection and normalization identical across tasks.

$mask()

Masks sensitive values for debugging or display. Masking output does not make it appropriate to store secrets in task YAML or logs.

Objects and arrays

A transform returning an array emits each element as a downstream item. Wrap an array when it must remain one value according to the receiving step's schema.

JSONata object grouping syntax is useful for converting field-mapping rows:

job_config.ticket_fields{
  source_field: {
    "field": target_field,
    "transform": transform
  }
}

Dates, IDs, and numbers

• Convert external IDs with $string() before storing mapping keys.
• Preserve numeric precision required by the destination.
• Normalize dates to one documented ISO representation.
• Do not compare a MongoDB ObjectId to a plain string.
• Sort arrays before hashing when source ordering is not meaningful.

Missing values

JSONata distinguishes missing from null. Explicitly default fields when downstream schemas require them:

{
  "name": input.name ? input.name : "Unknown",
  "phone": $exists(input.phone) ? input.phone : null
}

Error and safety guidance

• Avoid unbounded connector calls inside expressions.
• Keep write calls in explicit steps.
• Do not interpolate secrets into errors.
• Test expressions against missing, null, empty, and malformed fields.
• Use static allowlists for dynamic field or method choices.
• Keep complex expressions in a named transform step so their output is inspectable.

See Masking, loops, and error handling and Author a production task.