Jetformat

Word templates versus mail merge

Choose the filling command from the structure of the Word template. Similar-looking placeholders can use three different mechanisms.

Published · 5 min read

By Jetformat

Word template filling is the replacement of values in structured fields in an existing DOCX. Jetformat uses different commands for content controls, MERGEFIELD codes, and legacy form fields, so choose the command from the template structure rather than its visible labels.

Compare the three mechanisms

Template structure Command What identifies a value
Content control word template Tag or Alias
MERGEFIELD code word mail-merge Merge field name
Legacy form field word fill-fields Legacy field name

A printed label such as “Customer” does not tell you which mechanism the author used. Inspect the template before automating a batch. Replacing visible strings blindly can change ordinary prose while leaving the actual field unresolved.

Identify the source before filling it

Run jetformat word inspect letter.docx --json to examine structure. Use jetformat word form-fields letter.docx when the document is expected to contain legacy fields. Keep a pristine template and write each result to a new path.

For a content control tagged customer, the workflow is:

jetformat word template letter.docx --set customer="Acme Corp" -o filled.docx
jetformat text filled.docx --format markdown

For a MERGEFIELD named Customer, use word mail-merge instead. Preserve field name case. A batch should record which template revision and input values produced each output, without putting private customer data into public logs.

Verify both values and layout

Extracted text helps find unresolved placeholders and incorrect values. It cannot show that a long customer name wrapped into a signature block. Convert a representative filled document to PDF, then inspect a rendered page before processing the remaining records.

Use content-control filling, mail merge, or legacy field filling for the exact command. If an output contains the right words but looks wrong, follow the font and layout checks.

Prepare one representative record

  1. Keep an unchanged copy of the template and identify its filling mechanism.
  2. Collect the exact field identifiers and preserve their case.
  3. Prepare one record containing a long name, a typical value, and any optional blank values the workflow permits.
  4. Fill a new DOCX, extract its text, and compare every required value with that record.
  5. Convert the filled file and visually inspect wrapping before processing more records.

Treat a missing identifier as an input or template problem. Adding a second spelling to the data does not explain which field was actually filled. Maintain one explicit mapping between each source value and the intended template field.

Account for each resulting document

In an illustrative job, filling one template uses 1 credit. If its PDF conversion produces 8 pages, that step uses 8 credits. Rendering 2 pages to inspect long names adds 2 credits, for 11 credits total. Text extraction adds no credits. A longer value can change pagination, so the sample’s page count is an estimate for later records, not a fixed batch rate.

Diagnose an unresolved placeholder

If the output contains the original placeholder, first check whether the selected command matches the field mechanism. Then compare identifiers and inspect whether the source template changed. If the expected words are present but overlap a footer, investigate layout and fonts instead of changing the field mapping.

Keep the template revision and record identifier with the job result, but avoid putting private values into public logs. A failed record should be identifiable and retryable without replacing previously reviewed outputs. The batch pipeline guide applies the same principle across many documents.

Last updated