🔧 What Are Merge Fields?

Merge Fields (MF) are dynamic placeholders—template tags—that allow the insertion of live, contextual data into documents, emails, and other templates rendered by the ALX system. They are powered by the Jinja2 templating engine to provide greater flexibility and readability.

Merge Fields are resolved at render time and replaced with actual data pulled from records in the system (e.g., users, documents, tasks).

---

🔍 Basic Usage Example

{{ user.first_name }} {{ user.last_name }}
{{ document.title }}
{{ base64(document.content) }}

Merge Fields can also contain conditional logic or loops:

{% if user.is_admin %}
  Administrator: {{ user.email }}
{% endif %}

📦 Technical Foundation

Jinja2 Template Engine

Merge Fields in ALX are implemented using Jinja2, a fast and expressive templating engine for Python. It provides the syntax and context resolution needed to work with dynamic fields.

📚 Jinja2 Official Documentation

🎯 Purpose of Merge Fields in ALX

Merge Fields serve as a dynamic link between your data and rendered content in ALX. They are frequently used in:

1. Document generation - document templates
2. Email templates and system notifications
3. Sequencer Actors: API Call, Send Message, Variables, AI Actors
4. Web-based dynamic content views
5. Word Add-in plugin

Merge Fields allow you to write generic templates that adapt to the actual content of a record at runtime. Merge fields allow inserting Object Record data in document templates, API call actor parameters, emails, and other resources relevant to Object Records.

🧩 Overview of Supported Merge Field Types

The ALX system supports a wide range of Merge Fields. Detailed sections will follow, but broadly, MF types include:

• User merge fields – full user objects, user groups, active-only users
• Document merge fields – metadata and file contents
• Base64 merge fields – useful for embedding files in templates
• Record properties – access any custom field from a record
• System fields – like current date, time, or logged-in user
• Related records – for accessing nested relationships
• Loop Item – for accessing items from Loop actor

⚙️ System Merge Fields

System merge fields are global system variables that are available in every context regardless of the currently processed object (record, user, etc.). They are not tied to any specific object and contain information about the system, environment, and execution context. The system merge fields are organized into four main categories:

👤 Admin Context

Admin-related merge fields provide information about the system administrator:

📌 Example usage

{{ admin_first_name }} 
{{ admin_last_name }} 
{{ admin_email_address }} 
{{ admin_phone_number }} 
{{ admin_job_title }} 
{{ admin_email_signature }}

🏢 Client Context

Client-related merge fields provide information about the current client:

{{ client_name }} 
{{ client_url }}

📅 Date and Time Context

Date and time merge fields provide current temporal information:

{{ current_date }} 
{{ current_datetime }}

🔧 Constants Context

Constants are user-defined values available throughout the system with special prefix constants:

{{ constants.API_BASE_URL }} 
{{ constants.COMPANY_NAME }} 
{{ constants.SUPPORT_EMAIL }}

🔄 Loop Item Context

The loop_item merge field is a dynamic reference to the currently processed item within a Loop actor. Loop Item is user-defined value available throughout the system with special prefix loop_item:

{{ loop_item }} 
{{ loop_item.name }} 
{{ loop_item.key1.key2 }}

⚙️ Usage Contexts

System merge fields work in all places where merge fields are supported:

• Document templates
• Email templates
• Sequencer (all actors)
• API responses
• Workflow notifications
• Custom scripts

📋 Complete Usage Example

Template:

Dear {{ client_name }},
This email was sent by {{ admin_first_name }} {{ admin_last_name }} on {{ current_date }} from {{ client_url }}.
API endpoint: {{ constants.API_BASE_URL }}/users
Best regards, {{ admin_email_signature }}

Output:

Dear Acme Corporation,
This email was sent by Joe Doe on 2020-02-05 from [http://client.testserve](http://client.testserve).
API endpoint: https://api.example.com/users
Best regards, Signature

Global Availability

🌐 All system merge fields are globally available and don't require any specific object context to function.

Constants Prefix

⚠️ Constants merge fields require the constants. prefix, while other system merge fields can be used directly without prefixes.

🧾 Summary

Merge Fields are a core part of dynamic content generation in ALX. Backed by Jinja2, they allow templates to remain generic and adaptable while still outputting rich, data-driven content. Understanding how they work is essential to building powerful document templates and user-facing messages.

📘 What's Next?

A specific and powerful category of merge fields relates to Object Records—these include field references, nested relationships, and dynamic access to custom properties.

🧭 These will be covered in detail in the Object Record Merge Fields, where we explain how to access and format data from related records, such as linked users, documents, or custom model instances.