TX Text Control .NET for WPF

Mail Merge

Topic

A mail merge with MailMerge rarely fails with an error. More often, it succeeds and the result isn't what you expected: a field is empty or gone, a block isn't repeated, or a date has the wrong format. The problems below start from what you see in the merged document. Merge Data into Fields shows a working merge to compare with.

A Merge Field Disappears or Stays Empty

A merge field of the template isn't in the merged document, or it is there without a value.

MailMerge fills a field from the column or property whose name matches the name of the field, at the level of the data the field is in; fields of child data use dot notation, such as address.street. When no column matches, the field gets no value, and because RemoveEmptyFields is true by default, it is removed. With business objects, the property names are the field names, and the first object of a collection defines the structure: objects of other types leave some fields empty.

  1. Set RemoveEmptyFields to false, so that fields without data stay in the document and you can see which ones they are.
  2. Handle FieldMerged. It tells you with Merged whether a field got a value.
  3. Correct the field name in the template or the column name in the data.

Show a Text for Fields Without Data shows a FieldMerged handler that marks the fields without data. The blog article MailMerge: Field Mapping and Handling of Unmerged Fields describes the mapping in detail.

Empty Lines Remain Where Fields Had No Data

An address or a list has blank lines where fields without data were.

Removing an empty field doesn't remove the line it was on.

  1. Keep RemoveEmptyFields at true.
  2. Set RemoveEmptyLines to true, which removes lines that are empty after the merge. Its default is false.
  3. For images without data, set RemoveEmptyImages to true.

A Merge Block Isn't Repeated or Disappears

A section of the template that should repeat for each record appears once, with empty fields, or it is missing from the result.

A merge block is a subtext part whose name starts with the prefix that MergeBlockNamePrefix returns, txmb_. The rest of the name must match the name of the table, or of the collection property of a business object, that holds the records. A block without data is removed, because RemoveEmptyBlocks is true by default. In a template from Microsoft Word, blocks are bookmarks, which are loaded as subtext parts only on request.

  1. Check that the block name starts with txmb_ and that the rest matches the name in the data, for example txmb_Items for a property Items.
  2. If the block disappears, check that the data contains records for it, or set RemoveEmptyBlocks to false to see the empty block.
  3. When you load a Word template into the editor, set LoadSettings.LoadSubTextParts to true, as Document Conversion describes.

Add Repeating Merge Blocks shows a working block. The blog article MailMerge: Removing Empty Blocks explains the removal.

Numbers or Dates Are Parsed or Formatted Wrongly

A date or a number in the merged document is wrong, or it has the format of another country.

Values in the data are parsed with one culture and formatted in the document with another. DataSourceCulture is the culture that reads numbers and dates from the data, and MergeCulture the culture that formats them in the document. Both default to the culture of the current thread, which differs between machines.

  1. Set DataSourceCulture to the culture your data is written in.
  2. Set MergeCulture to the culture the document should show.
  3. Merge again.

Parse Numbers and Dates With the Right Culture shows the code.

MergeJsonData Throws a ParserException

MergeJsonData throws an exception derived from ParserException.

The JSON string isn't valid, or it doesn't have the shape MergeJsonData expects: a single object or an array of objects with the same structure. The derived class tells you what is wrong; Merge JSON Data lists the classes and their causes.

  1. Catch ParserException around MergeJsonData and log the type of the exception.
  2. Validate the JSON, and make sure it is one object or an array of objects with the same structure.

Merge Throws a MergeCanceledException

The merge stops with a MergeCanceledException.

Your code canceled the merge: the exception is thrown when a handler of DataRowMerged sets Cancel to true, for example when a user stops a long merge.

  1. Catch MergeCanceledException where you call the merge method, and treat it as a canceled merge, not as an error.

LoadTemplate Returns False

LoadTemplate returns false, and the merge has no template.

The template is invalid or couldn't be loaded.

  1. Check the path and the format you pass to LoadTemplate.
  2. Open the template in the editor to see whether it loads there. Document Conversion describes the errors of loading.

The Merged Document Has the Wrong Page Size or Margins

The merged document has the page size and margins of the editor, not those of the template.

UseTemplateFormat is false by default. Then the merged document gets the page size and margins of the TextComponent that MailMerge works with, not those of the template.

  1. Set UseTemplateFormat to true to keep the page format of the template.

Loading a Data Source Configuration File Throws an Exception

DataSourceManager.LoadDataSourceConfig or SaveDataSourceConfig throws an exception in your WPF application.

Data source configuration files can only be used in Windows Forms applications. Called from a WPF application, these methods throw an exception.

  1. Provide the data in code instead, for example as a DataSet, as business objects or as JSON, and pass it to the merge method.

Merged Content or Images Disappear in an Earlier Service Pack

After a merge, table cells lose their content, or merged images lose their ID and name, although the data contains values for them.

The service packs of version 34.0 fixed several merges that removed content. The Known Issues page of version 34.0 lists, among others, these fixes:

Fixed inWhat went wrong in the merge
Service Pack 1A memory leak in the MailMerge class, and a table header shown above a table cell with a formula
Service Pack 5Merged content was removed when RemoveEmptyLines was used inside table cells, a merge removed the complete content of a table cell, and images lost their ID and name
  1. Read the service pack your application runs with from VersionInfo.ServicePack.
  2. Install the latest service pack, update TXTextControl.TextControl.WPF.SDK to 34.0.5 and rebuild the application.
  3. If the problem remains, check the open issues on the Known Issues page. It lists as open, for example, that SaveDocumentToMemory doesn't work with documents whose merge block bookmarks are in invalid positions.

Related Pages