Aspose.Words

How-to: Set up Relations for use in Nested Mail Merge with Regions

When using executing mail merge with nested regions there must be relationships present between parent and child data in order for the process to work correctly. Skipping this important step is one of the most common causes of nested mail merge to fail.

Even though setting up relations between data tables related is a requirement when using mail merge with regions, there are some cases in which relations could be set automatically for you. This depends on the data source being used.

This article explains perform nested mail merge by providing detailed instructions on how to set up relations for each particular type of data source.

C:\Aspose\Materials\How-to Set up Relations for use in Nested Mail Merge with Regions\Nested Mail Merge with Regions Relationships Flowchart (Visio).png

Explicitly Creating Relations between DataTables in a DataSet

Each DataTable object wraps a ResultSet containing the data from your data source. A related collection of these DataTable objects can be added to a DataSet class and the DataRelation created to describe the relations between each of these tables.

The code snippet below demonstrates how to create relationship between the two data tables “Player” and “Country” within the DataSet called “dataSource”.

Example NestedMailMergeCreateRelationship

Shows how to create a simple DataRelation for use in nested mail merge.

[Java]

 

dataSet.getRelations().add(new DataRelation("OrderToItem", orderTable.getTableName(), itemTable.getTableName(), new String[] {"Order_Id"}, new String[] {"Order_Id"}));

 

 

Creating Relations between IMailMergeDataSource Objects

Implementation of the IMailMergeDataSource interface provides you an easy use your business objects as a data source for nested mail merge. You can also use nested mail merge with these objects as well. This is achieved by implementing the IMailMergeDatasource.GetChildDataSource method.

The details of how to fully implement this interface into your project can be found in the API documentation for the IMailMergeDataSource interface. According to the focus of this article, we are only going to concentrate on the implementation of relationships between these types of objects and not any further implementation.

The code example below shows how to use IMailMergeDataSource.GetChildDataSource to provide relationships between parent and child data. This method is called by mail the mail merge engine whenever a nested region is encountered in the current parent region. This method is invoked in the parent IMailMergeDataSource which is handling the region so it can return the appropriate child data for the current parent record.

Example GetChildDataSourceExample

Shows how to get a child collection of objects by using the GetChildDataSource method in the parent class.

[Java]

 

public IMailMergeDataSource getChildDataSource(String tableName)

{

    // Get the child collection to merge it with the region provided with tableName variable.

    if(tableName.equals("Order"))

        return new OrderMailMergeDataSource(mCustomers.get(mRecordIndex).getOrders());

    else

        return null;

}

 

 

The IMailMergeDataSource.GetChildDataSource method returns the child data related on the particular parent index. You are expected to return the correct child data from your custom objects based on the given table name and current position of the parent data. In this case this achieved by retrieving the order collection based on the current customer index. If this class is used in mail merge without nested regions or in simple mail merge, this method should simply return null.

Also note that the parent region might have one or more related child sets. These are differentiated using the supplied table name parameter. Each child data source should be derived from the IMailMergeDataSource interface as well.