The MailMerge engine allows the combination of merge and form fields to be merged with data from various data sources such as JSON or IEnumerable objects. Probably the most common automation element are merge fields. These are placeholders in templates with specific names that are populated with data from various data sources. Form fields can be pre-populated using the same engine to prepare forms for users to complete. Those fields can be pre-populated or flattened.

Consider the following Patient Medical History form that is typically completed by patients:

JSON Data

The following JSON data is used to merge the above template:

[
        {
                "Doctor": "Peter Jackson M.D.",
                "Patient": [
                        {
                                "Name": "Jeanette Jo",
                                "DOB": "07/22/1981",
                                "Sex": {
                                        "M": false,
                                        "F": true
                                },
                                "Pronouns": "She/Her",
                                "History": {
                                        "head": false,
                                        "seizures": false,
                                        "eye": false,
                                        "ear": true,
                                        "pacemaker": false,
                                        "blood": false,
                                        "cholesterol": false,
                                        "diabetes": false,
                                        "anxiety": false,
                                        "fainting": false,
                                        "dizziness": false,
                                        "heart": false,
                                        "weight": false,
                                        "neck": false,
                                        "bone": false
                                },
                                "Allergies": {
                                        "allergy1": {
                                                "To": "Gluten",
                                                "Severity": {
                                                        "Mild": false,
                                                        "Moderate": true,
                                                        "Severe": false
                                                },
                                                "Reaction": "Abdominal pain"
                                        }
                                },
                                "AdditionalNotes": {
                                        "Notes": [
                                                {
                                                        "Note": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla in auctor nibh, ac suscipit ex."
                                                },
                                                {
                                                        "Note": "Sed euismod hendrerit augue nec tincidunt. Suspendisse ac massa a velit molestie mattis."
                                                }
                                        ]
                                }
                        }
                ]
        }
]

Merging Merge Fields

To increase the patient experience, to accelerate the process and to decrease errors, parts of the document can be pre-populated. In the header, the doctor's name and the current date is known and can be merged into a merge field:

Pre-Populating Form Fields

The second part consists of form fields where some data is already known and can be pre-populated:

The following code is used to merge the JSON data into the template. Pay attention to the FormFieldMergeType property being set to Preselect.

using (TXTextControl.ServerTextControl tx = new TXTextControl.ServerTextControl()) {

  tx.Create();
  tx.Load("patient_history.tx", TXTextControl.StreamType.InternalUnicodeFormat);

  using (TXTextControl.DocumentServer.MailMerge mailMerge = new TXTextControl.DocumentServer.MailMerge()) {
    mailMerge.TextComponent = tx;

    mailMerge.FormFieldMergeType = TXTextControl.DocumentServer.FormFieldMergeType.Preselect;

    string jsonData = File.ReadAllText("data.json");
    mailMerge.MergeJsonData(jsonData);
  }

}

The form fields are pre-populated, but the patient is still able to modify the form fields or to make further selections.

Flattening Form Fields

If the FormFieldMergeType property is set to Replace, the form fields are flattened and cannot be modified after the merge process:

mailMerge.FormFieldMergeType = TXTextControl.DocumentServer.FormFieldMergeType.Replace;

Conditional Merge Blocks

The third part of the template is a conditional merge section in form of a merge block. Merge blocks are removed by default when the associated data is not present in the given data source. The following screenshot shows the template loaded in the TX Text Control document editor and shows the Additional Notes section inserted as a merge block.

In case the element AdditionalNotes exists in the given JSON data (like in the above sample), the complete merge block is rendered and executed. If the element AdditionalNotes is removed from the data, the complete block is not rendered.

Download Template

You can download the demo template and JSON data for your own tests.

sample_data.zip