wordpress hit counter
Mail Merge in WordProcessingML - OpenXML Developer - Blog - OpenXML Developer
Goodbye and Hello

OpenXmlDeveloper.org is Shutting Down

There is a time for all good things to come to an end, and the time has come to shut down OpenXmlDeveloper.org.

Screen-casts and blog posts: Content on OpenXmlDeveloper.org will be moving to EricWhite.com.

Forums: We are moving the forums to EricWhite.com and StackOverflow.com. Please do not post in the forums on OpenXmlDeveloper.org. Instead, please post in the forums at EricWhite.com or at StackOverflow.com.

Please see this blog post for more information about my plans moving forward.  Cheers, Eric

Mail Merge in WordProcessingML

Mail Merge in WordProcessingML

  • Comments 32


Article by Sheela E.N, Sonata Software Limited


This article briefly explains the concept of Mail Merge and how this information is stored in WordProcessingML.


A mail merge is a word processing feature that allows in creating common letters, mailing labels, envelopes, or cataloging documents to a group of people as stored in a database.


We use mail merge when we want to create a set of documents that are essentially in a template format but only in a single place contains unique information. For example, in a letter that announces a new product to all its customers, the company logo and the text about the product is common and will appear in each letter, while the customer address and greeting line will be different in each letter.


The two key parts of the mail merge process are

1.    Connecting to an external data source

2.    Populating mail merge fields with external data


The connection details of the external data source are mentioned in the settings.xml file as


<w:settings xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:sl=http://schemas.openxmlformats.org/schemaLibrary/2006/main …..   ….. … >

    <w:mainDocumentType w:val="envelopes"/>


    <w:dataType w:val="native"/> 

    <w:query w:val="SELECT * FROM `test` "/>

    <w:dataSource r:id="rId1"/>


    <w:activeRecord w:val="4"/>


      <w:udl w:val="Provider=Microsoft.ACE.OLEDB.12.0;User ID=Admin;Data Source=D:\....\....\....\MailMerge\MailMerge.mdb;Mode=Read;Extended Properties=&quot;&quot;;Jet OLEDB:System database=&quot;&quot;;Jet OLEDB:Registry Path=&quot;&quot;;Jet OLEDB:Engine Type=5;Jet OLEDB:Database Locking Mode=0;Jet OLEDB:Global Partial Bulk Ops=2;Jet OLEDB:Global Bulk Transactions=1;Jet OLEDB:New Database Password=&quot;&quot;;Jet OLEDB:Create System Database=False;Jet OLEDB:Encrypt Database=False;Jet OLEDB:Don't Copy Locale on Compact=False;Jet OLEDB:Compact Without Replica Repair=False;Jet OLEDB:SFP=False;Jet OLEDB:Support Complex Data=False"/>

      <w:table w:val="test"/>

      <w:src r:id="rId1"/>

      <w:colDelim w:val="9"/>

      <w:type w:val="database"/>


      <w:recipientData r:id="rId3"/>








The   <w:mailMerge> element specifies the following information of the hosting application to connect to an external data source –

1.    w:mainDocumentType specifies the type of the mail merge. The possible types are

a.    formLetters.

b.    email

c.    envelopes

d.    fax

e.    mailingLabels

f.     catalog

2.    w:queryspecifies the table to be queried

3.    w:dataSource — specifies the link to the external data source. The details are stored in document setting part relationship.

4.    w:viewMergedData — specifies that the merged document shall display the data from the specified external data source where merge fields have been inserted.

5.    w:activeRecord — specifies which record within the data source should be displayed.

6.    w:odso — The Office Data Source Object (odso) settings is optional details which specifies a group of additional settings for the mail merge information which comprises an extension to the standard settings stored with a mail merge.


The Office Data Source Object Settings also contains a link to another part (mailMergeRecipientData) which contains details about all of the inclusion/exclusion data for the contents of the specified mail merge data source and is represented as


  <w:recipientData r:id="rId3"/>


The details of the record inclusion/exclusion in mail merge recipient data part are stored as


<w:recipients  xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing" xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" … …. …. >



    <w:active w:val="0"/>

    <w:column w:val="2"/>

    <w:uniqueTag w:val="MQ="/>




    <w:active w:val="0"/>

    <w:column w:val="2"/>

    <w:uniqueTag w:val="Mq="/>






The <w:recipientData> element specifies the following details for the inclusion/exclusion of records within mail merged document.


1.     w:column specifies the column on which the filter has applied based on the value of the column (like where clause on that column)


2.     w:uniqueTag — specifies the contents of a given record within the specified external data source, in the column containing unique data for every record within the external data source for inclusion/exclusion of records for mail merge.  The value specifies that this should be the base64-encoded value of the unique tag value as specified by the data source. This element is used along with <w:column> element.


3.     w:active — specifies whether the record to be shown on not. The default value is 1 which indicates the record is included for the mail merge


If this part is not present, it indicates that all the records within the data source are included for the mail merge.


In the main document part (document.xml by default), the merge fields are populated by extracting data from external data source and the same is represented as





<w:fldSimple w:instr="MERGEFIELD FirstName">



        <w:noProof />








In the above XML snippet, the merge fieldFirstName’ is inserted in a WordprocessingML document which connects to the external data source. When the mail merge takes place, the data from the FirstName column will be populated into the field FirstName (<w:fldSimple w:instr="MERGEFIELD FirstName">) within the merged WordprocessingML document.


The word document containing mail merge field place holders is illustrated as





When the mail merge takes place, the data will be generated and displayed as







In my next article, I will explain how to apply mail merge to WordProcessingML programmatically using System.IO.Packaging API.

Page 1 of 3 (32 items) 123