# JSONata expressions

> Source: https://docs.clonepartner.com/reference/jsonata/

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

## Task context

Task expressions can read:

```text
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:

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

Use a block string when values depend on runtime context:

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

## Conditions

```yaml
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:

```jsonata
$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:

```jsonata
{ "_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:

```jsonata
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:

```jsonata
{
  "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](/reference/masking-loops-and-error-handling) and [Author a production task](/guides/task-authoring).