Aspose.Words

About Mail Merge in Aspose.Words

Aspose.Words can generate documents from templates with mail merge fields. The data from an external source like a database or file is placed into these fields and formatted, and the resulting document is saved in the folder you specify.

Mail Merge is a feature of Microsoft Word for quickly and easily creating documents like letters, labels and envelopes. Aspose.Words takes the standard mail merge and advances it many steps ahead, turning it into a full-fledged reporting solution that allows you to generate even more complex documents such as reports, catalogs, inventories, and invoices.

The advantages of the Aspose.Words reporting solution are:

·          Design reports in Microsoft Word, use standard mail merge fields.

·          Define regions in the document that grow, such as detail rows of an order.

·          Insert images during mail merge.

·          Execute any custom logic, control formatting, or insert complex content using mail merge event handlers.

·          Populate documents with data from any type of data source.

Basic Steps

Steps to perform a mail merge are quite easy. First, you use Microsoft Word to create and design a Word document normally called a template. Note that the document does not have to be a Microsoft Word Template (.dot), it can be a normal .doc document. You insert some special fields called merge fields into the template in places where you want data from your data source to be later inserted.

Then you open the document in Aspose.Words and execute a mail merge operation. The mail merge operation will take data from your data source and merge it into the document. You can then save the document in Word binary format (.doc) or any other format supported by Aspose.Words. You can save it to a file or stream right to the client browser.

You can also designate repeatable merge regions in the document or insert special merge fields that allow you to insert other content such as images.

Depending on how you set up mail merge fields and repeatable regions inside the document, the document will grow to accommodate multiple records in your data source.

If you do not use mail merge regions, then the mail merge will be similar to Microsoft Word mail merge and the whole document content will be repeated for each record in the data source.

Using repeatable mail merge regions, you can designate portions inside a document that will be repeated for each record in the data source. For example, if you mark a table row as a repeatable region then this table row will be repeated, causing the table to dynamically grow to accommodate all of your data.

Data Sources

Data can come from a source in a variety of formats supported by Java. It can be ResultSet, an array of values or from any custom data source. You can also set up a custom data source for mail merging by implementing the IMailMergeDataSource interface. This allows data to be merged from any data source including a list or business objects.

Data which comes from a ResultSet (the result of a database query) is wrapped into an Aspose.Words class called DataTable. Many DataTable objects can be added to a DataSet. These classes mimic the basic functionality of DataTable and DataSet in .NET and allow to more easily merge complex hieratical data into documents.

The DataTable, DataSet and DataRelation classes are required because the ResultSet interface (a core part of the Java framework) has certain limitations which make merging merging with mail mege with regions and nested mail merge not possible on their own:

1.       The ResultSet interface does not include any members which can serve as a table name. This is required during mail merge to link the data to the corresponding region in the document.

2.       There is no direct way to define relationships between other related ResultSet objects. This is a key requirement to make nested mail merge work.

When executing nested mail merge (merging data straight from a hieratical data source), DataTable sources can be added to a DataSet class and DataRelation instances added to define relationships between the data.

Relationships between each DataTable object are defined by creating a new DataRelation and adding it to the DataSet.  The parameters required to be passed to the DataRelation:

1.       The name of the relation as a string. This can be any name but it should describe the relationship it represents by mentioning the table names that the relation represents.

2.       The parent table name as a string.

3.       The child table name as a string.

4.       The primary key column or columns in the parent table as an array of strings. Each value from these columns is linked to the child columns.

5.       The primary key column or columns in the child table as an array of strings. Like above, these are linked to the columns of the parent table.

The names of the primary key columns in the parent and child table are used to create the relation between the two tables.

Considerations when Working with the DataTable and DataSet Classes

Using the DataTable and DataSet classes is analogous of working with disconnected data. All data required for the full nested mail merge must be loaded in memory and must be made scrollable. This means that each ResultSet must left open during the duration of mail merge and the ResultSet.TYPE_SCROLL_INSENSITIVE.

Example CreateDatabaseStatement

Shows how to create a connection to a database which is scrollable.

[Java]

 

/**

* Utility function that creates a statement to the database.

*/

public static Statement createStatement() throws Exception

{

    return mConnection.createStatement(ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_READ_ONLY);

}

 

 

Alternatively if you require the connection to the database to be closed you can load the ResultSet into an instance of the CachedRowSet class. This will store the data from the ResultSet and allow you to close the connection.

Example CreateCachedRowSet

Shows how to store the results from a database query in a CachedRowSet so the database connection can be closed.

[Java]

 

ResultSet resultSet = createStatement().executeQuery("SELECT * FROM Orders");

CachedRowSetImpl cached = new CachedRowSetImpl();

// This loads the data into a CachedResultSet. The connection can be closed after this line.

cached.populate(resultSet);

 

// Load the cached data into a new DataTable.

DataTable orders = new DataTable(cached, "Orders");

 

 

If the requirement of loading all data used for nested mail merge into memory is not viable then you will be required to use a custom mail merge data source by creating a class implementing the IMailMergeDataSource interface.