Developing Complex Interviews Using Docassemble and Documate

Have you wondered how you can scale your document automation projects using Documate? Well, you are in luck. We want to give you an overview of how we escalate Documate to create fast and efficient workflows for your document automation projects.

Let’s start from the beginning.

Docassemble and Documate.

We use Documate to develop simple interviews and split up complicated interviews into separate components. These modular, reusable, and testable components are essential. Also, we use Github for version control and efficient collaboration.

Also, on some occasions, we use Docassemble. Docassemble is a versatile open-source interview and document generation program with many advanced features. You might not know, but Documate is a commercial tool built on Docassemble. Documate offers an attractive and streamlined interface with a graphical user interface (“GUI”) for development and hosting. However, considering that Docassemble powers Documate, any Docassemble code is compatible and can run on Documate.

‍

‍

Efficient Development of Complex Interviews.

An “interview” comprises the question files and the output templates that get turned into documents. Docassemble asks the questions from the question files, stores the user’s answers, and puts the answers into the output templates. The development process for simple interviews that only involve one set of questions and one or a few forms is relatively straightforward. But we have found that some challenges come up when we have to write complicated sets of interviews covering many interrelated topics.

The challenges come up because the question files and the output templates for complicated interviews get very long. If things aren’t split up, testing of the interviews might be a tricky endeavor. To make the process efficient, we split up the question files, split up the output templates, test the parts, and put them back together to complete the final product. Think of it as a digital puzzle that we break down voluntarily, but we have the “cheat-sheet” to put it back together.

Structure of the Code.

The interview questions and logic are in .yml files. A .yml is the file extension for YAML, which stands for “Yet Another Markup Language” or “YAML Ain’t Markup Language.” YAML is a simple, easy to read language that lets you store data without writing complicated syntax.

The .yml files tell Docassemble what questions to ask, when to ask them, and what forms to output. Take a look at the .yml file below. Docassemble would run it, ask the user what kind of fruit they had, and store the user’s answer to use in the output form. Then it would generate the output document using the .docx file fruit_template.docx.

‍

‍

The interview output templates are either .pdf files or Word .docx files. The output templates have tags that refer to the variables in the interviews. Docassemble uses the python-docx-template library to read the output templates and the Jinja templating language to replace the tags that it finds with the values that the user entered in the interview. Docassemble would take the example output document below and replace the {{ fruit }} with the kind of fruit the user said they have.

‍

‍

Complicated Interviews.

The interviews that cover a simple subject and generate one or a couple of documents can be developed relatively quickly. It’s easy to run the short interview, look at the forms that come out, and ensure that the answers are getting put in the right place. But more complicated subjects may have hundreds of questions, complex branching logic, and generate many documents. It is also common for a customer to need multiple documents that use the same questions in different places. For example, interviews that generate divorce documents could have the subject of alimony appear in four various forms. Our development process lets us write the questions once, write the output once, test them on their own, then re-use them in each place that we need them.

Re-using Questions.

An example of a complicated subject is divorce documents. The subject of alimony might appear in four different forms generated at various phases of the divorce case. To make the question code reusable, we split the code up. We write one .yml file asking the questions about alimony and including that file in each interview that generates output that consists of the alimony information. Splitting the parts of the interview up means that we can run them and test them separately. We can make sure each piece works before adding it to the more extensive interviews.

Also, if we want to change the questions about alimony, we only need to edit alimonyIndex.yml. Those changes will then show up in every other interview that includes alimonyIndex.yml. If we didn’t split up the files, we’d have to copy the alimony questions in each interview, asking about alimony. And when we wanted to change the questions about alimony, we’d have to make sure that we changed each interview question. But what if we changed most of them but missed one? Keeping all the questions about alimony in one place makes things easier and prevents errors from happening.

Below are some pictures of an example interview code. In these example interviews, alimonyIndex.yml has all the questions about alimony. The primary interview is utDivorcePetition.yml. The main interview asks about alimony by including alimonyIndex and asks about other subjects by including other .yml files.

‍

‍

‍

Re-using Output Templates.

There are two ways to make the alimony output reusable. One way is to write the code in a .docx template and include it as a sub-template. The other way is to write the code in a python function and call it from the main .docx template.

Including a .docx template as a sub-template of your main template means that the sub-templates entire output will be added to your main template. Below is an example of a .docx template being reused as a sub-template. The alimony.docx template would generate a few sentences about alimony, printing the parties’ names where appropriate. The divorce output form will include the entire contents of the alimony.docx template.

‍

‍

‍

Generating Output with Python Functions.

A lot of the time, using a sub-template is a good solution for including the output document that we need. But sub-templates don’t work with the numbered lists in Word documents. Also, many of the documents that we make use numbered lists because the forms are legal forms with numbered paragraphs. So we use Python functions to generate the output text. Python is the programming language on which Docassemble was written. You can include python functions in your interview code and call the python functions from inside your templates.

Below is an example divorce output form that has its content in a numbered list. We can’t use a sub-template because that won’t work with the numbered list. So we call the python function alimonyOutput. alimonyOutput returns a list of items. Each item in the list returned from alimonyOutput is then added to the numbered list. The code for doing this is inside the curly brackets in numbered items 2, 3, and 4.

‍

‍

‍

Testing Python Functions.

There are two more advantages to using python functions to generate the output text. The first advantage is that logic is a lot cleaner to write. Including complicated logic like loops and nested if statements inside the .docx template get hard to read; therefore, it is harder to fix bugs and get the right output. Writing python functions to generate the output lets us make working forms faster.

The second advantage of using the python functions to generate the output text is writing unit tests for the python functions. Unit tests are functions that tell you that you are getting the output you expect to see. If you write the test correctly and your code passes the test, you know your code is working. This lets you make changes to the code with confidence. If you change the code and it still passes the test, then it still works! We write our tests using the pytest library.

‍

‍

‍

Package.

Once all the parts are assembled, we save them as a Docassemble package. Then we host the package on Github. Then we can add the package to Documate and Docassemble accounts and run it, which makes the interviews available for use.

That’s it!

That’s the overview of the coding side of the A2J Tech interview development process. We develop the interview questions using the best tools for the job and use modern best practices to ensure the documents are assembled as the client required. We use Documate’s elegant GUI when it’s the best tool for the job, and when things get complicated, we split them up into components so they can be reused for quick, efficient, and precise results. If you need help, feel free to contact us.