# Performing Nested MailMerge with Multiple Levels in RadWordsProcessing

## Environment

| Version    | Product            | Author                                                                          |
| ---------- | ------------------ | ------------------------------------------------------------------------------- |
| 2024.3.806 | RadWordsProcessing | [Desislava Yordanova](https://www.telerik.com/blogs/author/desislava-yordanova) |

## Description

This article shows how to perform a [MailMerge](https://www.telerik.com/document-processing-libraries/documentation/libraries/radwordsprocessing/editing/mail-merge) operation with multiple levels of nested data, such as a list within a list (for example, `Incident` > `Person` > `Phones`) in [RadWordsProcessing](https://www.telerik.com/document-processing-libraries/documentation/libraries/radwordsprocessing/overview).

## Solution

To perform a nested [MailMerge](https://www.telerik.com/document-processing-libraries/documentation/libraries/radwordsprocessing/editing/mail-merge) operation with multiple levels of data, follow these steps:

1. Prepare your data model to reflect the nested structure. In this case, the model includes the `Incident`, `Person`, and `Phone` classes.

2. Use the [MailMerge](https://www.telerik.com/document-processing-libraries/documentation/libraries/radwordsprocessing/editing/mail-merge) method to merge the data with the document template. Ensure your document template has the appropriate merge fields defined for each level of data.

3. Use special merge fields (`TableStart`, `TableEnd`, `RangeStart`, and `RangeEnd`) to denote the beginning and end of each nested collection.

The following example shows how to set up your data model and perform the nested MailMerge:

**Example 1: Set Up Nested Data Model and Perform MailMerge**

```csharp
// Define your data models.
public class Incident
{
    public string ReportNumber { get; set; }
    public List<Person> People { get; set; }
}

public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public List<Phone> Phones { get; set; }
}

public class Phone
{
    public string PhoneNumber { get; set; }
}

// Prepare the data.
var mergeData = new List<Incident>{
    new Incident{
        ReportNumber = "INC-2024-001",
        People = new List<Person>{
            new Person{
                FirstName = "John",
                LastName = "Doe",
                Phones = new List<Phone>{
                    new Phone{ PhoneNumber = "310-555-0101" },
                    new Phone{ PhoneNumber = "310-555-0102" }
                }
            },
            // Add more Person instances as needed.
        }
    }
};

// Perform the MailMerge operation.
RadFlowDocument document = new RadFlowDocument();
// Assume 'provider' is initialized and points to the appropriate document format provider.
var mailMergeResult = document.MailMerge(mergeData);
```

In your document template, ensure you have the corresponding merge fields:

* For the start and end of the `People` list: `TableStart:People` and `TableEnd:People`.
* For the start and end of the `Phones` list within each `Person`: `RangeStart:Phones` and `RangeEnd:Phones`.
* For merging individual property values, use merge fields named after the properties, such as `FirstName`, `LastName`, and `PhoneNumber`.

  ![Nested mail merge template](https://www.telerik.com/document-processing-libraries/documentation/assets/dbfe7268ce8729e26a3a26bdd47c3c5a/nested-mail-merge-template.png)

### Generating the Table Structure in the Document

When you work with nested collections, you must dynamically create table structures that accommodate the varying lengths of these collections.

The following image shows the result of the nested MailMerge operation:

![Nested mail merge result](https://www.telerik.com/document-processing-libraries/documentation/assets/b180fdfcbbe50f083ba70c39fd1c57e5/nested-mail-merge-result.png)

## Troubleshooting

### NullReferenceException with Newlines in Table Group Cells

When you execute a nested `MailMerge` over a table group (`TableStart:GroupName` and `TableEnd:GroupName`) that spans multiple rows, multiple paragraphs or hard newlines (`\r\n`) in intermediate cells can cause a `NullReferenceException`.

**Workaround:**

* Use soft line breaks (Shift+Enter in Word or `\v` / `BreakType.LineBreak` in code) instead of hard paragraph breaks (`\r\n`) inside intermediate cells so the cell content remains within a single `Paragraph`.
* Alternatively, place multi-paragraph merge fields in the last row of the table group, or split the content across separate single-paragraph table rows.

## See Also

* [MailMerge](https://www.telerik.com/document-processing-libraries/documentation/libraries/radwordsprocessing/editing/mail-merge)
* [Generating a Word Document with Data Using MailMerge in RadWordsProcessing](https://www.telerik.com/document-processing-libraries/documentation/knowledge-base/generate-doc-template-and-populate-with-collection-data-mail-merge)
* [Populate a Table with Data Using Nested Mail Merge Functionality](https://www.telerik.com/document-processing-libraries/documentation/knowledge-base/populate-table-data-mail-merge)
