Document-template expression context

Start with the record context

When KayanOS renders a managed document template for an entity record, it supplies: KayanOS managed document-template settings with a record-based filename expression and caller-permissions mode.

KayanOS managed document-template settings with a record-based filename expression and caller-permissions mode.

Root	Meaning
`$record`	Flattened current entity record.
`$inverseRelations`	Configured inverse-relation records, grouped by entity and field.
`$organization`	Organization object with `id`.
`$member`	Calling member object with `id`.
`$now`	ISO timestamp captured for this render context.

`Acknowledgement {{ $record.request_id }} — {{ $record.status || "received" }}`

Use $record, not the entity-rule $ root. An interpolation that resolves to null or undefined becomes blank, so add a reviewed fallback in public or official documents.

Stable time and formatting

Use $now when every part of a document must show the same captured timestamp. now() is also available as a function, but it is evaluated by the renderer and can differ slightly between expressions.

dateFormat($now, "YYYY-MM-DD")

Document templates share the general helper catalog, including date, text, list, comparison, project, and planning helpers. They do not inherit shared-only legacy aliases or form-only functions. See Expression language syntax and the individual helper availability notes.

Controlled record lookups

The template-only getRecords function accepts one object argument:

getRecords({
  entityKey: "service_requests",
  filters: [["status", "eq", "approved"]],
  limit: 20,
  sorting: [{ field: "created", direction: "desc" }]
})

Supported object properties are entityKey, optional q, filters, limit, sorting, and search. A sorting value is an array of objects, each with field and direction: "asc" | "desc"; it is not an object keyed by field name. Each call clamps limit to a value between 1 and 500. Keep a lookup narrow, select only the data needed for the document, and make an empty result understandable.

getRecords({
  entityKey: "service_requests",
  filters: [["applicant_id", "eq", $record.applicant_id]],
  limit: 5
})

Caller and admin execution modes

In caller mode, the lookup is evaluated as the calling member. In admin mode, it uses an administrative execution identity. This is a material data-governance decision, not a formatting preference. An administrative lookup is restricted only when its allowed-entity list is non-empty. An omitted or empty list is not deny-all: it permits lookup against every entity in the organization that the administrative execution identity can read. Do not select admin mode until the service owner has reviewed that broader boundary. When admin mode is necessary, add a short, approved non-empty list of entity keys and treat any later change to it as an access change. Before publishing a template that uses getRecords:

Choose caller mode unless the service owner has approved a narrower administrative need.
In admin mode, configure a non-empty allowed-entity list as tightly as possible; do not leave it blank expecting a restriction.
Test with a member who should see the least amount of data, then test an entity outside the non-empty list and confirm that lookup is refused.
Check the rendered document for unintended personal, financial, or operational data.
Keep an empty lookup from producing a misleading statement.

The renderer has a 500-row cap per lookup call, a 10,000 total loop-iteration limit, a 20-level nesting limit, a five-level subtemplate limit, and a 15-second render timeout. Do not assume a separate aggregate lookup-row limit that is not part of the public contract. Configured inverse relations are suitable for a small related-record section. A document-template loop belongs in the document tag syntax, while its expression supplies the collection. The renderer currently exposes $relations as an empty reserved object, so do not use it as a direct-relation data contract. Put a directly needed value on the record where appropriate, use a configured inverse relation, or use a reviewed getRecords lookup.

$inverseRelations.inspections.request_id

Use a relation only after confirming the entity/field grouping that the template context exposes. An unconfigured inverse relation is not a reliable signal that no related records exist.

Filename expressions

Filename expressions use the same document-template expression context. Keep filenames stable, readable, and free of sensitive values that do not need to appear in a download name.

$record.request_id + "-acknowledgement"

The output type appends the document extension as required. Do not embed a path, access token, national identifier, or free-form private note in a filename.

Test a template as a record, not a paragraph

Test	Expected outcome
Complete record	Every intended tag resolves with the correct format.
Missing optional value	A reviewed fallback or an intentional blank is shown.
Empty relation/list	The document remains truthful and readable.
Caller mode	The template does not expose data beyond that member’s service purpose.
Admin mode—restricted list	A lookup for an entity outside the non-empty approved list is refused.
Admin mode—empty list	The reviewer recognizes that an empty/missing list is broad administrative access, not a restriction.
Large but valid data	Loop, nesting, output size, and timeout limits are respected.

Expression language

Expression helper reference

Practical reference

Document-template expression context

Start with the record context

Stable time and formatting

Controlled record lookups

Caller and admin execution modes

Filename expressions

Test a template as a record, not a paragraph

​Start with the record context

​Stable time and formatting

​Controlled record lookups

​Caller and admin execution modes

​Related data and loops

​Filename expressions

​Test a template as a record, not a paragraph

​Related guides

Start with the record context

Stable time and formatting

Controlled record lookups

Caller and admin execution modes

Related data and loops

Filename expressions

Test a template as a record, not a paragraph

Related guides