Placeholder Reference

How placeholders work in email templates and what every workflow placeholder means.

Table of Contents

1. What a placeholder is
2. Two kinds of placeholders
3. Placeholder syntax
4. Placeholder definition fields
5. Data types
6. Allowed filters
7. Missing values, defaults, and required placeholders
8. Document placeholders (document.*)
9. Workflow placeholders (workflow.*)
10. Runtime notification placeholders
11. How workflow notifications receive values
12. Examples
13. A note on testing

What a placeholder is

A placeholder is a named value that is filled in when the email is rendered. In the template it looks like:

Hello {{ recipient_name }}, your request {{ document.number }} is ready.

At send time, the system replaces each token with the real value. Placeholders let one template serve many records and recipients.

Two kinds of placeholders

Workflow placeholders are not magic tokens that bypass validation. In Email Studio, every token must be declared. When you click a workflow field in the Data source panel, the designer inserts the token and declares it for you. If you type {{ workflow.approvers }} manually, you must also add a placeholder definition named workflow.approvers.

Placeholder syntax

Placeholder definition fields

Each declared placeholder has these attributes.

Data types

Use url for links. A plain text value containing a URL is not validated as a URL, and a URL placeholder is validated after rendering to prevent unsafe schemes.

Allowed filters

Filters are optional and are written with a pipe: {{ name|lower }}. Only these filters are allowed:

Any other filter is rejected at validation time.

Missing values, defaults, and required placeholders

The renderer follows these rules:

Warnings do not block sending. Errors do.

Document placeholders (document.*)

document.* placeholders read fields from the business document attached to the workflow, such as an invoice, purchase order, or request.

Single fields

{{ document.number }}
{{ document.status }}
{{ document.due_date }}

Any concrete field on the workflow's document model can be used, with these exclusions:

• Sensitive or account fields: password, is_superuser, is_staff, groups, user_permissions, last_login, date_joined.
• Binary, file, and image fields are not exposed.

Related fields

When the workflow configuration declares relationships, you can read a field on a related record:

{{ document.vendor.name }}
{{ document.customer.email }}

document.<relation>.<field> supports the relations configured for that workflow. Relations to the framework user model, Django groups, and Django permissions are excluded from automatic discovery.

Formatting behavior

• Choice fields render their human-readable label, not the stored value.
• Booleans render Yes or No.
• Dates and datetimes render using the project's date formats, or the placeholder's format string.
• Many-to-many values render as a comma-separated list.
• Missing or unset values render as an empty string.

document_label

{{ document_label }} is the display name of the whole document, for example the formatted record title. Use it in a sentence such as "Regarding {{ document_label }}…".

Workflow placeholders (workflow.*)

These values describe the workflow itself. The designer offers:

• The core catalog below, always available for a workflow data source.
• Additional context fields built from the live workflow instance.
• Document fields from the selected workflow's document model.

Core workflow catalog

Additional workflow context fields

These are produced from the workflow instance and are offered by the workflow data source.

On an approval request, the email channel sets workflow.approvers and workflow.work_item_owner to the recipient of that specific message, so the email addresses the person being asked to act.

Workflow aliases at a glance

Several names point at the same underlying value. Use whichever reads best in the email.

Runtime notification placeholders

These top-level values are supplied when a notification is sent. They are available as data-source fields for workflow templates and can be declared on the template.

Notification types

These are the standard notification types a workflow can send:

submission, approval_request, approval_request_originator, approval_approved, rejection, changes_requested, completion, state_assignment, join_ready, state_completion, reassignment, delegation_expired.

Use {{ notification_type }} when one template serves several notification types, for example to vary wording.

How workflow notifications receive values

When a workflow sends an email:

1. The workflow resolves the template code for the notification type from the step, the workflow template map, or the settings fallback.
2. Enezaframework builds the email context from the live workflow instance and current step. It includes the workflow.* object, the document.* values, and the runtime top-level values.
3. The email channel adds recipient details (recipient_name, recipient_email), the notification title and message, and a fallback action_url.
4. The active published version is rendered with that context, placeholders are validated and coerced, and the email is queued.
5. If a declaration expects a name the workflow does not supply, the send fails validation. The workflow designer warns about this when you map the template, but preview and test send are the reliable checks.

If no email template is selected for a workflow notification, the email channel is skipped and the delivery is logged as failed with No email template selected.

Placeholder resolution in notification text

The workflow's in-app notification text uses a separate lightweight renderer. It resolves:

• workflow.* tokens from the current workflow and step.
• document.* tokens for single fields and one related level.
• Unknown tokens are left unchanged rather than blanked.

Email templates use the full template engine described on this page: every token must be declared, and undeclared tokens are validation errors.

Examples

Approval request

Subject: Approval needed for {{ document.number }}

Hello {{ recipient_name }},

{{ workflow.workflow_originator }} submitted {{ document_label }}
for your approval at the {{ workflow.current_step }} step.

Current status: {{ workflow.status }}
Last note: {{ workflow.last_note }}

Review the item: {{ workflow.link_to_web }}

Rejection notice

Subject: {{ document_label }} was rejected

Hello {{ workflow.workflow_originator }},

Your request was rejected by {{ workflow.last_action_user }}.
Reason: {{ reason }}

Open the record: {{ action_url }}

Generic notification

Subject: {{ notification_title }}

Hello {{ recipient_name }},

{{ notification_message }}

Open the item: {{ action_url }}

Regards,
{{ company_name }}

For the generic example, declare notification_title, notification_message, recipient_name, action_url, and company_name (all text, except action_url as url).

A note on testing

Per project rules, the developer or agent does not run or claim test results. The user is solely responsible for all testing and validation of the output described in this guide.

Related guides

• Creating and Publishing an Email Template
• Email Templates — User & Admin Guide
• Workflow — Developer Index