Practical rules for Salesforce document templates that don't break

The problem in two sentences

If your Word or PDF templates break when an admin adds a field or the sales team asks for one more quote line, you’re not alone. Badly designed merge templates are fragile: they misplace data, drop repeating rows, or put signature blocks on the wrong page.

Why templates fail in Salesforce document generation

As the admin, you control layouts and API names, but users keep asking for small changes that have large effects. Here are the common failure modes I've seen:

Using fixed-position content. A signature placed with fixed coordinates won't survive an extra invoice line or a new clause that shifts pagination.
Embedding calculated text in the template instead of pulling the calculated field from Salesforce. When the logic changes you have to edit every template.
Expecting child records to appear in a fixed count. If an Opportunity has four OpportunityLineItems and your template assumes three rows, the fourth disappears.
Mixing data from parents and deep lookups without checking nulls. A missing parent record causes the whole table to fail or print empty tokens.

Design rules for reliable Salesforce document templates

Follow these rules when you build or update templates. They’re written for clicks-first admins and avoid fragile tricks.

1. Pull calculated values from Salesforce, not the template

Create formula fields or use a Flow to calculate totals, tax, clause logic, or conditional text, and merge those fields into the template. When the rules change, change the formula or flow once in Salesforce—not in every Word file.

2. Use repeating rows for child records

Don’t hard-code a fixed number of lines. Use the template tool’s repeating-row feature so all child and grandchild rows appear as table rows. That way an Opportunity with 12 OpportunityLineItems prints 12 rows; one with 2 prints two.

Example conceptual layout for an invoice table
- [Repeating row start]
  Description: {Invoice_Line__c.Description}
  Quantity: {Invoice_Line__c.Quantity__c}
  Unit Price: {Invoice_Line__c.Unit_Price__c}
- [Repeating row end]

Replace the bracketed start/end markers with the repeat syntax your template tool uses. The point is: treat the row as a repeat, not as a set of fixed fields.

3. Protect signature placement with anchor tags

Place signature fields using anchor tags (text anchors), not absolute coordinates. Anchor tags move with the surrounding text, so signatures remain attached to the right clause no matter how many pages the document gains or loses.

4. Limit parent traversal to what you need

DocuGen can reach five levels of parent lookups. That’s useful, but don’t pull everything just because you can. Map the exact fields you need from Account, Contact, Contract, Quote, or custom parents like Renewal__c. Fewer lookups means less chance of nulls and fewer performance hits.

5. Handle missing data explicitly

Decide what should print when a field is empty. Use fallback fields or default text from the record (eg, "N/A" or "TBD") rather than leaving blank tokens. That avoids awkward gaps and makes the document look intentional.

Checklist before you publish a template

Have you pulled totals and conditional text from Salesforce formulas or Flows?
Are child records rendered with repeating rows instead of repeated placeholders?
Do signature fields use anchor tags so they survive repagination?
Are you only traversing the parent lookup levels you actually need?
Do you have default text where values can be null?
Did you test with a record that has the longest expected content (a 60-page agreement is a good stress test) and the shortest?

Concrete scenario: a 60-page MSA and 200 renewals a month

Imagine a 60-page Master Services Agreement generated from Opportunity with fields on Account, primary Contact, Quote and a custom Renewal__c. You also gather invoice lines from Invoice_Line__c as repeating rows. If users generate 200 renewals a month, any template fragility multiplies administrative work fast.

Apply the rules above: move clause selection into formula fields on Renewal__c; render invoice lines as repeating rows; use anchor tags for 12 signature blocks; test with a fully populated Opportunity (all children present) and with a minimal Opportunity (no invoice lines). That test catches the two biggest risks: missing child rows and signature misplacement.

Common mistakes and quick fixes

Signature ends up on the wrong page

Fix: replace fixed coordinates with anchor tags and attach the signer block to nearby clause text. Re-generate the document and test with long and short records.

One or two child rows are missing

Fix: convert those rows to a repeating table. Confirm the template reads child records from the correct object (OpportunityLineItem, Invoice_Line__c, etc.) and that filters (if any) match expected criteria.

Blank values where conditional text should be

Fix: build a formula field or Flow that returns a readable default or the conditional text, then merge that field into the template.

How this maps to Savvy DocuGen

DocuGen fills Word and PDF templates from any Salesforce record, reaches up to five levels of parent lookups, and supports child/grandchild repeating rows—so you can implement the repeating tables and parent-field rules above. Signature positions use anchor tags so they move with your text. Finished documents are filed back to the record in Files or Notes and Attachments per template, and signature runs use your Circularo account so signed PDFs come back to the same record.

If you want to try these template rules without touching production, install DocuGen in a sandbox and test with a long and a short record. That quick test will show whether your templates behave before you put them in front of users.

Try DocuGen in your sandbox today.