Expressions and filters

Ingestly templates pull data from earlier nodes into the configuration of later ones. Wherever you see a field that accepts {{ ... }} (callback URL, HTTP body, email subject, transform output, validation rule), you can reference an upstream value, index into arrays, transform it with filters, or insert a built-in helper.

Basic syntax

A template expression has three parts: a path, optional filters, and the surrounding {{ }} markers.

{{ path | filter | filter }}

The path locates the value. Filters transform it left to right. The result replaces the whole {{ ... }} token.

Path

A path is a dotted identifier, optionally with array indices.

Form	What it resolves to
`{{nodeName}}`	The full output of the named upstream node, as JSON
`{{nodeName.payload.field}}`	A field inside that node’s output
`{{nodeName.payload.items[0].sku}}`	The first element of an array, then a field inside it
`{{nodeName.payload.items[-1]}}`	The last element of an array (negative index counts from the end)

The first segment of every path must be the name of an upstream node (or a built-in placeholder or helper, see below). Subsequent segments index into that node’s output, which has the shape { success, payload, metadata, error }. Paths are case sensitive and may use letters, digits, and underscores.

Each node in the editor has a Name field. Default names are auto-assigned (extract, extract2, vars, etc.) but you can rename a node to anything that’s unique within the pipeline. Whatever name you pick is the identifier used at the head of every template expression.

Built-in placeholders

These resolve from the run context:

Placeholder	Value
`{{documentId}}`	The current document’s ID
`{{organizationId}}`	The owning organization’s ID
`{{pipelineId}}`	The current pipeline’s ID
`{{nodeId}}`	The current node’s ID

Source document file

The $document head resolves from the run’s source document: the original file that triggered the run, whether it was uploaded or emailed. It is a global head, valid in any template field, because a pipeline can have several triggers but only one fires per run.

Path	Value
`{{$document.file.name}}`	The original file name (falls back to `document` plus the extension)
`{{$document.file.contentType}}`	The MIME content type, for example `application/pdf`
`{{$document.file.size}}`	The file size in bytes
`{{$document.file.extension}}`	The file extension, including the leading dot, for example `.pdf`
`{{$document.file.base64}}`	The raw file bytes, Base64-encoded

The metadata paths (name, contentType, size, extension) are always cheap to resolve. base64 is different: the file bytes are fetched and encoded lazily, only when a template actually references {{$document.file.base64}}, and they are never persisted. The encoded value never enters run output, step history, or the live preview. Anywhere it would otherwise appear, Ingestly shows a [binary N bytes, type] placeholder instead. Use {{$document.file.base64}} to send the source file as a binary body on a callback or HTTP node, or to attach it to a record.

A node name can never start with $, so the $document head never collides with a node you have named document.

Built-in helpers

These produce a value at the time the template is evaluated.

Helper	Returns
`{{now}}`	Current UTC datetime as ISO 8601 (`yyyy-MM-ddTHH:mm:ssZ`)
`{{today}}`	Current UTC date (`yyyy-MM-dd`)
`{{nowUnix}}`	Current Unix epoch seconds
`{{uuid}}`	A new UUID v7 (time-ordered)

You can chain filters onto helpers: {{now | formatDate: 'yyyy-MM-dd'}}.

Filters

Add a filter with the pipe character: {{ value | filter }}. Filters with arguments use a colon: {{ value | filter: 'arg1', 'arg2' }}. You can chain as many filters as you need, applied left to right.

Filter arguments

Each argument is one of:

Form	Example	Notes
Number literal	`{{count \| add: 5}}`	`-3.14`, `1e6`, etc.
Quoted string	`{{name \| concat: '!'}}`	Single or double quotes
`true`, `false`, `null`	`{{value \| default: null}}`	Bare keywords
Path reference	`{{payload.terms \| div: payload.divisor}}`	Resolved against the same upstream context as the head expression

Path references must satisfy the same shape as the head path (identifier(.identifier|[N])*). The runtime resolves them at filter-application time, so they can reference upstream node fields (extract.payload.divisor), built-in helpers ({{end | dateDiff: 'days', start}}), or array elements ({{items[0] | concat: items[1]}}). If the path resolves to a type that doesn’t match what the filter expects (e.g., div argument resolves to a string), the editor flags it before the run starts.

String filters

Filter	Example	Result
`upper`	`{{name \| upper}}`	`ALICE`
`lower`	`{{name \| lower}}`	`alice`
`trim`	`{{ ' alice ' \| trim}}`	`alice`
`replace: 'from', 'to'`	`{{name \| replace: 'a', '@'}}`	`@lice`
`substring: start, length?`	`{{name \| substring: 0, 3}}`	`Ali`
`truncate: maxLength, postfix?`	`{{title \| truncate: 8, '...'}}`	`Invoi...`
`split: separator`	`{{tags \| split: ','}}`	`["a","b","c"]`
`concat: 'suffix'`	`{{name \| concat: '!'}}`	`Alice!`
`contains: 'needle'`	`{{name \| contains: 'lic'}}`	`true`
`startsWith: 'prefix'`	`{{name \| startsWith: 'Al'}}`	`true`
`endsWith: 'suffix'`	`{{name \| endsWith: 'ce'}}`	`true`
`padStart: length, pad?`	`{{code \| padStart: 5, '0'}}`	`00042`
`padEnd: length, pad?`	`{{code \| padEnd: 5, '0'}}`	`42000`
`capitalize`	`{{name \| capitalize}}`	`Alice`
`camelCase`	`{{'order id' \| camelCase}}`	`orderId`
`kebabCase`	`{{'Order Id' \| kebabCase}}`	`order-id`
`snakeCase`	`{{'Order Id' \| snakeCase}}`	`order_id`

truncate counts the postfix toward the limit; padStart and padEnd pad with a space when no pad string is given.

Number filters

Filter	Example	Result
`round: digits?`	`{{3.14159 \| round: 2}}`	`3.14`
`ceil`	`{{3.2 \| ceil}}`	`4`
`floor`	`{{3.8 \| floor}}`	`3`
`abs`	`{{-5 \| abs}}`	`5`
`add: n`	`{{5 \| add: 3}}`	`8`
`sub: n`	`{{5 \| sub: 3}}`	`2`
`mul: n`	`{{5 \| mul: 3}}`	`15`
`div: n`	`{{6 \| div: 3}}`	`2`

Format filters

Turn a raw number into a display string.

Filter	Example	Result
`formatNumber: decimals, culture?`	`{{amount \| formatNumber: 2}}`	`1,234.50`
`formatCurrency: 'code', decimals?, culture?`	`{{amount \| formatCurrency: 'USD'}}`	`$1,234.50`

formatCurrency takes an ISO 4217 currency code (for example USD, EUR, GBP) and pins the currency symbol from that code.

Array filters

Filter	Example
`length`	`{{items \| length}}`
`first`	`{{items \| first}}`
`last`	`{{items \| last}}`
`join: separator`	`{{tags \| join: ', '}}`
`sum`	`{{prices \| sum}}`
`avg`	`{{prices \| avg}}`
`min`	`{{prices \| min}}`
`max`	`{{prices \| max}}`
`unique`	`{{tags \| unique}}`
`sort`	`{{prices \| sort}}`
`reverse`	`{{items \| reverse}}`
`slice: start, end?`	`{{items \| slice: 0, 3}}`
`groupBy: 'key'`	`{{lineItems \| groupBy: 'category'}}`

slice uses Python-style bounds (negative indices count from the end). groupBy groups an array of objects by the string value at key, returning an array of { key, items } groups. reverse also reverses a string’s characters.

Date filters

Operate on ISO 8601 strings (or anything that can be parsed as one). The add/subtract and start/end filters return an ISO 8601 UTC string.

Filter	Example	Result
`formatDate: '...'`	`{{now \| formatDate: 'yyyy-MM-dd'}}`	`2026-04-28`
`addDays: n`	`{{today \| addDays: 7}}`	`2026-05-05T00:00:00Z`
`subDays: n`	`{{today \| subDays: 1}}`	`2026-04-27T00:00:00Z`
`addHours: n`	`{{now \| addHours: 6}}`	shifted ISO datetime
`addMinutes: n`	`{{now \| addMinutes: 90}}`	shifted ISO datetime
`addMonths: n`	`{{today \| addMonths: 1}}`	shifted ISO datetime
`addYears: n`	`{{today \| addYears: 1}}`	shifted ISO datetime
`startOfDay`	`{{now \| startOfDay}}`	`2026-04-28T00:00:00Z`
`endOfDay`	`{{now \| endOfDay}}`	`2026-04-28T23:59:59Z`
`startOfMonth`	`{{now \| startOfMonth}}`	first day of the month
`endOfMonth`	`{{now \| endOfMonth}}`	last day of the month
`dayOfWeek`	`{{now \| dayOfWeek}}`	`Tuesday`
`toUnix`	`{{now \| toUnix}}`	epoch seconds
`fromUnix`	`{{ts \| fromUnix}}`	ISO datetime
`toIso`	`{{rawDate \| toIso}}`	canonical ISO 8601 UTC
`dateDiff: unit, otherDate`	`{{end \| dateDiff: 'days', '{{start}}'}}`	`5`

formatDate uses .NET-style format strings. Common patterns: yyyy-MM-dd, yyyy-MM-ddTHH:mm:ssZ, MM/dd/yyyy, HH:mm. Negative arguments to the add* filters subtract.

Encoding filters

Filter	Example	Notes
`base64Encode`	`{{value \| base64Encode}}`	Base64-encode UTF-8 text
`base64Decode`	`{{value \| base64Decode}}`	Decode Base64 back to text
`urlEncode`	`{{value \| urlEncode}}`	Percent-encode for use in a URL
`urlDecode`	`{{value \| urlDecode}}`	Reverse percent-encoding

General filters

Filter	Example	Notes
`default: 'fallback'`	`{{maybeMissing \| default: 'n/a'}}`	Substitutes when the value is null or empty
`coalesce: fallback, ...`	`{{primary \| coalesce: secondary, 'n/a'}}`	Returns the first argument (starting with the input) that is not null or empty. Takes any number of fallbacks
`json`	`{{payload \| json}}`	Stringify the value as JSON
`escape`	`{{name \| escape}}`	HTML-escape a string

Array constructs

Beyond the filters above, four constructs transform arrays and pick branches. They use the same | syntax but are written by name.

Construct	Syntax	What it does
`map`	`{{items \| map: field=value, ...}}`	Project each array element into a new object. Use `$` for the current element and `$.field` for a field of it
`filter`	`{{items \| filter: $.qty > 0}}`	Keep only the elements matching a condition. `$` is the current element
`select`	`{{items \| select: $.sku}}`	Pull one field from every element into a flat array
`if`	`{{value \| if: "$ > 100", 'high', 'low'}}`	Inline conditional. The condition is a quoted string; the else branch is optional and passes the input through when omitted

{{extract.payload.lines | map: sku=$.sku, qty=$.quantity}}
{{extract.payload.lines | filter: $.amount > 0 | select: $.sku}}

Live preview

When you edit a template field in a node editor, Ingestly shows a live preview of the resolved value. Select a document from the run toolbar so the preview evaluates against that document’s most recent run data. This lets you confirm a path and its filter chain produce the value you expect before you run the pipeline. Without a selected document, the editor still validates the path and filter names but cannot show a resolved value.

Type-aware autocomplete

When you type inside a {{ ... }} field in a node editor, Ingestly suggests:

Upstream node fields at the start of the expression (after {{)
Built-in helpers (now, today, uuid, nowUnix) alongside fields
Filters after a |, scoped to the type of the preceding value (an array path shows length, first, join; a string path shows upper, lower, trim)
Filter arguments as snippet placeholders you can tab through

Unknown filter names render with a red squiggle and surface as a validation error on the node.

Inside JSON bodies

When you write a template inside a JSON value position, like "qty": "{{payload.qty}}", Ingestly emits the resolved value as raw JSON so types are preserved. A number stays unquoted, an object stays structured, an array stays an array.

{
  "amount": "{{payload.amount | round: 2}}",
  "lines": "{{payload.lineItems}}"
}

After substitution the request body becomes:

{
  "amount": 3.14,
  "lines": [{ "sku": "A1", "qty": 2 }]
}

This applies to the HTTP action and callback output body fields when they parse as JSON. Outside JSON value positions (URLs, email subjects, plain-text fields), templates substitute as plain strings.

Filter arguments inside a JSON-position template should use single quotes ('a') rather than double quotes, to avoid clashing with the surrounding JSON string.

Row expansion in JSON bodies ( $each and$ when)

A JSON body can fan out over a runtime array. Inside any JSON array, an object that carries a $each key is a row template: it is repeated once per element of the referenced array, and the $each key itself is removed from the output.

{
  "orderNumber": "{{transform1.payload.po_number}}",
  "salesOrderLines": [
    {
      "$each": "{{payload.lines}}",
      "lineObjectNumber": "{{item.mark}}",
      "quantity": "{{item.quantity}}"
    }
  ]
}

Inside a row template:

{{item}} is the current array element, and {{item.field}} reads a field from it
{{index}} is the zero-based position
Values that are exactly one {{item...}} or {{index}} token keep their type (a number stays a number, an object stays structured)
Tokens that mix text and bindings, like "row {{index}}: {{item.mark}}", substitute as text
Other {{node.path}} tokens are left for normal substitution

Add a $when key to filter rows. The condition supports ==, !=, a bare truthiness test, and ! for negation:

"salesOrderLines": [
  {
    "$each": "{{payload.lines}}",
    "$when": "!{{item.__label}}",
    "lineObjectNumber": "{{item.mark}}",
    "quantity": "{{item.quantity}}"
  },
  {
    "$each": "{{payload.lines}}",
    "$when": "{{item.__label}} == 'surcharge'",
    "description": "{{item.description}}",
    "unitPrice": "{{item.total}}"
  }
]

Several row templates in one array concatenate in order, which routes rows to different shapes: here regular lines (no __label) become item lines and reconcile-classified surcharge rows become a different line shape. A reconcile node stamps classified extra rows with __label, so this pairs naturally with Expected extras. An object with only $when (no $each) is included or dropped as a whole. Row templates nest: a field inside a row can hold another array with its own $each over {{item.subArray}}, and the inner template’s item refers to the inner element. Row expansion applies to the HTTP action and callback body fields when they parse as JSON. A $each reference that does not resolve to an array contributes no rows.

Common recipes

Last item from an extracted line items array, with a fallback:

{{extract.payload.lineItems[-1].sku | default: 'no-sku'}}

Total of a numeric array, rounded:

{{extract.payload.amounts | sum | round: 2}}

Today’s date plus 30 days as a yyyy-MM-dd string:

{{today | addDays: 30 | formatDate: 'yyyy-MM-dd'}}

Stringified JSON of a structured value, for a plain-text field:

{{extract.metadata | json}}

Comma-joined tags, uppercased:

{{extract.payload.tags | join: ', ' | upper}}

When a template doesn’t resolve

If the path can’t be resolved (the field is missing, the upstream node didn’t run, the index is out of bounds), Ingestly substitutes an empty string. Use default: '...' to provide a fallback. If the filter name is unknown or a filter call is malformed (wrong arg count, bad argument type), the substitution yields an empty string and the node surfaces a validation error.

Getting started

Learn

Guides

Reference

Administration

Expressions and filters

Basic syntax

Path

Built-in placeholders

Source document file

Built-in helpers

Filters

Filter arguments

String filters

Number filters

Format filters

Array filters

Date filters

Encoding filters

General filters

Array constructs

Live preview

Type-aware autocomplete

Inside JSON bodies

Row expansion in JSON bodies ( $each and$ when)

Common recipes

When a template doesn’t resolve

​Basic syntax

​Path

​Built-in placeholders

​Source document file

​Built-in helpers

​Filters

​Filter arguments

​String filters

​Number filters

​Format filters

​Array filters

​Date filters

​Encoding filters

​General filters

​Array constructs

​Live preview

​Type-aware autocomplete

​Inside JSON bodies

​Row expansion in JSON bodies (eachandeach and eachandwhen)

​Common recipes

​When a template doesn’t resolve

Basic syntax

Path

Built-in placeholders

Source document file

Built-in helpers

Filters

Filter arguments

String filters

Number filters

Format filters

Array filters

Date filters

Encoding filters

General filters

Array constructs

Live preview

Type-aware autocomplete

Inside JSON bodies

Row expansion in JSON bodies ( $each and$ when)

Common recipes

When a template doesn’t resolve