BlueprintEnvelope

Unique identifier for this document within the envelope.

Human-readable label for this document, shown in Studio and audit trails.

Reference to an uploaded file. Two distinct uses:

• With a template: overrides the underlying PDF that the template would otherwise pull from its contentKey/contentVersion asset. The template's fields and roles still apply — useful when the same template structure should be applied to a different source file (per-tenant branding, customer-specific paper).
• Without a template: the file is rendered as-is, with no template engine. Use for static documents that don't need fields or signature placements declared.

At least one of templateKey or fileId must be set. Prefixed lowercase ULID, e.g. f_01jv8m7qfj6xj9gkz7a4s2h8e.

Optional JSONata expression evaluated at render time. If it returns false, this document is skipped. When combined with iterator, the expression is evaluated per-instance with __iterator__ in scope (e.g. __iterator__.current.required).

Wires this document's underlying template inputs to the blueprint's inputs. Templates declare their own inputs (the data they need to render); blueprint inputs are what the caller supplies. Each entry says "feed blueprintInputKey from the running blueprint into templateInputKey on this template."

Auto-matching fallback: if inputMap is omitted, the renderer matches by key — any blueprint input whose key equals a template input key is passed through automatically. Set inputMap only when the keys differ (e.g. blueprint input candidate feeding template input signer) or when you want to be explicit.

Materializes this document once per array element, instead of once total. The value is a JSONata expression evaluated against the merged entity context — every blueprint input is exposed as a top-level key ($.team.members, $.position.supplements).

Coercion: the result is coerced to an array. null → [] (zero instances). A single value → [value] (one instance). An array passes through.

Per-instance context: inside each iteration, the engine injects __iterator__ into the JSONata scope:

• __iterator__.current — the array element for this iteration
• __iterator__.index — zero-based index
• __iterator__.total — total iterations

This is what lets includeIf and fileId (in expression form) vary per instance.

Document key suffixing: when the iterator produces more than one instance, the engine appends the index — nda becomes nda0, nda1, nda2. A single-instance result keeps the original key. Step assignments that target the document by its declared key ({ documentKey: "nda", roleKey: "signer" }) prefix-match all materialized instances — you don't enumerate the suffixed keys.

Per-instance vs shared fields:

• Per-instance: includeIf, fileId (when expressed via __iterator__)
• Shared across instances: templateKey, templateVersion, inputMap

Use for: one NDA per board member, one supplement per attached service line, one waiver per dependent. See the Generating Multiple Documents guide for full semantics and edge cases.

Key of the template that defines this document's fields, roles, and (by default) the underlying PDF. Required unless rendering directly from an uploaded file via fileId alone.

Version of the template to use. Pair with templateKey.