---
title: "Nested Mail Merge with Regions in Java"
---
In some scenarios, you may need to use nested Mail Merge with regions. Nested merge is a feature that enables you to merge hierarchical data from your data source into your merge template to easily populate your document. Basically, the hierarchical data is represented as a set of data items, and hierarchical relationships describe how the data items are related to each other (one item of data is the parent of another one).
Aspose.Words allows you to perform a Mail Merge operation with nested regions. You can use this feature if you have a data source that is organized into a tree-like structure and you want to execute a Mail Merge operation to populate a template with hierarchical data.
{{% alert color="primary" %}}
Nested Mail Merge is relevant only when performing a Mail Merge with regions.
{{% /alert %}}
## What is a Nested Mail Merge
The Mail Merge region is called nested if you have two or more Mail Merge regions where one of them is inside the other in a hierarchical form. Note that each region contains data from one table.
The most common example of a nested Mail Merge is an order that contains multiple items where you need to link multiple data tables and present the information in a template.
The picture below shows two nested regions where the *Order* Mail Merge region is the parent of the *Item* Mail Merge region.
## How to Process Mail Merge with Nested Regions
The data to be merged into a template can come from various sources, mainly relational databases or XML documents. In our example, we are going to use an XML file to store our data and load it directly into the **DataSet**.
Aspose.Words allows you to process Mail Merge with nested regions using the data relationships specified in the **DataSet**. When the **DataSet** object loads XML, it either uses the provided schema or infers it from the structure of the XML itself to accomplish this. From this structure, it creates relationships between tables where necessary.
The image below shows how the data from the *Order* table passed to the nested merge regions will be linked to the *Item* table, as well as the output generated during the merge operation.
As you can see from the output document, each order from the **Order** table is inserted into the merge template with all order’s related items from the **Item** table. The next order will be inserted along with their items until all the orders and items are listed. The order of nesting Mail Merge with regions in the template must match the data relationships between the tables in the data source.
The following code example shows how to generate an invoice using nested Mail Merge with regions:
{{< gist "aspose-words-gists" "827e71ccc0b8516a3cfe247b86ce6d4e" "Examples-src-main-java-com-aspose-words-examples-mail_merge-TypesofMailMergeOperations-NestedMailMerge.java" >}}
{{% alert color="primary" %}}
You can download the sample file of this example from [Aspose.Words GitHub](https://github.com/aspose-words/Aspose.Words-for-Java/blob/master/Examples/Data/Mail%20merge%20data%20-%20Customers.xml).
{{% /alert %}}
## How to Set Up Data Relations in Nested Mail Merge with Regions
You need to set up all data relationships in the parent‑child structure to execute the nested Mail Merge with regions correctly. Skipping this important step can lead to a failure in executing the nested Mail Merge with regions.
When retrieving data for a nested Mail Merge from an XML file using the **ReadXml** method, relationships are automatically created according to the structure of the XML document. However, you need to make sure that correct relations have been created.
If Mail Merge is not working as expected, then you may need to restructure your XML file or explicitly create relations between DataTable objects in the DataSet.
A `DataSet` that has related data tables will use the **DataRelation** object to represent the parent‑child relationship between the tables.
The following code example shows how to establish a `DataRelation` between a customer’s table and an order’s table by using a `DataRelation` object:
{{< highlight java >}}
dataSet.getRelations().add(new DataRelation("OrderToItem", orderTable.getColumns().get("Order_Id"), itemTable.getColumns().get("Order_Id"), false));
{{< /highlight >}}
------
## FAQ
1. **Q:** What is the difference between a regular Mail Merge region and a nested Mail Merge region?
**A:** A regular region merges data from a single table, while a nested region merges data from a child table that is related to the parent table. The child region must be placed inside the parent region in the template, and the data source must contain a `DataRelation` that defines the parent‑child link.
2. **Q:** How do I create the required `DataRelation` when my data comes from an XML file?
**A:** If you load the XML with `DataSet.readXml`, Aspose.Words will automatically infer relationships based on the XML hierarchy. If the relationships are not inferred correctly, you can create them manually using `DataSet.getRelations().add(new DataRelation(...))` as shown in the example.
3. **Q:** My nested Mail Merge produces only the parent rows and no child rows. What could be wrong?
**A:** This usually means the region names in the template do not match the table names or the `DataRelation` is missing or incorrectly defined. Verify that the child region name matches the child table name and that the `DataRelation` connects the correct parent and child columns.
4. **Q:** Can I use a database `ResultSet` instead of an XML file for nested Mail Merge?
**A:** Yes. Fill a `DataSet` with `DataTable`s retrieved from the database, then create the necessary `DataRelation`s between those tables before calling `mailMerge.executeWithRegions(dataSet)`.
5. **Q:** Is it possible to perform a nested Mail Merge with more than two levels (e.g., Order → Item → SubItem)?
**A:** Absolutely. You can nest any number of regions as long as each child region has a corresponding `DataRelation` that links it to its immediate parent table. Ensure the template reflects the same hierarchy.