A Quick Walk Through Docassemble

Share on facebook
Share on twitter
Share on linkedin
Share on pinterest
Matthew Penning is a member of the Merlin Legal Open Source Advisory Board

A Quick Walk Through Docassemble

Matthew Pennington*

I recently built my first tool using docassemble, a free open source system, which at its core offers guided interviews and automated document assembly. As I learned, however, it is capable of doing much more than this.

You can use docassemble to push/pull data from other systems – your end goal in fact doesn’t need to be assembling a document at all! Docassemble also offers support ‘out of the box’ for providing remote assistance to users completing an interview (through live chat, screen sharing or taking control of the interview), multi-language interviews and capturing touchscreen signatures.

This article focuses on the experience I had getting docassemble up and running and then creating my first interview. I have also included a walk through of the tool I built, which is freely available for anyone to download/use/improve/play with.

Getting docassemble Running

Getting docassemble up and running requires a level of technical knowledge. This, for me, is probably the main barrier to having more people exploring its features. I tried to get docassemble running for myself (following the instructions on the website) and was unable to do so successfully – though admittedly the steps were beyond my level of technical competence.

It would be great to see third parties such as agencies/consultants coming forward to offer free tiers of docassemble instances that users can just dive straight into and start building.

For now, if you aren’t familiar with configuring web servers or using Docker, then you have a couple of choices:

1) Have someone set up docassemble for you

You could ask your IT Team to get docassemble up and running for you. If you don’t have an IT team, your favourite local web development company should be able to assist. You could also check out the consultants listed on the docassemble website, or ask for help in the #questions channel of the docassemble Slack Group.

2) Use a third party development tool that has docassemble under the hood

There are several platforms that are built on top of docassemble that provide interview development tools. These tools are more geared towards ‘no code’ type environments, so you may not get the full docassemble experience. They are however a great way to get up and running easily. Existing providers include Community.lawyer and Documate. At the time of writing, a third provider, Clerical Platform, is currently available in beta mode.

The rest of this article follows route (1) – where you have found a friendly techie to get docassemble up and running for you (thank you Steven Dickinson!).

The Task

I recently spent time at the charity Support Through Court – looking at some of the issues Litigants In Person (LIP) were facing when navigating the court system in England and Wales.

One of the issues I saw was the basic errors that LIP were making when drafting a Witness Statement to submit to the courts. There is very specific wording that needs to be used within the document, as well as certain border widths and a specific font.

What was happening was that LIP were submitting forms that did not meet the criteria, so having their statements rejected. I saw this as a good test project to build using docassemble.

The Solution

The end result was a Witness Statement Helper tool. The docassemble solution consisted of two parts:

1. Writing the Interview (collecting the info needed for the Witness Statement)

2. Creating the Document Template (producing the Witness Statement for the LIP)

Before reading on, it’s worth trying out the Witness Statement Helper for yourself so you can see what the end goal is!

Writing the Interview (collecting the info needed for the Witness Statement)

I was surprised by how straight forward creating interviews in docassemble actually is.

Rather than getting bogged down with a ‘flow chart’ approach, docassemble allows you to focus on creating a question bank, and then it just asks the questions it needs in order to accomplish a given task. This means you could have a big old question bank, and then use those questions to populate various documents, depending on the task.

A lot of the heavy lifting in terms of the types of information you are trying to capture is also taken care of for you – for example letting users pick a date or checking an email address is in a valid format.

In addition, docassemble has a set of starter questions and definitions of things that are common to a legal court case (e.g. plaintiff, respondent). Whilst the extent of this functionality is currently minimal, this is where the power of open source can be leveraged.

For example, someone familiar with the language and information used in a court case in England & Wales could provide an extension to this section of the platform that anyone else working in the England & Wales jurisdiction could then use, extend, contribute to and improve.

To create the interview I needed to capture a few things from the user:

1) The name of the court and type of case they were involved in. This determined:

  • The opening line of the Witness Statement, e.g “IN THE FAMILY COURT IN SHEFFIELD”
  • What the people involved in the case were called, e.g. Claimant, Applicant or Petitioner

2) How many people were involved in the case, along with their names and addresses. This determined:

  • The correct wording for the opening and closing statements in the Witness Statement
  • Where and how the names of the people were included at the top of the Witness Statement and the number of signature boxes needed

3) Some other basic info, comprising:

  • The case number
  • The date the user would be signing the statement

4) Their actual Witness Statement!

So now we turn to the code itself. This was the first thing I built in docassemble, so I’m sure that if I look back on this code in a few months/years time, I’ll be horrified by the way some of its written!

The interview itself is made up of three files:


Essentially this file designates what the “Witness Statement Helper” does. It relies upon two files for its question bank (which are detailed below), and designates the output of the interview as being a witness statement produced as a docx file – which we will explore more in the “Creating the Document Template” section below.

<script src=”http://gist-it.appspot.com/https://github.com/mattpennington/docassemble-hmctshelper/blob/master/docassemble/hmctshelper/data/questions/witnessStatement.yml?slice=1:16″></script>


This file contains the single question about in which court the case is being heard, because that’s a question I can see being used again and again in multiple interviews.

<script src=”http://gist-it.appspot.com/https://github.com/mattpennington/docassemble-hmctshelper/blob/master/docassemble/hmctshelper/data/questions/courts.yml?slice=1:16″></script>


This file contains all the other questions we need – though arguably these could be broken out individually so they could be made available for reuse too.

<script src=”http://gist-it.appspot.com/https://github.com/mattpennington/docassemble-hmctshelper/blob/master/docassemble/hmctshelper/data/questions/witnessStatementQuestions.yml?slice=23:55″></script>

You can click on the ‘view’ links in the code fragments above, to view the full files, or review/download/clone the whole project on github. You can also add it into your own docassemble setup directly using the python package, and explore it that way.

When the Witness Statement Helper interview is run, it takes a look at what we are trying to achieve first, which in this case is populating all the information placeholders that are defined within our Witness Statement template file. We now move on to take a look at how that file is put together.

Creating the Document Template (producing the Witness Statement for the LIP)

Docassemble has several ways in which you can build documents, including generating files from scratch using markdown, utilising docx templates (the format you often see your Microsoft Word documents in), and populating PDFs that have fields that need completing.

You can also link Google Drive and/or Microsoft OneDrive to your docassemble setup, enabling you to maintain your existing ecosystem with respect to versioning of documents/templates, and then synchronising changes back into docassemble when needed.

For the Witness Statement Helper I created a docx template as shown below.

There is a mix of information being populated from the questions we posed, and logic that changes the layout based on things we found out when asking the questions (for example how many people were making the claim).

Logic statements are encapsulated in {% %}, and information we are printing out within }.

We will quickly look at each type used in this document template in turn.

{ }

This prints out the case number that we captured when we asked the user for the case number.

{ }

We populated this value when we found out what type of case it was, so we can refer to the person correctly as claimant, applicant or petitioner.

{ }

We asked for the names of each person making the claim, and stored each person within a claimant variable. The 0, refers to the first claimant (as data structures in most programming languages tend to make zero the first entry, followed by one, two, three…), and we are getting the name we captured for them. We captured their forename and surname separately and we now want to print out their full name. Docassemble comes with a number of built in helper functions for circumstances such as these, and in this case the full() function will print the person’s full name into the document.

{%p if claimants[1] is defined %}

This is a logic statement that checks whether or not (“if”) we have a second person making the claim. It looks if there is any information held at position one in our claimant variable, and if so it then prints out the text before we reach the {%p endif %} a couple of lines later.

If it finds a second person, then it prints out { } SECOND { } – being the name of the second person, followed by the word “SECOND” followed by the term we are using for the person making the claim defined in { } (as above).

{%p for paragraph in paragraphs %}

During the interview, we asked the person making the claim to make their statement, one small paragraph at a time. This “for” logic statement is taking each of those paragraphs in turn, so we can do something with them. In this case we use { to print out the contents of each paragraph in turn until we run out of paragraphs.

{ }

This is a helper function built into docassemble that simply prints out today’s date.

All The Code

All the code is within a single docassemble package called hmctshelper. The package is freely available through both PyPi and Github for others to use and ideally improve – there’s also a ‘bonus’ interview for populating the dreaded N244 court form that demonstrates how to populate a PDF from an interview.

Github: https://github.com/mattpennington/docassemble-hmctshelper/

PyPi: https://pypi.org/project/docassemble.hmctshelper/


It’s worth noting that docassemble has a ton of functionality that isn’t covered in this article – in fact we have barely scratched the surface! To read more about what you can do, take a look through the documentation over at docassemble – especially the special features.

I was surprised by how pleasant an experience I had creating this tool using docassemble.

Experience with other open source products has taught me you can end up bumping up against things that are broken (a “Hello World!” example that doesn’t work is the universe telling you that you should stop there), or where the development/direction of the product has been so dominated by the personality/design choices of one person, that the end result is something that other developers can find it quite hard to get involved in or work with the code base that’s there.

My impression and experience from reaching out through the docassemble Slack group, and getting support from docassemble’s creator Jonathan Pyle during this project, is that people who are using docassemble can see that the design choices made have resulted in a great product. It probably also helps that Jonathan is a nice guy!

What docassemble needs now is for the community to continue to grow, more people to get involved and for the suite of packages and extensions to continue to build. Docassemble would benefit from improving the “Playground” helper so that it provides more helpful feedback when debugging interviews, and perhaps extending the “Wizard” so it can generate more complex interviews.

Whilst the documentation is pretty good (poor documentation being another open source bugbear of mine!), docassemble could benefit from more tutorials and examples of things that have been built.

This is the true test of how open/collaborative the legal community is prepared to be, as it’s one thing to utilise open source tools, but how many people are going to be prepared to give back and share what they’ve built in order to move our whole community forward? Only time will tell.

I’m certainly excited to see how far we can go with an open source document assembly ecosystem; or as Alex Hamilton, CEO of Radiant Law and who recently released an open source integration between docassemble and DocuSign more eloquently put it: “If industry players are set on building Death Stars, it’s time to start a rebel alliance.”.

*Matthew Pennington is a member of the Merlin Legal Open Source Foundation Advisory Board and is from Sheffield UK.

Scroll to Top