Generate Office documents

This guide explains the process of populating Office templates with data. Document Engine supports Word (.docx), PowerPoint (.pptx), and Excel (.xlsx) templates. The processed file is returned in the same Office Open XML format as the input template. Word output can then be converted into a PDF document.

This is useful for automatically generating documents like invoices, contracts, reports, or letters where the layout stays the same but the content changes based on your data.

Populating Office templates with data and converting Office files into PDF documents require special licenses. Contact Sales for more information.

General principles

Office templating consists of the following elements:

1. A .docx, .pptx, or .xlsx file that will be used as the template.
2. A template model that contains the placeholder values to replace in the Office template.
3. Configuration for the template model.

Supported template formats

Document Engine supports these Office template formats:

• Word (.docx) templates support placeholders, loops, and dynamic tables.
• PowerPoint (.pptx) templates support placeholders, loops, conditions, tables, and images on slides. Slide masters, slide layouts, and speaker notes aren’t processed.
• Excel (.xlsx) templates process every worksheet and support placeholders, conditions, row loops, images, and typed number, date, percentage, and Boolean cells. Column loops and list expansion within a single cell aren’t supported. Formula references, structured table ranges, and defined names aren’t adjusted when row loops insert rows.

Use the same /api/process_office_template endpoint for all supported template formats. To populate an Excel template, upload an .xlsx file and write the response to .xlsx:

curl -X POST http://localhost:5000/api/process_office_template \
  -H "Authorization: Token token=<API token>" \
  -F "document=@invoice-template.xlsx" \
  -F "model=<invoice-model.json;type=application/json" \
  --output result.xlsx

Template model

The template model must contain:

1. A configuration containing both a start and end delimiter. The default delimiters are { and }, and both can be configured in the request.
2. At least one placeholder-value pair. The placeholder name must correspond to the placeholder defined in the Office template.

Use config.delimiter.objectDelimiter when model keys contain dots and you need a different separator for nested properties.

Populating a document

Document Engine supports replacing placeholder text strings, automatic reflow, loops, and dynamic tables.

Text replacement

Consider the following DOCX content:

Hello my name is {name}.
There is {more}.

Use the following model:

"model": {
  "name": "Petey Eff",
  "more": "lorem ipsum dolor sit amet."
}

The output DOCX document will be:

Hello my name is Petey Eff.
There is lorem ipsum dolor sit amet.

Loops

Consider the following DOCX content:

{ledger}:
{#items} {name} {price} {/items}

Here, items is the name of the loop, and name and price are placeholders for repetitive elements. Consider the following model:

"model": {
  "ledger": "Tom's groceries",
  "items": [
    { "name": "A", "price": 10 },
    { "name": "B", "price": 15 }
  ]
}

The outcome in the output DOCX document will be:

Tom's groceries:
A 10
B 15

Request example with custom delimiters

This example demonstrates dynamically populating a DOCX template with custom delimiters ({{ and }}) using a request to the /api/process_office_template endpoint:

curl -X POST http://localhost:5000/api/process_office_template \
  -H 'Authorization: Token token=<API token>' \
  -H 'content-type: multipart/form-data' \
  -F 'document=@/path/to/template.docx'
  -F 'model={
    "config": {
      "delimiter": {
        "start": "{{",
        "end": "}}"
      }
    },
    "model": {
      "placeholder": "replacement value",
      "loop-name": [
        {
          "placeholder-within-loop": "replacement value",
          "another-placeholder-within-loop": "replacement value 2"
        },
        {
          "placeholder-within-loop": "another replacement value",
          "another-placeholder-within-loop": "another replacement value 2"
        }
      ]
    }
  }' \
  --output result.docx

POST /api/process_office_template HTTP/1.1
Authorization: Token token=<API token>
Content-Type: multipart/form-data; boundary=customboundary

--customboundary
Content-Disposition: form-data; name="document";

template-document
--customboundary
Content-Disposition: form-data; name="model";
Content-Type: application/json

{
  "config": {
    "delimiter": {
      "start": "{{",
      "end": "}}"
    }
  },
  "model": {
    "placeholder": "replacement value",
    "loop-name": [
      {
        "placeholder-within-loop": "replacement value",
        "another-placeholder-within-loop": "replacement value 2"
      },
      {
        "placeholder-within-loop": "another replacement value",
        "another-placeholder-within-loop": "another replacement value 2"
      }
    ]
  }
}
--customboundary

Understanding the above example

Consider a DOCX template with the following content:

Invoice for: {{customer}}

Products:
{{#products}}
{{name}} - ${{price}}
{{/products}}

Use the following model:

"model": {
  "customer": "Acme Corporation",
  "products": [
    { "name": "Widget A", "price": "29.99" },
    { "name": "Widget B", "price": "49.99" }
  ]
}

The output DOCX document will be:

Invoice for: Acme Corporation

Products:
Widget A - $29.99
Widget B - $49.99