Text Control's MailMerge API maps merge fields in MS Word compatible templates with data columns (fields) in supported data sources. During the merge process, the field name in the template is compared to the column names of merged data in the applicable hierarchy level.

The following illustration shows how merge field names are mapped to hierarchical data.

company_name comes from the root table directly while the address is coming from a child table. These fields can be accessed using the "dot notation". For example, to access the street, the merge field name is address.street.

Learn More

MailMerge: Data Structures Explained with a Sample Template and JSON Data

Read Article

Removing Empty Fields

But what is happening to a field in case an appropriate column name cannot be found in the given data source?

By default, empty fields are removed. This behavior can be controlled by setting the RemoveEmptyFields property.

The following sample template contains 3 fields while the third field MERGEFIELD doesn't have an associated data field in the used sample JSON data source.

In the resulting document, the third field is removed:

In the following code, a new instance of the MailMerge class is created and the RemoveEmptyFields is set to false, so that empty fields are not removed from the document.

string jsonData = System.IO.File.ReadAllText("data.json");

using (MailMerge mm = new MailMerge() { TextComponent = textControl1 }) {
  mm.RemoveEmptyFields = false;
  mm.MergeJsonData(jsonData);
}

Handling Empty Fields

For each merged field, the FieldMerged event can be used to map the field to another data column or to set custom text. The following code attaches the event to the MailMerge instance. The RemoveEmptyFields property must be set to false to handle those empty fields.

string jsonData = System.IO.File.ReadAllText("data.json");

using (MailMerge mm = new MailMerge() { TextComponent = textControl1 }) {
  mm.FieldMerged += Mm_FieldMerged;
  mm.RemoveEmptyFields = false;
  mm.MergeJsonData(jsonData);
}

In the event handler, the text of the unmapped field is changed.

private void Mm_FieldMerged(object sender, MailMerge.FieldMergedEventArgs e) {
  if (e.Merged == false) {

    if (e.MailMergeFieldAdapter.TypeName == "MERGEFIELD") {
      MergeField mf = new MergeField(e.MailMergeFieldAdapter.ApplicationField);
      mf.Text = "[Field not merged!]";
    }

  }
}

The unhandled field contains the custom text after the merge process.

In case there is a mismatch, this event can be also used to add custom mapping lists or dictionaries that represent the mapping between names in the given data source and merge fields in the template.

Removing Empty Paragraphs

In case a paragraph contains only unhandled merge fields and becomes empty during the merge process, the resulting empty line might not be wanted in the resulting document. These empty lines can be removed automatically by setting the RemoveEmptyLines property.

string jsonData = System.IO.File.ReadAllText("data.json");

using (MailMerge mm = new MailMerge() { TextComponent = textControl1 }) {
  mm.FieldMerged += Mm_FieldMerged;
  mm.RemoveEmptyFields = true;
  mm.RemoveEmptyLines = true;
  mm.MergeJsonData(jsonData);
}