Telerik blogs
RadWordsProcessing is evolving faster and faster. One of the latest features we have implemented is mail merge. For those of you who are not familiar with this functionality, Wikipedia says: “Mail merge is software operation describing the production of multiple and potentially large numbers of documents from a single template and a structured data source."

In this post, I will demonstrate with simple examples how easy it is to create a document template and the ease with which the data source is passed to the same template to perform the merging.

Creating a Mail-Merge Document Template with Code

Before executing mail merge, we need first to have a document template to merge our data with. The mail-merge document template is just a document containing a special type of elements called merge fields. A merge field is simply a reference to a data field by the field’s name.

Fields are inserted with RadFlowDocumentEditor. To learn more about RadFlowDocumentEditor, check the Say Hello to RadWordsProcessing blog post.

Let’s start creating the template by initializing a new document and associating it with an editor.
RadFlowDocument document = new RadFlowDocument();
RadFlowDocumentEditor editor = new RadFlowDocumentEditor(document);

As a next step, insert the first couple of fields.
editor.InsertText("Hello ");
editor.InsertField("MERGEFIELD FirstName ", "«FirstName»");
editor.InsertText(" ");
editor.InsertField("MERGEFIELD LastName ", "«LastName»");

To insert a field using InsertField method of RadFlowDocumentEditor you will need the code fragment of the field and the field result. The code fragment is composed from the field name and parameter. In our case, MERGEFIELD is the field name and LastName is the parameter that represents property in the data source record. The field result represents the content that should be shown in the document template.

editor.InsertText("On behalf of ");
editor.InsertField("MERGEFIELD CompanyName ", "«CompanyName»");
editor.InsertText(", ");
editor.InsertText("I would like to thank you for purchasing ");
editor.InsertField("MERGEFIELD PurchasedItemsCount ", "«PurchasedItemsCount»");
editor.InsertText(" ");
editor.InsertField("MERGEFIELD ProductName ", "«ProductName»");
editor.InsertText(" from us.");
editor.InsertText("We are committed to provide you with the highest level of customer satisfaction possible. ");
editor.InsertText("If for any reasons you have questions or comments please call ");
editor.InsertField("MERGEFIELD ProductSupportPhone ", "«ProductSupportPhone»");
editor.InsertText(" ");
editor.InsertField("MERGEFIELD ProductSupportPhoneAvailability ", "«ProductSupportPhoneAvailability»");
editor.InsertText(", or email us at ");
editor.InsertField("MERGEFIELD ProductSupportEmail ", "«ProductSupportEmail»");
editor.InsertText("Once again thank you for choosing ");
editor.InsertField("MERGEFIELD CompanyName ", "«CompanyName»");
editor.InsertText("Sincerely yours,");
editor.InsertField("MERGEFIELD SalesRepFirstName ", "«SalesRepFirstName»");
editor.InsertText(" ");
editor.InsertField("MERGEFIELD SalesRepLastName ", "«SalesRepLastName»");
editor.InsertField("MERGEFIELD SalesRepTitle ", "«SalesRepTitle»");

And here is the result saved in DOCX format:
Document template

Of course, the template doesn’t need to be created with RadWordsProcessing. It could be created in one of the formats supported by the library that also supports mail-merge functionality like DOCX or RTF and imported with the respective format provider.

Creating Data Source and Passing it to the Mail-Merge Document Template

Once we have a template, it’s time to prepare for the data source merging. The only requirement to the data source is to implement the IEnumerable interface. This way, the document template will be able to iterate over all records and produce the final merged document. The records in the source need to contain properties corresponding to all the merge field names. Here is the class definition of the mail-merge record for our example:

public class FollowUpData
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string CompanyName { get; set; }
    public int PurchasedItemsCount { get; set; }
    public string ProductName { get; set; }
    public string ProductSupportPhone { get; set; }
    public string ProductSupportPhoneAvailability { get; set; }
    public string ProductSupportEmail { get; set; }
    public string SalesRepFirstName { get; set; }
    public string SalesRepLastName { get; set; }
    public string SalesRepTitle { get; set; }

Creating separate classes each time you want to use the mail-merge functionality is not mandatory; dynamic class could do the job, as well.

Finally, we need to pass the data source to the document template. This is done with a single line of code:
RadFlowDocument mailMergedDocument = document.MailMerge(mailMergeDataSource);

And that’s all! The mail merge is finished. The following image illustrates the final result of our example with one record:Merged document

The used code is available for download in our SDK repository on GitHub.
Feel free to contact us if you have any questions or suggestions for the WordsProcessing library.

Mihail Vladov
About the Author

Mihail Vladov

Mihail Vladov is a Software Engineering Manager at Progress. He has more than a decade of experience with software and product development and is passionate about good software design and quality code. Mihail helped develop the WPF controls suite and Document Processing libraries which are used by thousands of developers. Currently, he is leading the JustMock team. In his free time, he loves to travel and taste different foods. You can find Mihail on LinkedIn.

Related Posts


Comments are disabled in preview mode.