Office-stamper

Introduction

Office-stamper is a Java template engine that allows for dynamic creation of DOCX documents at runtime. It requires Java 17+ (Maven release set to 25). You design a template using your preferred Word processor; and office-stamper will generate documents based on that template.

Key Features

• Expression-based templating: Use Spring Expression Language (SpEL) for powerful template expressions.

• Comment-based processing: Add special instructions as comments in your Word documents.

• Formatting preservation: All formatting from the original template is preserved.

• Custom functions: Extend the templating capabilities with your own functions.

• Image deduplication: Automatically reuse identical images in the document to prevent file bloating.

• Type-safe: Strong typing for Java integration.

• Flexible configuration: Customize the behavior to suit your needs.

Quick Start

void main() {
    var context = new YourPojoContext(_, _ , _);
    var stamper = OfficeStampers.docxStamper();

    try(var template = Files.newInputStream(Paths.get("template.docx"));
        var output = Files.newOutputStream(Paths.get("output.docx"))) {
        stamper.stamp(template, context, output);
    }
}

If you already have a WordprocessingMLPackage (Docx4J document), use docxPackageStamper:

var stamper = OfficeStampers.docxPackageStamper(OfficeStamperConfigurations.standard());
WordprocessingMLPackage stamped = stamper.stamp(document, context);

Want to understand the architecture? Read the v3 overhaul story on the blog.

Configuration Presets

Office-stamper provides three main configuration presets in OfficeStamperConfigurations to help you get started quickly:

• minimal(): Base engine with placeholder preprocessors.

• standard(): Recommended. Adds common comment processors (repeat, displayIf, replaceWith) and date/time formatting.

• full(): Adds cleanup for language information and orphaned notes.

You can create a configuration via one of these presets and then further customize it:

var configuration = OfficeStamperConfigurations.standard()
    .addResolver(new MyCustomResolver());

Security Modes

Office-stamper is secure-by-default. SpEL evaluation runs in a restricted mode, and SVG parsing uses a hardened XML parser.

You can opt into a permissive mode for trusted templates:

import pro.verron.officestamper.api.SecurityMode;

void main(){
    var cfg = OfficeStamperConfigurations.standard()
        .setSpelSecurityMode(SecurityMode.PERMISSIVE)
        .setSvgSecurityMode(SecurityMode.PERMISSIVE);
}

Control modes via system properties:

• -Dofficestamper.spel.mode=restricted|permissive

• -Dofficestamper.svg.mode=restricted|permissive

Maven Coordinates

<dependency>
    <groupId>pro.verron.office-stamper</groupId>
    <artifactId>engine</artifactId>
    <version>3.5</version>
</dependency>

<!-- You also need to provide a dependency to Docx4J -->
<dependency>
    <groupId>org.docx4j</groupId>
    <artifactId>docx4j-core</artifactId>
    <version>11.5.13</version>
</dependency>
<dependency>
    <groupId>org.docx4j</groupId>
    <artifactId>docx4j-JAXB-ReferenceImpl</artifactId>
    <version>11.5.13</version>
</dependency>

Documentation

Comprehensive documentation is available at https://office-stamper.verron.pro.

What’s New

For the latest changes and migration guides, please refer to:

• Release Notes – detailed changelog for each version.

• 3.x Update Guide – rationale and migration guidance for the v3 overhaul.

Modules

This repository is structured into several modules:

• Engine – core templating engine and public API

• Utils – low-level utilities

• AsciiDoc – AsciiDoc to DOCX integration

• CLI – command line interface

Sample Code

Check the source code for tests showing how to use the features. Run them with mvn test. Template .docx files used in tests are located in the sources subfolder.

Who Uses This?

Office-stamper is used in production for document automation in the energy sector in China, where strict schema compliance and security constraints are non-negotiable. If your team uses office-stamper, feel free to open an issue or PR to add yourself to this list.

Author

Office-stamper is crafted and maintained by Joseph Verron. Follow the stories behind the code on the blog.

Contributing

Contributions are welcome! See the Contributing Guide for details on how to contribute to Office-stamper.

License

Office-stamper is released under the MIT License.