DocumentID: ECMA-376/Part4/2.14
Title: ECMA-376, Part4: 2.14 Mail Merge
Extracted-From: ECMA-376 Office Open XML File Formats, 1st Edition / December 2006
Warning: Coverted to HTML format by a script known to have bugs

Navigation:

Next: 2.14.1 active (Record Is Included in Mail Merge)
Up: 2. WordprocessingML Reference Material
Table of contents: Table of contents
Previous: 2.13.8 Spelling & Grammar

2.14 Mail Merge

Mail merge refers to an operation by which WordprocessingML documents may work in conjunction with data from an external data source, importing this data into a document according to a set of codes contained in WordprocessingML known as fields.

A WordprocessingML document that contains the mailMerge element (§2.14.20) and is therefore connected to an external data source, is known as a source document. In addition to being connected to an external data source and containing fields, a source document may contain any regular WordprocessingML constructs such as:

Text runs
Paragraphs
Images
Tables
Numbering
Etc.

There are two key parts of the mail merge data stored in a WordprocessingML document

Information connecting a document to an external data source
Information populating fields within that document with external data.

Once the fields in a merged document have been populated with external data, mail merge has been completed and the resulting files are known as mail merged documents or simply merged documents.

The mail merge settings for a WordprocessingML document are stored in two locations:

The standard mail merge settings are stored as the child elements of the mailMerge element (§2.14.20)
A set of additional mail merge settings stored in the odso element (§2.14.25), and collectively referred to as the Office Data Source Object settings. The Office Data Source Object is an extension to the standard settings stored with a mail merge which performs two functions: First, it provides additional information about the mail merge data source, specifically: information about how to map the columns in the data source to MERGEFIELD fields and information about records which shall be included and excluded when creating merged documents. Second, it provides an alternate set of connection information which should be used when the dataType element (§2.14.10) specifies a value of native. This alternate connection string provides additional connection information for applications which choose to support the ODSO connection string syntax.

[Example: Consider a WordprocessingML document containing static WordprocessingML constructs such as text runs and paragraphs in addition to two WordprocessingML MERGEFIELD fields (§2.16.5.42) calling for Courtesy Title and Last Name data. The field codes for each field are displayed, delimited by {} characters:

Dear {MERGEFIELD "Courtesy Title" \m} {MERGEFIELD "Last Name" \m},

Sample text. Sample text. Sample text. Sample text. Sample text. Sample text. Sample text. Sample text. Sample text. Sample text. Sample text. Sample text. Sample text. Sample text. Sample text. Sample text. Sample text. Sample text. Sample text. Sample text. Sample text. Sample text. Sample text. Sample text. Sample text.

Sincerely,

If the following WordprocessingML was added to this document, this document would become a source document rather than just a standard WordprocessingML document, as the mailMerge (§2.14.20) element specifies the elements and attributes necessary to enabled the document to connect to an external spreadsheet data source.

<w:mailMerge>

...

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

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

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

...

</w:mailMerge>

Here, the dataType (§2.14.10) and dataSource (§2.14.9) elements specify that the given document shall be connected to the external data source target by the relationship whose relationship value is rId1 as specified in the dataSource element (§2.14.9). While connected to the external data source, the source document together with the hosting application and/or data source access application will extract data from the external data source to perform the merge as specified by the connectString (§2.14.8) and query (§2.14.26) elements. end example]

Converted to HTML format by ooxmlspec2html 0.1, a Perl script provided by OpenISO.org.