novodocx

Convert JSON files to Word documents

A while back I built the first version of ndocx – a utility that you can call in your terminal to populate standard Word templates. It can used to generate documents based on simple JSON files. You can think of it as a Word document visualizer of your JSON files. The ndocx utility doesn’t need Word or any other application to be installed on the machine, which makes it a good fit for services and you don’t need any license to run it. It’s real open source alternative that you can use as you wish.

ndocx is in fact the command line interface of Novo Docx, a library based on the latest .NET Framework. You can also find an Azure Functions App that exposes the same functionality as a REST service. This is a good alternative if you don’t want to deal with document manipulation yourself.

If you have a JSON file and a word template, using ndocx is as easy as the following command.

ndocx populate mytemplate.docx -params params.json -output output.docx

Take the following word template as an example.

A very simple word template

It has just one placeholder called a. In order to populate that place holder, you would need a JSON file like the following.

{
  "a": "simple test"
}

In other words for each placeholder in your word template, you would need an attribute in your JSON file with the exact same name.

If you have repeating section in your word template, you will need an array for your repeating section and inside the array each placeholder (that you want to populate) needs a matching attribute. For example the following JSON, has a simple attribute called “a” and an array called “repeating1”.

{
  "a": "simpla test",
  "repeat1": [
    {"a": "Col 1 - row 1", "b": "col 2 - row 1"},
    {"a": "Col 1 - row 2", "b": "col 2 - row 2"}]
}

The given JSON file can match the following word document, with a simple placeholder called “a” and a repeating section called “repeat1”.

A simple template with a repeating section

Just keep in mind that currently only “Plain text content control” and “Repeating section content control” are supported which should be enough for majority of use cases.

You can download the latest release of ndocx from its Github repository, Novo Docx.

https://github.com/rezanid/novodocx/releases

NovoDocx – An open source service that generates documents using standard Word templates

Lately, as part of solution I have been building for a client, we had to deal with several document generation flows. I’m talking about really complicated document templates. For example there is one that is composed of several tables and sections that compare different credits / mortgages that a client can take and their financial impact, benefits and downsides and more. This is nothing like the simple mortgage documents that your local bank shares with you. In fact, I am happy for their clients that will receive such well-thought documents, but as for the poor developers, this was not an easy task.

There are two out-of-the-box options when you need to populate Word documents.

  • Word templates feature that existed for ages in Dynamics CRM and now inherited by Power Platform. This is normally the easiest option, but it has many limitation and only works in harmony with rows in a table and its direct related tables.
  • Word Online Connector which is a premium connectors and more capable without dependency on any table. The main issue with this one is when you have flows in your solution that will be deployed in different environments or any time the location of your document needs to change. In this case instead of the name of these placeholders you would need to use random numbers because this connector cannot figure out the schema of the document or lock it after your build one.

For the second options there are some workaround, that I will be writing about soon in future, but what if the logic is so complex that using Flows or a Power App does not make sense or not enough.

In search for an open source library

At this point I started looking for an open source .NET library (preferably) to let us get the job done. It should exist in this day and age, right? The answer is no, it doesn’t. There are only some paid libraries and services that are quite expensive for what they do and working with them is not as easy as one might think. After digging deeper into GitHub, I was able to find some libraries that either rely on Open Office or a headless browser or the brain of the library is in a closed-source black box. I have to say honestly the fact that there is no open-source library and not in .NET was annoying enough, so I decided to start one and I decided to start simple and make it as easy as possible for the developer to use with no knowledge of the underlying format (😎 ehem which I know pretty well, but not to Eric White level well ☺).

Novo Docx

NovoDocx’s first readme file push in Git

Today I share with you my first iteration of Novo Docx, my take on a simple-to-use and simple-to-host library and service that you can use in you own projects. The current features are enough to handle a complex documents and quite fast. I have tried to capture many edge cases too. I will be focusing on enriching the functionality and providing more hosting options. The source code is hosted in GitHub. It includes a simple library and an Azure Functions App that you can use however you like.