Understanding Merge Fields: The Key to Dynamic Documents

Merge fields are the foundation of dynamic document generation. They act as placeholders in your templates that get replaced with actual data when you generate a document. Master merge fields and you can create any document from any data source.

What Are Merge Fields?

A merge field is a placeholder in your template that looks like this: {{FieldName}}. When you generate a document, the system replaces these placeholders with actual data from your data source.

For example, {{ClientName}} might become "Acme Corporation" in the final PDF.

Basic Merge Field Syntax

The basic syntax uses double curly braces:

The field name should match exactly what's in your data source (column header in Google Sheets, field API name in Salesforce, etc.).

Accessing Related Data

For CRM data, you often need to access related records. Use dot notation:

Common Merge Field Patterns

For Invoices

For Quotes/Proposals

Dynamic Tables

For line items or related records, you can create tables that automatically expand based on your data. The table row acts as a template that repeats for each item:

Conditional Rendering

Sometimes you want to show or hide elements based on your data. With visibility conditions, you can control which fields appear in your final PDF.

How It Works

Each element in your template can have a visibility condition. If the condition evaluates to false, the element is hidden from the generated PDF.

Syntax

Visibility conditions use merge fields with comparison operators:

Supported Operators

• == - Equal to
• != - Not equal to
• > - Greater than
• < - Less than
• >= - Greater than or equal
• <= - Less than or equal

Common Use Cases

• Show discount row only when applicable - {{Discount}} > 0
• Display premium terms for VIP clients - {{AccountTier}} == 'Premium'
• Hide optional sections - {{IncludeWarranty}} == true
• Show different payment terms by region - {{Region}} == 'EU'

If a referenced field is empty or null, the element is hidden by default. This makes it easy to handle missing data gracefully.

Best Practices

• Use consistent naming - Match your data source exactly
• Handle empty values - Consider what happens if a field is blank
• Test with real data - Don't just use sample data
• Document your fields - Keep a reference of what each field maps to
• Use descriptive names - {{CustomerFullName}} is better than {{name1}}

Troubleshooting

If a merge field isn't working:

• Check for typos in the field name
• Verify the field exists in your data source
• Make sure you're using the API name, not the label (for CRMs)
• Check that the data isn't empty for your test record
• Ensure proper dot notation for related fields

Conclusion

Merge fields are simple in concept but powerful in practice. Once you understand the syntax and patterns, you can create templates for any document type and connect them to any data source.