3.1.2.2.1.2 recipientData (Data About Single Data Source Record)

This element specifies information about a single record within an external data source. If a record shall be merged into a merged document, then no information is needed about the record within this part. However, if a the record shall not be merged into a merged document, then the hash value for the record shall be stored within the hash element as a child of this element, along with the active element, to indicate this exclusion.

[Note: This mapping is necessary in place of simply using the element order to correspond to the record indices in the external data source because records may be added or deleted from external data sources, and a means must be provided to maintain specific external record WordprocessingML data, like that specified in the active element (§3.1.2.1.1.6, active) and the corresponding external data record, when the WordprocessingML document is reconnected to the external data source, irrespective of the ordering of the records within the external data source. In other words, this element, and its child elements enable merged WordprocessingML documents to maintain the relationship between the records within an external data and record-specific WordprocessingML parameters. end note]

[Example: Consider a mail merge source WordprocessingML document that:

Has been connected to a specified external data source containing three records; and

Has been configured by the hosting application to not populate a merged document with the record pertaining to John Smith in the external data source.

Consider also that the first time the given WordprocessingML document was connected to the external data source, John Smith's record was in the second record in the data source.

When this merged document is connected to the external data source the recipientData element may be used to store the hash value for each data record in the external data source, including John Smith's. This setting is represented using the following WordprocessingML to use the hash codes within the recipientData element to uniquely identify the three records within the external data source.

 <w:recipientData>
   <w:hash w:val="1408613399" /> 
 </w:recipientData>
 <w:recipientData>
   <w:active w:val="0" />
   <w:hash w:val="870254691" /> 
 </w:recipientData>
 <w:recipientData>
   <w:hash w:val="1107777181" /> 
 </w:recipientData>

Here, the first, second (John Smith record), and third records within the specified data source whose hash values are 1408613399, 870254691, and 1107777181 have been associated with recipient data via the active element to specify that the record associated with the given record (John Smith's record) shall not be used to populate a merged WordprocessingML document.

With these associations in place, if a fourth record is added to the given external data source and that record precedes John Smith's record, when the given merged WordprocessingML document is reconnected to the external data source, the hosting application will still know that John Smith's record shall not be used to populate a merged WordprocessingML document as it is associated via its hash value and is not dependent on the given record's ordinal position within the external data source. end example]

The following XML Schema fragment defines the contents of this element:

 <complexType name="CT_HashedRecipientData">
   <sequence>
     <element name="active" type="CT_OnOff" minOccurs="0"/>
     <element name="hash" type="CT_DecimalNumber" minOccurs="1"/>
   </sequence>
 </complexType>