In our previous article, we gave a helicopter view of how we built a custom document generation solution based on a microservice architecture. In this article, we want to delve into more details showing how an individual microservice responsible for generating documents works.
Business document generators are a common feature in applications, especially those belonging to the Line of Business (LOB) type. Every application has its own way of approaching document generation. In some, a document is generated based on built-in settings and templates. Others have template editors that allow users to easily and quickly modify documents to be generated.
A document generator—defining the requirements
When building a custom document generation solution for one of our clients, we started by defining the requirements for the generator. They were as follows:
- The document template editor should be easy to use.
- It should handle two popular file types: DOCX and PDF.
- No need to install MS Word on a machine with the document generation system installed.
- It should handle multiple items in a document (e.g., a table with multiple rows based on data sent).
- It should work fast.
- It should work in any business domain, so that it can be used in any project without the need to make changes to it.
- The data needed to generate a specific document are sent via XML file.
- The price for external components (a PDF converter) should not have a negative impact on the overall cost of the solution.
Document generator—how it works
The solution we prepared worked as follows:
- We define an XML structure that contains all the data needed to populate the template.
- Based on the XML file, we create a document template, assign a code to it and load it into the document generator database.
- A target application communicates with the document generator via an event bus or REST API sending an XML file with data as well as a template code, and defining what the required document format is: DOCX or PDF.
- The generated document is sent back using the same communication channel that was used to send the request for document generation.
A document generator template
As a document editor, we chose MS Word, which is a commonly used tool among enterprises. Additionally, it has a built-in option to prepare templates.
To create a document template, we need to prepare an XML file with the data structure that will be sent in reply to a document generation request. The structure should contain the data of the document that needs to be generated. Of course, the structure will depend on the application domain. For an accounting app, it could be a structure to create a new invoice, e.g.:
InvoiceDate DueDate InvoiceNumber NameAddress PostalCity No Title Amount
Such a structure can be prepared by either the developers working on an application or by business analysts. In the latter case, programmers will need to write code allowing the application to send data to a document generator that conform with the XML structure.
Once the XML file is ready, we can start working in MS Word. First, we need to activate the “Developer” ribbon.
- In MS Word, Click File à Options.
- In the dialog window “Word options,” click “Customize ribbon,” and next select the “Developer” ribbon (see Fig. 1 below).
Fig 1. Customizing the ribbon in MS Word
The next step is to activate the “XML mapping” windows and to load an XML file with the document structure. See Fig. 2 below:
Fig. 2. The XML mapping window
Now everything is set up and we can start working with a document template.
In the place where the data coming from the app should be inserted (1), we put a cursor, while in the mapping window (2, 3), we choose an XML tag describing the type of data to be inserted—see Fig. 3 below:
Fig. 3. Inserting XML tags in the document template
The file prepared in this way needs to be sent to the template database of the document generator.
In an ideal scenario, it would be good to design and build a web pane allowing users to manage/edit/update document templates directly in the app that sends document generation requests.
Document generation process
To generate DOCX documents, we used the OpenXML library developed by Microsoft. The final document creation step involves loading XML data into the structure of a DOCX document, and it takes no time to complete.
The target document formats are both DOCX and PDF. In the case of the former, the process ends after loading XML structure in the document, and the generated document is sent back to the services that sent the request.
If a target file should be in the PDF format, there is a conversion step in between. To do this, we used the Spire.Doc for .NET library. We chose it for two main reasons. First, it handles files with XML metadata well. Second, it does not require the installation of any additional components on the server to work.
A custom document generator based on microservices—summary
We build our document generator using .NET 6.0 technology. It has both a REST API interface and communicates with an event bus to receive document creation requests and to publish generated files.
In order to communicate with the template database, we use the Entity Framework library. In the prepared solution, we used PostgreSQL as storage. However, thanks to the Entity Framework, an open source object-relational mapping framework for ADO.NET, and depending on the specific project requirements, we could use any other database for which there is a prepared Entity Framework provider.
Last but not least, our document generator can work in the containerized environment using containers with either Linux or Windows images, depending on the client’s preferences.