Using Powershell to manage large HotDocs interviews

If you use the document assembly product HotDocs, you may know that the main component file (which contains the interview logic and variables used to turn the template into a finished document) is an XML file. HotDocs Developer, the official editor for the component file, is relatively easy to use. However, it has limits for larger dynamic documents. There are no features that assist with manipulating a large set of related components with scripting. PowerShell is great at handling XML files. That lets us manipulate the component file directly, speeding up some time-consuming manual steps.

What problem does PowerShell solve?

Automation does two jobs: it saves time, and it reduces errors. That’s the same problem we’re trying to solve with HotDocs, after all!

My current project has been actively developed over the last 25+ years. It consists of 140 templates, hundreds of components, and generates more than 50 distinct forms to defend against an eviction. It’s aimed at lawyers, not pro se tenants, so complexity is OK. But I wanted to simplify the experience by using dynamic elements. That means on some dialogs, hiding or showing dozens of components at once, and using scripting to set the value of those variables based on a response on a different dialog. With a lot of manual copying and pasting, I was worried that I was making mistakes or inadvertently omitting components. I didn’t find a way within HotDocs to store a list of variables and their association in something like an array for later reuse in scripts. That meant a lot of dragging and dropping (one at a time in the Script Editor) and typing in repetitive keywords. I found a workaround with copying between Excel, Notepad++, and then back to the Script Editor, but there had to be a better way!

PowerShell is working for me. I still have some long, spaghetti code scripts, but at least I can quickly update them when components are added or removed without fear of making mistakes.

Why PowerShell?

I chose to use PowerShell because I’m very familiar with it–I use it almost every day as a systems administrator–and it is great at manipulating strings, objects, and XML files. The PowerShell pipeline is also perfect for stringing together a series of commands, which makes it very flexible for creating different commands. One added bonus is that PowerShell is available on every Windows system after Windows XP. There’s no reason that a different language couldn’t work. Some that I know have built-in libraries for working with XML include Python and JavaScript.

Examples

Although PowerShell can also write changes back into the component file, my basic workflow is to place the components I want to manipulate into a dialog, run the PowerShell script, and then copy the resulting code into the Script Editor.

Generating show/hide keywords

I created a function, get-dialogcontents, which lists all of the components in a dialog. For the example below, it was 36 separate components that I wanted to show or hide when I clicked a check box. Using the PowerShell function, generating the text for that script is just one line:

get-dialogcontentsscript -dialog "CC Unfair deceptive practices DI" -before "`tSHOW"

(the `t is a code that tells PowerShell to insert a tab–in other languages, the same is commonly represented as \t).

Then I can simply cut and paste the code into the Script editor:

It is possible to use “dummy” dialogs that are never used in the interview just to store lists like this. For example, you may want to break your questions into multiple dialogs, but use a single script to set the default value of those components. If you want to use the script technique above, you could place the components into two dialogs: a “master” list and the shorter list that you actually display to the user. That lets you easily maintain a set of related components in a way that’s easy to update and later extend.

Here’s the code to set the value of all of those components to true, which you might want to happen if another value is set:

get-dialogcontentsscript -dialog "CC Unfair deceptive practices DI" -before "`tSET" -after "TO TRUE"

Summarizing a list of selections

In addition to hiding, showing, and setting default options, a last component of responsive document automation for me is summarization. HotDocs does some question level summarization, but because our system is so large, I wanted to provide some additional summaries at checkpoint stages. Here’s an example:

The list of selections is dynamically generated, but it takes a long computation with a series of conditional statements to get this nice summary:

Here’s the one liner for PowerShell automatically summarizing the contents of a dialog:

get-dialogsummary -dialog "DISC Fault DI"

And here’s what that looks like on a sample dialog:

Conclusion

I’ve posted the scripts in the examples above on GitHub. They are going to be most helpful for someone who understands a little bit about PowerShell and already makes use of the Script Editor in HotDocs, but I hope they can help you!