Create Word documents using templates in Python

Nutrient Document Converter Services (DCS) can generate new Word documents by filling in Word template files. This approach is ideal for automating document creation tasks such as:

  • Generating contracts with client-specific details
  • Creating invoices with dynamic pricing and customer information
  • Producing reports with data from databases or APIs
  • Filling out forms programmatically

A Word template is a .docx file that includes placeholders. The placeholder format is defined in a template model.

The template model is a JSON structure that defines:

  • A config section to specify the placeholder delimiters
  • A model section containing one or more placeholder–value pairs

You can provide the template model as an external JSON file or construct it programmatically.

Prerequisites

Before following this guide, ensure you have:

  • Python 3.x installed on your system
  • The Zeep library installed (pip install zeep)
  • Nutrient Document Converter Services running locally on port 41734
  • A Word template file (.docx) with placeholders
  • A JSON file containing the data to fill the template

For initial DCS setup with Python, refer to the using Document Converter Services with Python guide.

Sample model

The following model is used in the sample:

{
  "config": {
    "delimiter": {
      "start": "{{",
      "end": "}}"
    }
  },
  "model": {
    "name": "Jules Winnfield",
    "invoicenumber": "90121",
    "paymentdue": "28/09/2020",
    "grandtotal": "81.00",
    "yourname": "Johan Schmidt",
    "yourposition": "Finance department",
    "yourcontactdetails": "Systems testing"
  }
}

Sample Word template

Word template showing placeholders for name, invoice number, payment due date, and contact details

Sample code

You can run this code in any Python environment with access to the Zeep library(opens in a new tab).

The Zeep library enables interaction with Web Services Description Language (WSDL), which defines how to call the web services and describes the data structures returned. Nutrient Document Converter Services (DCS) provides these WSDL definitions for document processing operations.

To examine the WSDL obtained using the Zeep tool, use the code snippet below:

import zeep
import base64


print("Filling/creating Word documents using Word templates")
#Service URL.
service_url = "http://localhost:41734/Muhimbi.DocumentConverter.WebService/"
# WSDL URL.
wsdl_url = service_url+"?WSDL"


# Source file.
templateFile = "testtemplate.docx"
dataFile = "invoicereminder.json"


# Construct the header.
header = zeep.xsd.Element(
    "Header",
    zeep.xsd.ComplexType(
        [
            zeep.xsd.Element(
                "{http://www.w3.org/2005/08/addressing}Action", zeep.xsd.String()
            ),
            zeep.xsd.Element(
                "{http://www.w3.org/2005/08/addressing}To", zeep.xsd.String()
            ),
        ]
    ),
)
# Create a heading object.
header_value = header(Action=service_url,To=service_url)
# Create client.
client = zeep.Client(wsdl=wsdl_url)


# Load the template file as a Base64 string.
with open(templateFile, "rb") as image_file:
    encoded_template_string = base64.b64encode(image_file.read()).decode('utf-8')


# Load the template file as a string.
with open(dataFile, "rb") as data_file:
    datafile_string = data_file.read()


# Create a factory type to construct objects with the suffix ns2 (see the WSDL).
factory = client.type_factory("ns2")


# Create the OpenOptions object with the minimum settings.
open_options = factory.OpenOptions(OriginalFileName = dataFile, FileExtension = "json")


# Call the service.
result = client.service.FillWordTemplate(encoded_template_string, open_options, datafile_string)


# Write the filled template file.
with open("FilledTemplate.docx", "wb") as f:
  f.write(result.File)


print("Done")

Troubleshooting

Connection error: Cannot connect to DCS service

  • Ensure DCS is running on localhost:41734
  • Check that no firewall is blocking the connection
  • Verify the service URL in your code matches your DCS installation

Template processing error: Invalid placeholders

  • Verify that placeholders in your Word template match the JSON model keys exactly
  • Ensure placeholder delimiters in the JSON config match those used in the template
  • Check that the Word template file is accessible and not corrupted

JSON data error: Invalid JSON format

  • Validate your JSON file syntax using an online JSON validator
  • Ensure all string values are correctly quoted
  • Check for trailing commas or missing brackets

File access error: Permission denied

  • Verify that Python has read access to the template and JSON files
  • Check that the output directory has write permissions
  • Ensure files aren’t locked by other applications

What’s next

Now that you can create Word documents from templates, explore these related DCS capabilities: