Understanding Merge Fields

Merge fields are expressions that reference data from entity records or system information. When Magentrix processes a merge field, it replaces the expression with the actual value from the referenced field. Merge fields enable dynamic content that automatically adapts to different users, records, and contexts without requiring manual customization for each scenario.

This guide explains merge field syntax, types, context rules, and relationship navigation to help administrators effectively use merge fields throughout the Magentrix platform.

What Are Merge Fields?

Think of merge fields as placeholders that Magentrix fills in with real data when needed. Just as mail merge in a word processor replaces placeholders with names and addresses from a mailing list, Magentrix merge fields replace expressions with actual field values from entity records.

Example Without Merge Fields: An email template with static text reads: "Hello, thank you for your interest. Please contact us at support@company.com for assistance."

Example With Merge Fields: An email template with merge fields reads: "Hello {!Contact.Firstname}, thank you for your interest in {!$Organization.Name}. Please contact us at {!$Organization.Email} for assistance."

When sent to John Smith, the email automatically becomes: "Hello John, thank you for your interest in Acme Corporation. Please contact us at support@acmecorp.com for assistance."

When sent to Sarah Johnson, the same template automatically becomes: "Hello Sarah, thank you for your interest in Acme Corporation. Please contact us at support@acmecorp.com for assistance."

This automatic personalization works for thousands of recipients using a single template.

Merge Field Syntax

All merge fields follow specific syntax rules:

Basic Structure

Merge fields are enclosed in curly braces with an exclamation point:

{!FieldReference}

The exclamation point immediately follows the opening curly brace with no space: {!

Syntax Components

• Curly Braces:{ } mark the beginning and end of the merge field
• Exclamation Point:! indicates this is a merge field expression
• Periods:. separate entity names, relationship names, and field names
• Dollar Sign:$ prefixes global system merge fields

Syntax Rules

• Merge fields must begin with {! and end with }
• No spaces appear between the opening brace and exclamation point
• Entity names, relationship names, and field names are case-sensitive
• Periods connect entity names to field names: Entity.Field
• Merge fields do not contain parentheses (that indicates a function)
• Merge fields do not contain commas (that indicates function arguments)

Two Types of Merge Fields

Magentrix supports two fundamentally different types of merge fields: Global System Merge Fields and Entity Instance Merge Fields. Understanding the difference is essential for using merge fields correctly.

Global System Merge Fields

Global System Merge Fields reference system-level information that is always available regardless of context. These merge fields always include a dollar sign ($) immediately after the exclamation point, identifying them as system-level references.

Format:{!$SystemCategory.Field}

Three Categories of Global System Merge Fields:

Current User Information: $User

$User merge fields reference the currently logged-in user's information. These merge fields access data from the User entity for whoever is viewing the content, receiving the email, or interacting with the system at that moment.

Common Examples:

Use Cases:

• Personalize portal pages: "Welcome back, {!$User.Firstname}!"
• Display user-specific information: "Your account manager: {!$User.Name}"
• Create user-specific links or parameters in URLs
• Filter content based on current user attributes
• Generate personalized reports or dashboards

Organization Information: $Organization

$Organization merge fields reference your organization's configuration and contact information as defined in Company Preferences.

Common Examples:

Use Cases:

• Include company contact information in email templates automatically
• Display organization branding and identity on portal pages
• Generate links to portal pages: {!$Organization.OrgURL}/portal
• Show organization-specific formatting (currency, dates, timezone)
• Create consistent footer content across communications

System Information: $SystemInfo

$SystemInfo merge fields return information about the current user's system state and device type. These merge fields return True or False values indicating specific conditions.

Common Examples:

Use Cases:

• Show different content based on user type (guest vs. authenticated)
• Provide mobile-optimized layouts for mobile users
• Display admin-only options to administrators
• Create conditional visibility based on authentication state
• Adjust interface complexity based on device type

Date and Time: $Today and $Now

Two special global merge fields provide current date and time information:

Use Cases:

• Display current date in email templates or page headers
• Calculate date differences using functions: "Days remaining: {!AddDateTimePart($Today,"days",30)}"
• Create time-sensitive conditional logic
• Generate timestamps for reports or exports

Entity Instance Merge Fields

Entity Instance Merge Fields reference data from specific entity records in the current context. Unlike global system merge fields that always reference the same system information, entity instance merge fields reference different record data depending on which record is being viewed, edited, or processed.

Format:{!EntityName.FieldName}

Example:{!Contact.Email} references the Email field of the Contact entity record in the current context.

Understanding Context

Context determines which entity record a merge field references. The context is defined by where the merge field is used:

Email Template Context: An email template configured to send to Contacts has Contact as its context. Merge fields in this template reference the Contact record receiving the email. If the template sends to 100 contacts, each email uses merge fields from the respective contact's record.

Page Layout Context: A page layout for the Account entity has Account as its context. Merge fields in visibility formulas or field formulas reference the Account record being viewed or edited.

Validation Rule Context: A validation rule on the Opportunity entity has Opportunity as its context. Merge fields in the validation formula reference the Opportunity record being saved.

Automation Context: An automation triggered by Lead creation has Lead as its context. Merge fields reference the Lead record that triggered the automation.

Full Syntax vs. Simplified Syntax

Entity instance merge fields can be written with or without the entity name, depending on context clarity:

Full Syntax (Always Valid):

{!Contact.Firstname} - Explicitly includes entity name

{!Account.Name} - Explicitly includes entity name

{!Opportunity.Amount} - Explicitly includes entity name

Simplified Syntax (Context Clear):

{!Firstname} - Entity name omitted when context is clear

{!Name} - Entity name omitted when context is clear

{!Amount} - Entity name omitted when context is clear

When You Can Omit Entity Names:

When the context clearly establishes which entity you are working with, you can omit the entity name from merge fields:

Example 1 - Email Template for Contacts:
Context: Email template configured for Contact entity
Full syntax: Dear {!Contact.Firstname} {!Contact.Lastname},
Simplified: Dear {!Firstname} {!Lastname},
Both work identically because context is Contact.

Example 2 - Validation Rule on Account:
Context: Validation rule on Account entity
Full syntax: {!IsNull(Account.BillingStreet)}
Simplified: {!IsNull(BillingStreet)}
Both work identically because context is Account.

Example 3 - Page Layout for Opportunity:
Context: Page layout section visibility on Opportunity entity
Full syntax: {!Equal(Opportunity.Stage,"Closed Won")}
Simplified: {!Equal(Stage,"Closed Won")}
Both work identically because context is Opportunity.

Navigating Relationships Through Lookup Fields

One of the most powerful capabilities of merge fields is the ability to navigate from one entity to related entities through lookup fields, accessing data from related records without requiring separate queries or manual lookups.

How Relationship Navigation Works

When an entity has a lookup field that creates a relationship to another entity, you can "traverse" that relationship in merge fields using dot notation to access fields from the related entity.

Example Relationship: Contact entity has a lookup field to Account entity. Each Contact can be associated with one Account.

Direct Field Access:
{!Contact.Firstname} - Accesses the Contact's first name
{!Contact.Email} - Accesses the Contact's email address

Related Entity Access:
{!Contact.Account.Name} - Accesses the related Account's name
{!Contact.Account.Phone} - Accesses the related Account's phone
{!Contact.Account.BillingCity} - Accesses the related Account's city

The merge field traverses the relationship from Contact to Account, then accesses the Account's field value.

Relationship Navigation Syntax

Standard Entity Relationships:

For standard entities, use the lookup field name without a suffix to navigate relationships:

{!Contact.Account.FieldName} - Navigate from Contact to Account
{!Opportunity.Account.FieldName} - Navigate from Opportunity to Account
{!Contact.CreatedBy.FieldName} - Navigate from Contact to User (CreatedBy)

Custom Entity Relationships:

For custom entities, relationship names end with _r to indicate a relationship navigation:

Example: Custom entity Project__c has a lookup field AccountId__c that references the Account entity.

• Field Name:AccountId__c (stores the Account ID)
• Relationship Name:AccountId_r (navigates to the related Account)

Usage:
{!Project__c.AccountId_r.Name} - Navigate from Project to Account and access Name
{!Project__c.AccountId_r.BillingCity} - Navigate from Project to Account and access BillingCity

The _r suffix signals that this is a relationship navigation, not a direct field reference.

Simplified Syntax for Relationships

When context is clear, you can omit the initial entity name even when navigating relationships:

Context: Email template for Contact entity

Full syntax: {!Contact.Account.Name}
Simplified: {!Account.Name}
Context makes it clear you're starting from Contact, so Contact can be omitted.

Context: Validation rule on Project__c custom entity

Full syntax: {!Project__c.AccountId_r.Name}
Simplified: {!AccountId_r.Name}
Context makes it clear you're starting from Project__c, so Project__c can be omitted.

Multi-Level Relationship Navigation

You can navigate multiple levels deep through relationship chains:

Example: Contact → Account → Owner (User)

{!Contact.Account.Owner.Name} - Navigate from Contact to Account to the Account Owner (User) and access the owner's name

Breakdown:

• Contact - Starting entity
• .Account - Navigate to related Account
• .Owner - Navigate to Account's Owner (a User)
• .Name - Access the User's name

Simplified When Context is Clear:
{!Account.Owner.Name} - If context is Contact, you can omit Contact

Common Relationship Patterns

Access Account Information from Contact:

• {!Contact.Account.Name} - Account name
• {!Contact.Account.Phone} - Account phone
• {!Contact.Account.Industry} - Account industry
• {!Contact.Account.BillingStreet} - Account billing address

Access Owner Information from Any Entity:

• {!Opportunity.Owner.Name} - Opportunity owner's name
• {!Opportunity.Owner.Email} - Opportunity owner's email
• {!CustomEntity__c.Owner.Name} - Custom entity owner's name

Access User Who Created or Modified Record:

• {!Contact.CreatedBy.Username} - User who created the Contact
• {!Contact.CreatedBy.Email} - Creator's email
• {!Account.ModifiedBy.Name} - User who last modified the Account

Custom Entities and Custom Fields

Magentrix allows administrators to create custom entities and custom fields to meet organization-specific requirements. Understanding naming conventions is essential for referencing these custom elements in merge fields.

Custom Entity Naming Convention

Custom entities (entities created by administrators rather than built into the platform) are identified by the __c suffix:

Examples:

• Project__c - Custom entity for projects
• Invoice__c - Custom entity for invoices
• ProductInventory__c - Custom entity for product inventory

Usage in Merge Fields:
{!Project__c.Name} - Reference the Name field on custom entity
{!Invoice__c.TotalAmount__c} - Reference custom field on custom entity

Custom Field Naming Convention

Custom fields (fields added by administrators to any entity) are also identified by the __c suffix:

Examples on Standard Entities:

• Account.Region__c - Custom Region field on standard Account entity
• Contact.MembershipLevel__c - Custom membership level on Contact
• Opportunity.ExpectedROI__c - Custom ROI field on Opportunity

Examples on Custom Entities:

• Project__c.ProjectManager__c - Custom field on custom entity
• Invoice__c.PaymentTerms__c - Custom field on custom entity

Usage in Merge Fields:
{!Account.Region__c} - Reference custom field
{!Project__c.ProjectManager__c} - Reference custom field on custom entity

Standard Fields Have No Suffix

Standard fields (built into the platform) have no special suffix:

Examples:

• Contact.Firstname - Standard field (note: only first letter capitalized)
• Contact.Lastname - Standard field (note: only first letter capitalized)
• Account.Name - Standard field
• Account.Phone - Standard field
• Opportunity.Amount - Standard field

Custom Relationship Fields

Custom lookup fields that create relationships follow the same naming convention with the _r suffix for navigation:

Example: Custom entity Project__c has custom lookup field AccountId__c referencing Account.

• Field storing ID:AccountId__c
• Relationship for navigation:AccountId_r

Usage:
{!Project__c.AccountId__c} - Returns the Account ID (e.g., "001abc123")
{!Project__c.AccountId_r.Name} - Returns the Account Name (e.g., "Acme Corp")

Integrated CRM Entities

Magentrix supports integration with Salesforce and Microsoft Dynamics CRM. Entities synchronized from these systems follow the same merge field syntax as native Magentrix entities, with one important consideration: case sensitivity.

Salesforce Entities

Salesforce entities may use different capitalization than Magentrix conventions. Always use the exact capitalization from Salesforce when referencing these entities and fields:

Example: If Salesforce defines a custom field as CustomField__c with specific capitalization, use that exact capitalization in merge fields.

Merge Field Usage:
Salesforce and native Magentrix entities work identically in merge fields. You don't need special syntax; simply reference the entity and field names with correct capitalization:

{!Force__Contact.Email} - Salesforce Contact email
{!Force__Account.Name} - Salesforce Account name
{!Force__CustomSFObject__c.CustomField__c} - Salesforce custom object and field

Microsoft Dynamics Entities

Microsoft Dynamics entities follow the same rules as Salesforce entities. Use the exact capitalization defined in Dynamics:

{!DynamicsCrm__Contact.EmailAddress} - Dynamics Contact email (note Dynamics field naming)
{!DynamicsCrm__Account.Name} - Dynamics Account name

Schema Transparency

From a merge field perspective, the origin of the entity (native Magentrix, Salesforce, or Dynamics) doesn't matter. Once the entity is available in Magentrix, merge fields reference it using standard syntax with proper capitalization.

Complete Merge Field Examples

Email Template Examples

Scenario: Welcome email for new portal users (User context)

Subject: Welcome to {!$Organization.Name} Portal, {!Firstname}!

Dear {!Firstname} {!Lastname},

Welcome to the {!$Organization.Name} partner portal! Your account has been activated and you can now access our resources, training materials, and support tools.

Your portal login: {!Username}
Your registered email: {!Email}
Your account: {!Account.Name}

If you have questions, please contact your account manager:
{!Account.Owner.Name}
{!Account.Owner.Email}
{!Account.Owner.Phone}

Best regards,
The {!$Organization.Name} Team
{!$Organization.Email}
{!$Organization.Phone}

Merge Fields Used:

• {!$Organization.Name} - Organization name (global)
• {!Firstname} - Contact's first name (entity instance, simplified)
• {!Lastname} - Contact's last name (entity instance, simplified)
• {!Username} - Contact's username (entity instance, simplified)
• {!Email} - Contact's email (entity instance, simplified)
• {!Account.Name} - Related Account name (relationship navigation)
• {!Account.Owner.Name} - Account owner's name (multi-level navigation)
• {!Account.Owner.Email} - Account owner's email (multi-level navigation)
• {!Account.Owner.Phone} - Account owner's phone (multi-level navigation)
• {!$Organization.Email} - Organization email (global)
• {!$Organization.Phone} - Organization phone (global)

Page Layout Visibility Examples

Scenario: Show "Internal Notes" section only to employees on Account page layout

Visibility Formula: {!IsInRole("Employee")}

This uses a function rather than a merge field, but demonstrates context awareness.

Scenario: Show "Account Executive" field only when Account Type is "Customer"

Visibility Formula: {!Equal(Type,"Customer")}

Merge field Type references Account.Type (entity name omitted because context is Account page layout).

Custom Entity Examples

Scenario: Custom Project Management System

Custom entity: Project__c
Custom fields: ProjectManager__c, Budget__c, Deadline__c
Lookup field: AccountId__c (relationship name: AccountId_r)

Email Template for Project Updates (Project__c context):

Subject: Project Update: {!Name}

Hello {!ProjectManager__c},

This is an automated update for project: {!Name}

Project Details:
Budget: {!Budget__c}
Deadline: {!Deadline__c}
Client: {!AccountId_r.Name}
Client Contact: {!AccountId_r.Phone}

Status: {!Status__c}

Best regards,
Project Management System

Merge Fields Used:

• {!Name} - Project name (entity instance, simplified)
• {!ProjectManager__c} - Custom field (entity instance, simplified)
• {!Budget__c} - Custom field (entity instance, simplified)
• {!Deadline__c} - Custom field (entity instance, simplified)
• {!AccountId_r.Name} - Related Account name via custom lookup (relationship navigation)
• {!AccountId_r.Phone} - Related Account phone via custom lookup (relationship navigation)
• {!Status__c} - Custom field (entity instance, simplified)

Automation Examples

Scenario: Send notification to Account Owner when Opportunity reaches specific stage (Opportunity context)

Email recipient formula: {!Account.Owner.Email}

This merge field navigates from Opportunity → Account → Owner (User) → Email to dynamically determine who should receive the notification.

Email Template Content:

Subject: Opportunity Update: {!Name}

Hello {!Owner.Name},

The opportunity "{!Name}" for account {!Account.Name} has reached the {!Stage} stage.

Opportunity Details:
Amount: {!Amount}
Close Date: {!CloseDate}
Probability: {!Probability}%

Account Contact: {!Account.PrimaryContact__c}

Please review and take appropriate action.

Troubleshooting Common Merge Field Issues

Merge Field Not Resolving (Showing Literal Text)

Symptom: Merge field appears as literal text like {!Contact.Email} instead of the actual email address.

Common Causes:

• Incorrect Syntax: Verify curly braces and exclamation point are correct: {! not { or {{
• Typo in Field Name: Field names are case-sensitive. {!contact.email} won't work if the correct name is {!Contact.Email}
• Field Doesn't Exist: Verify the field exists on the entity with the exact spelling
• Wrong Entity Context: Attempting to reference fields from an entity not available in the current context

Blank or Empty Result

Symptom: Merge field resolves but shows nothing (blank space).

Common Causes:

• Field Is Empty: The field exists but has no value for this record. This is expected behavior.
• Field Does Not Exist: If a field name is incorrect or doesn't exist on the entity, Magentrix treats it as an empty value rather than generating an error. The merge field will display as blank.
• Relationship Not Populated: Navigating a relationship when the lookup field is empty (e.g., {!Contact.Account.Name} when Contact has no Account)
• Permission Issue: User lacks permission to view the field (rare, but possible)

Best Practices for Using Merge Fields

Use Simplified Syntax When Context Is Clear

When context clearly establishes the entity, omit entity names for cleaner, more readable formulas:

Good:Dear {!Firstname}, (in Contact email template)
Also Good:Dear {!Contact.Firstname}, (more explicit but verbose)

Choose based on your preference for brevity vs. explicitness.

Include Entity Names for Clarity in Complex Formulas

When formulas become complex or navigate multiple relationships, include entity names for clarity even when context allows omission:

Good for Readability:{!Opportunity.Account.Owner.Email}
Less Clear:{!Account.Owner.Email} (context allows omission but less obvious)

Test with Real Data

Always test merge fields with actual records containing data to verify they resolve correctly. Pay special attention to:

• Records where fields may be empty
• Records where relationships may not be populated
• Different user contexts (administrator vs. portal user)
• Different record types or scenarios

Document Custom Field Purpose

When creating custom fields that will be referenced in merge fields, document their purpose and usage in the field description. This helps other administrators understand which merge fields to use.

Use Consistent Naming Conventions

Establish naming conventions for custom entities and fields:

• Use descriptive names: ProjectDeadline__c not PD__c
• Be consistent with capitalization
• Use clear relationship names

Handle Null Values Appropriately

When merge fields might be empty, consider using functions to handle null values gracefully:

Example:{!NullValue(PhoneNumber__c,"Not Provided")} displays "Not Provided" when phone number is empty instead of blank space.

Next Steps

Now that you understand merge fields, proceed to Understanding Functions to learn how functions process and evaluate merge field values to create sophisticated business logic.

<< About Functions and Merge Fields | Understanding Functions >>