Generate documents from a Word template with Docx4j on Wildfly

Last Updated:  November 17, 2021 | Published: September 9, 2018

Lately, I had the requirement to generate Word documents from a template and fill them dynamically with data. For this task, I compared the following Java libraries: Apache POI, iText PDF, Docx4j, and XDocreports.  I compared them while using the following characteristics: Possibility to replace variables, amount of additional dependencies, lines of code to generate the document, and the number of releases in the last year. The winning library was Docx4j.  In this blog post, I'll show you a simple way to generate Word documents from a Word template with Docx4j using Java EE and running on Wildfly. The application will accept data through a JAX-RS endpoint, populate the document and send the generated document back as a result.

Project Setup for using Docx4j on WildFly

The pom.xml of the project looks like the following:

I am using the Docx4j library in version 6.1.2 and as this library is making use of JAXB and uses the JAXB namespace prefix mapping, I am adding an additional library to be able to use the JAXB reference implementation of Wildfly.

The Docx4j and the JAXBNamespacePrefixMapper dependencies are packed into the .war which is okay for this sample project, but for a thinner .war approach you can also add them to the Wildfly libs and mark them as provided in the pom.xml .

To be able to use the JAXB implementation of Wildfly, we need the following jboss-deployment-structure.xml under /src/main/webapp/WEB-INF:

Converting a Word Template with Docx4j

The following POJO will be used for replacing the variables in the Word document with some data:

The JAX-RS endpoint looks like this:

We validate the incoming UserInformation object using Bean Validation and pass it to the DocxGenerator for replacing the variables. This endpoint returns the media type APPLICATION_OCTET_STREAM as we are sending the raw bytes to the client. In addition, I am adding the Content-Disposition header to inform the client about the attached document.

The required code for loading the document and replacing the variables is also rather simple:

The template.docx file is loaded into a Docx4j internal object and prepared for the variable replacement. For replacing the variables I created a HashMapwhere the key is the name of the variable and the value the content. Docx4j supports three approaches for replacing variables within a .docx file:

  1. Marking variables with ${} in the document
  2. Using the Word field format MERGEFIELD
  3. Using XPath to replace the content

In this example, I am using the first approach, which is the simplest one. The template.docx looks like the following and is placed under /src/main/resources :

Downloading the Word Template

To download a generated document you can now use a REST client like Postman and store the response to the filesystem or use this cURL command:

For a simple deployment on your machine, I created the following Dockerfile:

With the JAVA_OPTS environment variable, I am adding some memory restrictions for the JVM and with the parameter -Dcom.sun.xml.bind.v2.bytecode.ClassTailor.noOptimize=true I am optimizing the performance and reducing the amount of required heap space for JAXB processing. You can find a detailed explanation for this here.

You can find the whole source code on GitHub and a detailed explanation for starting this application in the

Have fun with generating documents from a Word template with Docx4j on Wildfly,


  • This method doesn’t work properly. I mean replacing variables with:

    since one variable, for example, ${firstname} may be separated in multiple runs in the word document. So, ‘variableReplace’ method cannot find such variables which are separated in multiple runs.

    • Hi Navid,

      thanks for reaching out. I did a quick test and added a second page to the template.docx with the ${firstName} variable in addition to page one and it worked. You can also have a look at the implementation of the .variableReplace() method and see what’s happening under the hood.

      If you want, I can share the example with multiple variable replacements with you.

      Kind regards,

      • Hi Rieckpil,
        thanks for responding. Try this scenario:
        in the “${firstName}” variable in the word file, change the format of one character, for example, bold the letter N in ${firstName} and check whether this time it is replaced with the value or not.

        • Hey Navid,

          I tried it with the character ‘N’ and the whole variable in bold and it worked for me. With docx4j you have three different possible ways of replacing variables:

          1. Marking variables with ${} in the document
          2. Using the Word field format MERGEFIELD
          3. Using XPath to replace the content

          Maybe you can try a different solution

  • Hello,

    While using this I encountered an error like:
    Caused by: java.lang.NoClassDefFoundError: org/docx4j/openpackaging/packages/WordprocessingMLPackage

    I added the dependencies in pom.xml.
    I cant figure out why its not working.

  • Hey Rieckpil,

    Great exmaple!~

    I wanna inject an object into my template file like ${gender.title}, so i use this function documentPart.addObject(gender);
    but i got an error like “Caused by: javax.xml.bind.JAXBException: class ni aucune de ses superclasses n’est connue dans ce contexte.”

  • Hello I have followed your tutorial and I am running into the problem that it results in a corrupted word file. Can you help with this issue?

  • Hi there. Great blog post.
    I notice that you have a section titled “Generate the PDF file on WildFly”, but am I right in saying that you code doesn’t actually generate a PDF (it generates a docx)?
    Did you have a requirement to generate PDFs and if so, what did you use? I am using docx4j, but I’m finding PDF conversion quite tricky as all the open source libraries I have used so far have issues with formatting and layout (i.e the generated pdf, doesn’t look like the input docx).


    • Hi Lutin,

      thanks for the feedback and the hint. Indeed, the headline is misleading and should state “Document” and not PDF.

      Some years ago I also struggled to create nice-looking PDF files from a Word document as a template. I ended up with the following solution. You might use this as a proof of concept and build a more robust solution for it.

      Kind regards,

      • Thank you so much for the reply!
        I am knee-deep in researching the best solution for: docx template + data -> docx -> pdf.
        I think I’ve settled on either docx4j (or docx-stamper) for the first part, but the programmatic conversion to PDF (as you have found out), is trickier than the average joe would assume (“just open the file in word and save as PDF!”).

        Docx4j – may require a word plug-in for content control in order to support conditional and repeating elements in a doc. This plug-in (opendope) is only available for windows (mac doesn’t support content control). In addition, this approach may require XML binding.

        Docx-stamper – uses variable replacement and then comments (yes, comments!) for conditional and repeating elements. This means templates could be authored on mac (and word online). Downside to this is that it’s less mature than doxc4j and may not support advanced use cases (variable replacement inside text boxes).

        For the conversion to PDF, I was hoping to use open source tools, but all the libs I’ve tried need only support very simple docx formatting (as you also found out). LibreOffice conversion works very well (and is free to use, unlike MS), so I might leverage that. I’m thinking of either running it on an aws server (ec2) integrated as a web app, or as an aws lambda (libreoffice can be loaded as a lambda layer).

        EC2 Server – not great for scaling but good performance in terms of generation time.
        Lambda – good scaling, but cold starts (fully loading the libreoffice binaries) may be a dealbreaker.

        Anyway, thank you so much for your time.

        • Hi Lutin,

          thanks for coming back and adding the outcome of your investigations. If there’s a LibreOffice Lambda layer available and you don’t need responses within milliseconds, then the AWS Lambda solution sounds like a good plan.

          Kind regards,

  • Hello Phil, Thanks for this great post, I am using this in my project and I’m able to successfully replace the MERGEFIELD.
    but, I do also have conditional MERGEFIELD as well in my word template do you have any suggestion how can I handle conditional MERGEFIELD field e.g. {IF{MERGEFIELD sreasonPoorQuality}= “true” 254 168} a f Wingdings ?

  • {"email":"Email address invalid","url":"Website address invalid","required":"Required field missing"}