How to Generate Word Documents from Data in a Workflow (No Macro Hell)

How to Generate Word Documents from Data in a Workflow (No Macro Hell)

Summary

  • Mail Merge and VBA fail for structural reasons: Finish & Merge writes plain text values and severs the data link (so updates fail silently), and macros live on a single machine with no version control or code review.
  • A declarative workflow splits the job into three inspectable, version-controlled parts: a standard .docx or .dotx template, a structured YAML/JSON data block, and plain-language generation instructions.
  • WORD_TEMPLATE_GENERATE parses the template's styles.xml before filling it, so fonts, spacing, headers, and table formatting survive; repeating rows or bullet lists need no loop syntax inside the Word file.
  • Add WORD_EXTRACT, WORD_TEXT_COMMENT, and WORD_TEXT_HIGHLIGHT to verify values and embed review flags directly in the file, giving every document in a batch its own auditable trail.
  • Start with one document type, confirm the generation step is stable, then expand. Workflows built in Jinba Flow are team-owned and deploy on-premise for regulated environments.

Generating a Word document from a spreadsheet is not a solved problem in practice. Many teams still do it manually or rely on a VBA script that only one person understands. When that person leaves, the process breaks.

The standard alternatives have material limits. Mail Merge fails when data becomes complex. Google Apps Script requires a developer to maintain it. Power Automate is another platform to configure and maintain. The actual requirement is straightforward: take a template, fill it with data, produce a file, and repeat the process.

This article shows how to do that with a workflow-based approach using WORD_TEMPLATE_GENERATE, a tool that handles Word document generation automation without macros, proprietary template formats, or single-owner scripts.

Why Mail Merge and VBA Break Down

The Mail Merge ceiling

Mail Merge works for flat, uniform data. It does not work well when records have different numbers of columns, or when the document needs nested lists, conditional sections, or repeating table rows with variable length.

When a document needs dozens of merge fields, Mail Merge becomes difficult to manage. The tool's IF field logic compounds quickly, and the output is difficult to audit.

The deeper problem is how Mail Merge handles the data link. Microsoft's own documentation confirms that the Finish & Merge function outputs plain text values, not live fields. That is by design. The connection to the source data is severed on completion. Subsequent changes to the source Excel file or CSV are not reflected in the generated document unless the entire merge is re-run. Three specific failure modes follow from this:

  • Stale data: The tool caches the data source, so edits made after the merge are silently ignored.
  • Blocked updates: Unaccepted tracked changes in the template can prevent fields from updating.
  • Unpredictable behaviour: Mixed field-code states cause Word to behave inconsistently across runs.

These failures are silent; the document looks complete, but the values may be wrong.

The VBA continuity problem

VBA scripts can automate document generation effectively. Teams have used them to produce reports in batch for years. The constraint is ownership.

A VBA macro typically lives in a single workbook on a single machine. It is not version-controlled. It does not go through code review. When the person who wrote it leaves, other team members cannot confidently modify it. The script becomes a dependency the team maintains by leaving it unchanged, until it fails.

A workflow-based approach separates the template, the data, and the generation logic into distinct, inspectable artifacts. Each can be edited independently. The process is team-owned.

A Declarative Approach to Document Generation

The model used here keeps three things separate: the template file (.docx or .dotx), the structured data (YAML or JSON), and the generation instructions passed to the tool. None of these are combined in a macro.

The tool at the centre of this approach is WORD_TEMPLATE_GENERATE. It takes a Word template, a set of natural-language instructions, and a structured data block. It uses an LLM to parse the template's structure, including its styles, and fills the document accordingly; this is more than a simple find-and-replace.

This matters because Word formatting is carried by four style types: paragraph, character, table, and numbering definitions. As the python-docx documentation explains, only the styles actually defined in a document's styles.xml are available for use. A script that attempts to apply a built-in style not yet defined in that file will fail silently. WORD_TEMPLATE_GENERATE analyses the available styles before filling content, which means the output preserves the template's fonts, spacing, headings, and table formatting exactly.

Templates remain standard .docx files, editable in Word. Libraries like docxtemplater rely on the same standard format, so there is no proprietary format to learn, and no vendor lock-in.

Step-by-Step: Generating a Word Document from Data

Step 1: Prepare the template

Open any Word document and identify where dynamic content will appear. Insert plain placeholder text such as {client_name}, {report_date}, or {project_title}. For repeating content like table rows or milestone lists, format one example row or list item in the template. The workflow tool handles repetition from the structured data; no loop syntax is required inside the Word file.

Save the file as a .docx for a filled-in document or .dotx for a reusable template type.

Step 2: Define the workflow step in YAML

The generation step is declared in a YAML file. This makes the entire operation readable, version-controllable, and reviewable. The data block accepts both scalar values and structured lists, which maps directly to table rows and bullet lists in the output.

steps:
- name: generate_project_report
tool: WORD_TEMPLATE_GENERATE
# Path to your Word template file
template: "templates/ProjectStatusReport.docx"
# Natural language instructions for the LLM
instructions: |
Fill the template using the provided structured data.
Replace {client_name} with the client name from the data.
Replace {project_title} with the project title from the data.
Replace {report_date} with the report date from the data.
Under the 'Project Milestones' heading, create a bulleted list
from the 'milestones' array.
Find the table with header row 'Description, Qty, Unit Price, Total'
and populate it with the 'line_items' data.
# Structured data to populate the template
data:
client_name: "Innotech Global"
project_title: "Quantum Leap Initiative"
report_date: "2024-11-15"
milestones:
- "Q1: Initial research and feasibility study complete."
- "Q2: Prototype development and internal review."
- "Q3: Alpha testing with key partners."
line_items:
- description: "Phase 1: Research"
quantity: 120
unit_price: 180.00
- description: "Phase 2: Prototyping"
quantity: 250
unit_price: 220.00
- description: "Cloud Infrastructure"
quantity: 6
unit_price: 1500.00
# Output file path
output: "output/reports/Innotech_Report_2024-11-15.docx"

The milestones list maps to a bulleted list in the document. The line_items array populates table rows. Both are handled through the instructions field in plain language, with no syntax required inside the template itself.

Step 3: Run the workflow and review the output

The output is a standard .docx file. The process edits the document's existing XML structure, so the original styles, headers, footers, and page layout are preserved. The file is immediately openable in Word, shareable, and ready for further processing.

Building a Full Review Pipeline

Generation is one step. A production-grade workflow for Word document generation automation also includes verification and annotation.

Three companion tools extend the pipeline:

  • WORD_EXTRACT pulls text from the generated .docx file programmatically. Use it to verify that values in the output match the source data, or to extract figures for downstream processing.
  • WORD_TEXT_COMMENT adds native Word comments to the document. As the python-docx documentation describes, comments can be attached to a range of text with author, initials, and date metadata, making them indistinguishable from manually added review notes. A workflow step can flag specific values for human review without altering the document content itself.
  • WORD_TEXT_HIGHLIGHT applies colour highlights to specific text ranges. Use it to draw attention to key figures, threshold breaches, or sections that require sign-off before distribution.

Together, these tools support a self-annotating document pattern. The workflow generates the document and then inspects it, making errors visible. If a calculated total falls below a threshold, a WORD_TEXT_COMMENT step can insert a comment reading "Warning: revenue below target for this period" directly into the file. The reviewer opens one document and sees both the content and the flags.

This mirrors the approach taken by libraries like docxtemplater, whose error location module can convert template rendering problems into Word comments in the output file, so debugging remains visible and collaborative in the document.

The result is an auditable trail. Every document in the batch carries its own review state, embedded in the file format that the team already uses.

What to Do Next

The choice is between maintaining a fragile, single-owner process and building one the team can inspect, modify, and hand off.

Start with a single document type: a report, a proposal, or a contract that currently requires manual population. Convert it to a .docx template with placeholder text, define the data structure in YAML, and run WORD_TEMPLATE_GENERATE against it. Once the base generation step is stable, add WORD_EXTRACT to verify the output and WORD_TEXT_COMMENT to surface any anomalies that need human review.

The template, the YAML, and the workflow definition are all files. They live in version control, they are reviewable, and they do not depend on who built them.

Frequently Asked Questions

How do I automatically generate a Word document from spreadsheet data?

Use a Word template with placeholder fields, define the record as structured YAML or JSON, and run a generation tool such as WORD_TEMPLATE_GENERATE to fill the template and save a standard .docx file.

The workflow has three parts: the .docx or .dotx template, the structured data block, and a short set of natural-language instructions describing what goes where. Teams declare the step in YAML, point it at the template and the data, and specify an output path. No macro, add-in, or manual copy-paste step is involved.

Why does Mail Merge stop updating when the source data changes?

Mail Merge severs the connection to the data source when Finish & Merge runs, writing plain text values into the document instead of live fields.

That behaviour is by design, as Microsoft's own documentation confirms. Once the merge completes, later edits to the Excel file or CSV are not reflected in the generated document unless the entire merge is re-run. The practical symptoms are stale values, fields that do not update because of unaccepted tracked changes, and inconsistent behaviour from mixed field-code states. These failures are silent: the document looks finished, but the numbers may be wrong.

Can I generate Word documents without VBA macros?

Yes. A declarative workflow separates the template, the data, and the generation instructions into independent, version-controlled files, so no VBA macro is required.

This matters primarily for ownership. A VBA script usually lives in one workbook on one machine, is not version-controlled, and rarely goes through code review. When its author leaves, the team inherits a process that no one can safely modify. A workflow definition in YAML is readable, reviewable, and team-owned.

What is WORD_TEMPLATE_GENERATE and how does it work?

WORD_TEMPLATE_GENERATE is a workflow tool that fills a standard Word template using natural-language instructions and a structured data block, then writes the result to a .docx file.

It uses an LLM to parse the template's structure, including its styles, and fills the document accordingly; the operation is more than a simple find-and-replace. It accepts both scalar values and structured lists, which map directly to table rows and bullet lists in the output. The generated file is a normal Word document, ready to open, share, or process further.

Do I need a proprietary template format?

No. Templates remain ordinary .docx or .dotx files that are edited directly in Word, using plain placeholder text such as {client_name}, {report_date}, or {project_title}.

There is no special syntax to learn and no vendor lock-in. The approach relies on the same open standard format used by libraries such as docxtemplater, so the template stays portable and readable outside the workflow.

How do I create repeating table rows or bullet lists in a Word template?

Format one example row or list item in the template, supply the repeating values as an array in the data block, and describe the mapping in the instructions.

For example, a milestones array becomes a bulleted list under a "Project Milestones" heading, and a line_items array populates the rows of a table with headers "Description, Qty, Unit Price, Total". No loop syntax is required inside the Word file itself; the repetition is handled from the structured data and the plain-language instructions.

Will the generated document keep my template's fonts, spacing, and table formatting?

Yes, as long as those styles are defined in the template's styles.xml, which the tool analyses before filling content.

Word formatting is carried by four style types: paragraph, character, table, and numbering definitions. Only styles actually defined in a document's styles.xml are available for use, and a script that tries to apply an undefined built-in style will fail silently. Because WORD_TEMPLATE_GENERATE inspects the available styles first, the output preserves the template's headings, fonts, spacing, headers, footers, and page layout.

How can I verify that a generated Word document is correct before sending it?

Add a verification step using WORD_EXTRACT to pull the text from the generated .docx and compare key values against the source data.

WORD_EXTRACT reads the output programmatically, so teams can check that totals, names, and dates match the input, or extract figures for downstream processing. Teams can combine it with WORD_TEXT_COMMENT to insert native Word comments flagging any value that needs human review. The reviewer then opens a single document that contains both the content and its flags, creating an auditable trail for every file in the batch.

Can comments and highlights be added to generated Word documents automatically?

Yes. WORD_TEXT_COMMENT inserts native Word comments with author, initials, and date metadata, and WORD_TEXT_HIGHLIGHT applies colour highlights to specific text ranges.

Comments added this way are indistinguishable from manually added review notes, so a workflow can flag a threshold breach, a missing approval, or a figure requiring sign-off without altering the document's content. This supports a self-annotating document pattern: generate the file, inspect it, and embed the review state directly in the format the team already uses.

What skills does a team need to maintain this workflow?

Basic familiarity with Word templates and YAML is enough; no VBA or scripting expertise is required.

The template, the data block, and the workflow definition are all plain files. They live in version control, they are reviewable in a pull request, and they do not depend on who built them. A sensible rollout is to start with one document type, confirm the generation step is stable, and then add WORD_EXTRACT for verification and WORD_TEXT_COMMENT for anomaly flagging.

人馬一体のワークフロー構築を体験せよ

エンタープライズ組織を支えるAI基盤

無料で始める