Expressions

Expressions

Expressions connect a template to its data contract. Use them to insert values into text, format dates and numbers, show or hide blocks, repeat content, or calculate a value. Epistola uses JSONata for expressions.

Insert a field

Use a field when part of the document should come from the case or another input source.

1. Open a text block and place the cursor where the value should appear.
2. Type {{ or use the expression control to open the expression builder.
3. Choose a field from the template’s expected information.
4. Save the expression and preview it with an example.

For example, a greeting can combine fixed text and a field:

Dear {{customer.name}},

The field is stored as an expression chip, so its value changes when you select another data example.

Format values

Use the locale-aware formatters when the output should follow the document’s language or region.

Dates and times

Use $formatDate(value, pattern) with an ISO date or datetime:

$formatDate(invoiceDate, "dd-MM-yyyy")
$formatDate(createdAt, "EEEE d MMMM yyyy")
$formatDate(createdAt, "dd-MM-yyyy HH:mm")

Numeric tokens such as dd, MM, and yyyy follow the pattern exactly. Month and weekday names such as MMMM and EEEE are localized. The format builder offers common date and datetime patterns.

Numbers and percentages

Use $formatLocaleNumber(value, picture) for locale-aware number output:

$formatLocaleNumber(amount, "#,##0.00")
$formatLocaleNumber(rate, "0.0%")

The same picture uses 1.234,56 in nl-NL and 1,234.56 in en-US. The effective locale comes from the variant, tenant, or application default.

There is no separate currency formatter. Add the currency symbol as literal text around the localized number:

"€ " & $formatLocaleNumber(amount, "#,##0.00")

The built-in $formatNumber() is locale-agnostic. Prefer $formatLocaleNumber() for documents that must follow a regional number format. Common number and percentage presets are available in Builder mode; use Code mode for custom pictures.

Show content conditionally

Use a Conditional block when content should appear only for some cases. Its child blocks are rendered when the condition evaluates to true. For example:

decision = "refused"

You can place an explanatory paragraph inside the Conditional block and preview both sides of the rule by switching the selected data example.

Repeat data

Use a Loop to repeat arbitrary child blocks for every item in an array. Inside the repeated content, refer to the current item through its item variable, such as:

item.name

Use a Data List when the result should be a list. It can render bullets, numbers, letters, Roman numerals, or no marker. Configure one item template; Epistola repeats it for every array item.

Preview with multiple examples

Switch between the template’s examples while editing and check:

• A populated field and an empty or optional field.
• Both the true and false result of a condition.
• A short and a long array for loops and data lists.
• Date, number, and percentage output in the intended locale.
• Long names, addresses, and paragraphs that may change page breaks.

The expression builder provides a live preview for the selected example. Use Code mode when a custom JSONata expression or formatting picture is not available as a Builder preset.

Keep expressions maintainable

Use direct field paths for simple values and expressions for presentation logic. Keep business decisions in the case or workflow system and send the resulting value to Epistola. If a rule is difficult for a document owner to explain or test, simplify it or move the decision upstream.