This guide explains how to create a Document Merge action that includes a repeating sublist (table) in the generated document. In this example, the data sources are Apsona reports.

Step 1: Create the Top-Level Data Source Report

The top-level report determines how many documents Apsona generates.

Rule: One row in the top-level report = One generated document.

For example:

• Account Report → One document per Account
• Contact Report → One document per Contact
• Opportunity Report → One document per Opportunity

Steps

1. Navigate to Apsona → Reports.
2. Create a Single-Step Report (SSR) or Multi-Step Report (MSR) based on your parent object.
3. Add all parent-level fields required in the document.
   Example:
   • Account Name
   • Billing Address
   • Phone
   • Owner
4. Include the parent Record ID (for example, Account ID or Contact ID).
   • This field is mandatory because it will be used later to link the sublist report.
5. Make sure the report contains only one row for each parent record.
6. Do not include child object fields (such as Opportunities, Cases, Donations, etc.).
   • Including child fields causes one parent to appear multiple times.
   • Since Apsona creates one document per row, this results in duplicate documents.

Example

This report generates 2 documents.

Step 2: Create the Sublist Data Source Report

The sublist report supplies the repeating rows inside your document.

Unlike the top-level report, this report contains one row per child record.

Example child objects:

• Opportunities
• Cases
• Contacts
• Donations
• Orders
• Tasks

Steps

1. Create a new report based on the child object.
2. Add all fields that should appear inside the sublist table.
3. Include the lookup field that links the child record to the parent.

For example:

If the parent report is Account

Include:

• Opportunity Name
• Amount
• Stage
• Account ID

The Account ID field is mandatory because it is used during Linkage.

4. Apply any filters if required.

Example:

• Closed Won Opportunities only
• Open Cases only
• Current Year Donations only

Example

This report supplies the repeating rows inside each document.

Step 3: Create the Merge Template

Open Microsoft Word (.docx).

Insert all normal merge fields for the parent information.

Example:

• Account Name
• Billing Address
• Owner

These are inserted normally.

Creating the Sublist Table

Insert a Word table.

Example

The first row contains headers.

The second row will contain merge fields.

Insert TableStart

In the first cell of the data row, insert

«TableStart:Opportunities»

You may use any record group name.

Examples:

• Opportunities
• Cases
• Donations
• Contacts

Rules:

• No spaces
• Must be unique
• Remember the name because Apsona uses it later.
• • *

Insert Child Merge Fields

After TableStart, insert the child merge fields.

Example

«TableStart:Opportunities»
«Opportunity Name»
«Amount»
«Stage»

Insert TableEnd

After the last merge field, insert

«TableEnd»

Do not write

TableEnd:Opportunities

Only use

«TableEnd»

Final Row Example

During merge, Apsona duplicates this row for every matching child record.

Step 4: Upload the Template

Save the document as .docx.

Upload it to one of the supported locations:

• Salesforce Documents

• Google Docs (if using Google integration)

• • *

Step 5: Create the Merge Action

Run your Top-Level Report.

Click

Merge / Mail

Create a New Merge Action.

Choose your uploaded template.

Step 6: Map the Top-Level Fields

In Step 3 of the Merge Action wizard:

Map all parent merge fields.

Example:

Template Field. Report Field

Account Name - Account Name

Phone - Phone

Address - Billing Address

Step 7: Configure the Sublist Record Group

Because the template contains

TableStart:Opportunities

Apsona automatically creates a Record Group named Opportunities.

Below the normal field mappings, locate the Opportunities Record Group.

Open it.

Select the Data Source

Inside the Record Group:

Open the Mapping tab.

Change the Data Source.

Instead of the top-level report, select the Sublist Report created earlier.

Now map all child merge fields.

Example

Template Field. Report Field

Opportunity Name - Opportunity Name

Amount - Amount

Stage - Stage

Close Date - Close Date

Step 8: Configure Linkage (Most Important Step)

After selecting the sublist report,

Open the Linkage tab.

This step tells Apsona which child records belong to which parent record.

Without linkage:

Every document will contain every child record from the sublist report.

With linkage:

Each document contains only its related child records.

Configure the linkage as:

Parent Report Field

Account ID

\=

Sublist Report Field

Account ID

Apsona now knows:

ABC Document

• Opp 1
• Opp 2

XYZ Document

• Opp 3

instead of printing all three opportunities in every document.

Step 9: Complete the Merge Action

Configure any remaining options, such as:

• Output file name
• Save as Attachment (optional)
• Logging options (optional)

Give the merge action a meaningful name.

Example:

• Account Opportunity Summary
• Contact Donation Report
• Opportunity Product Summary

Click Save or Save and Run.

Final Flow

Top-Level Report
       │
       │
One Row = One Document
       │
       ▼
Merge Template
       │
       ▼
TableStart / TableEnd
       │
       ▼
Sublist Report
       │
       ▼
Linkage
Parent ID = Child Lookup ID
       │
       ▼
Generated Document

Best Practices

• Keep the top-level report to one row per parent record.
• Always include the parent Record ID in the top-level report.
• Always include the lookup field (parent ID) in the sublist report.
• Never include child object fields in the top-level report.
• Use a separate report for each sublist.
• Configure the Linkage correctly using the parent Record ID and child lookup field.
• Ensure the Record Group name in TableStart matches the Record Group shown in the Merge Action wizard.
• Test the merge with a small number of records before deploying it for production use.

Documentation - https://www.apsona.com/docs/help-and-support/doc-merge-with-sublists/

Demo - https://www.youtube.com/watch?v=Bq32t2fA2OQ