Mergefields

LabraDocs supports replacing mergefields in docx documents with user supplied data, by putting the standard docx mergefields on steroids.

Defining mergefields

Mergefields are standard docx mail merge fields which are defined in Word Mergefield creation You may name these fields as you like as long as they contain only upper and lower case characters and numbers, but we recommend using a naming convention which makes it easy to identify the fields in the docx document.

You can grab an example docx document with mergefields here.

note

Formatting of the mergefields is supported, so feel free to format the mergefields as you like.

warning

The changing the mergefield is supposed to happen in the popup window, not directly in the document.

Replacing mergefields

Mergefields are placeholders in the document which are replaced with data supplied by you, before the docx is converted into PDF/UA. The data is supplied in a JSON file, which is passed to the API endpoint. The mergefields are replaced with the data in the JSON file, which has the same name as the mergefield. Depending on which API endpoint you use, you can either supply the data in a separate JSON file or in a single JSON file.

Single file
Separate files

When sending data to the /docx2pdfua_packed endpoint, the data is supplied in a single JSON file. The JSON file contains the following fields:

{
     "template": { /* template data; see more info in the API reference*/ },
     "data": {
          "CUSTOMERNAME": "Jens Jensen",
          "CUSTOMERADDRESS": "...",
     },
     "images": [ /* image data; more about this in the API reference */ ]
}

Download an example here.

When sending data to the /docx2pdfua endpoint, the data is supplied in a separate JSON file in the following format:

{
     "CUSTOMERNAME": "Jens Jensen",
     "CUSTOMERADDRESS": "...",
}

Download an example here.

note

Mergefields are case sensitive, so make sure to use the same case in the docx document and in the JSON file.

Structured data

You are welcome to use structured data in the JSON file, which will be inserted into the docx document. The data can be nested as deep as you like, but the mergefield names must be unique and have to use "." to reference the different levels.

Example: «CUSTOMER.NAME» «CUSTOMER.ADDRESS»

{
     "CUSTOMER": {
          "NAME": "Jens Jensen",
          "ADDRESS": "...",
     }
}

note

Mergefields that are not found in the JSON file will be removed from the docx document.

In the data section beside the objects arrays are supported as well, which can be used to fill tables in the docx document. Will will cover this in the next section.

If you want to study the JSON schema, we use to validate the input, you can find it here or if you learn best by example, take a look here