Instruction Model: ADD TEXT TO MULT_CHOICE

This tip covers when to use and how to use the HotDocs Instruction Model: ADD TEXT TO MULT_CHOICE.  HotDocs supports dynamic multiple choice variables.  A list of options (and their associated prompts) for a multiple choice variable can be seen in the definition of a particular component. However, this restricts the user to options known at the time that a component file is authored. This instruction model lets the developer dynamically change the option values and their associated prompts based on answers given by the user during an assembly.

What are the elements?

  • ADD: The instruction to Add Text
  • TEXT: A Text Value, a Text Variable, or a Text String consisting of Text and Variables
  • MULT_CHOICE: A Multiple Choice Variable (Single select and Multi-Select)

Other Related Instructions?

  • CLEAR MULT_CHOICE:  Will clear ALL options and prompts for a Multiple Choice Variable

How do you use it?

1. Build from a Repeat

The sample below is used to set the options for a Beneficiary selector.  This option could itself appear on a REPEAT.  The beneficary variable is first CLEARed. Then the script loops through the list of children, adding each child’s name, one at a time to the option list.


2. Build from a Script

The sample below is used to set the options for a Beneficiary selector.  This option could itself appear on a REPEAT.  The beneficary variable is first CLEARed. Then the script loops through the list of children, adding each child’s name, one at a time to the option list.

ADD "Married|Client is married" TO CLI Married MC
ADD "Single|Client is single" TO CLI Married MC
ADD "Divorced|Client is divorced" TO CLI Married MC
ADD "Widowed|Client is widowed" TO CLI Married MC

3. Build from a Repeat and Add Custom Prompt

The sample below is used to set the options for a list of children to disinherit from a will.  The variable is first CLEARed. Then the script loops through the list of children.  For the option value, it adds each child’s name.  However, for the prompt, it puts in the child’s relationship to the , one at a time to the option list.

CLEAR HEIR Disinherit Name MS
// Change prompt based on gender of child
IF CHLD Gender MC = "Male"
ADD "«CHLD Name TE»|Client's son «CHLD Name TE»" TO HEIR Disinherit Name MS
ADD "«CHLD Name TE»|Client's daughter «CHLD Name TE»" TO HEIR Disinherit Name MS


  • You must create the Variable and assign a default option (e.g. “Name Goes Here” or “1″)


  • You must use a computation script for the CLEAR and ADD instructions.


  • The script must be processed before you display the Multiple Choice Variable.


  • However, given the way the HotDocs interview works, you can accomplish this by putting the computation on the Dialog Script where the Mutiple Choice Variable is used, or in an INTERVIEW script.  If you choose the latter option, it can go anywhere in the script.

Why do my autoentry forms include the wrong task links

Auto entry forms are a hybrid between chains and notes. They allow you to structure your tasks and events, much like a chain. And they also allow you to take notes on your tasks. However, if you convert an outline to an Auto entry form, the tasks associated with the underlying record (not the new record) are link to the outline topics.  It is simple to save an outline as an auto entry form. However, before you do that you should make a copy of the form and then remove the links to any associated records.

  • Make a copy of the outline
  • Remove all links to client and matter
  • Make a generic version of the description
  • Right-click on any outline elements that are linked to a task or event records and disassociate the link
  • Standardize and clean up the language
  • Click on the Save As Auto entry Form

You are now ready to go.

SET Command and GRAYed Variables

You need to SET the value of a variable, but want users to be able to edit the value even after it is SET.  HotDocs will GRAY a variable (prohibiting editing) if the SET command is processed on the dialog, and DEFAULT will not overwrite a variable’s value.

A “regular” script to SET a variable to a value (based upon a Multiple Choice variable) probably looks something like this:

IF Var_MC = “1”
SET Var1_TE TO “red”
SET Var1_TE TO “blue”

As soon as Var_MC is answered, Var_TE will acquire an appropriate value, and subsequently GRAYed out – because it is processed dynamically by the dialog script, and whilever those conditions are met, the variable will not be editable.

We need to avoid HotDocs GRAYIng the variable. The solution? A button that calls a computation.

Lets say we create a variable called Var1_CO – this is the variable that will be called by the button on our dialog. The content of this computation will be exactly the same as the script above. We don’t wish to do anything different, we just wish to shift the source of the SET command.

In our dialog additional text section, we type

@COMPUTE:Var1_CO: Populate

@COMPUTE is the command to tell HotDocs we want a button to call a computation. Var1_CO is the name of the computation variable we are calling. Populate is the button text which will be displayed. When we click this button, the value is SET (provided all conditions have been made), and the variable is editable.

The Holy Grail

There is much talk about the “Holy Grail” in document assembly.  As those who have seen “Monty Python and the Holy Grail” or more serious students of the Arthurian Romance (as opposed to those who have read “The DaVinci Code”, the Holy Grail is a “chalice” or “cup” which held the blood of the real Christ, was kept as a holy relic by the church for centuries and then was lost to history.  During the middle ages, knights went on quests to “find” and “recover” the Grail.  The Grail was never found.  But the “search for the Grail” filled up thousands of pages of literature, and the hunt for the Grail kept thousands of knights diverted in a quest that kept them from seeking to overthrow corrupt monarchies.

In the world of document assembly, one vendor has claimed to have achieved “the Holy Grail”.  The technology will not be available till late in 2007.  When it is, we will review it.  The question is not whether the Grail can be found, but whether it will be the “solution”.

In a recent newsletter, Exari claims to have achieved the Holy Grail in Document Assembly

The Holy Grail: A Document Assembly System That Reuses Negotiated Clauses
There’s a favorite question that people love to ask when they’re pondering whether document assembly will work for them. It usually goes something like this:

“That’s great, I answer all the questions, the system spits out a great first draft, I send it off to the other side, and their lawyers mess around with the fine print of clauses 11 and 23. Now, can I shove that document back into the document assembly system and change a few of my previous answers?”

Looking into the Myth

This article inspired me to look into The Holy Grail and its application to the world of document assembly.  As a youth, I was entranced by the Grail myth.  I knew all the players: Percival, Gawain, Lancelot.  And so, when a document assembly vendor claimed to have achieved the grail, I thought I should take a look.

In the wikipedia encyclopedia, the Holy Grail was:

….  the dish, plate, or cup used by Jesus at the Last Supper, said to possess miraculous powers. The connection of Joseph of Arimathea with the Grail legend dates from Robert de Boron’s Joseph d’Arimathie (late 12th century) in which Joseph receives the Grail from an apparition of Jesus and sends it with his followers to Great Britain; building upon this theme, later writers recounted how Joseph used the Grail to catch Christ’s blood while interring him and that in Britain he founded a line of guardians to keep it safe. The quest for the Holy Grail makes up an important segment of the Arthurian cycle, appearing first in works by Chrétien de Troyes.

In the literature of Chrétien de Troyes, a book called The Arthurian Romances, and other literature, the Grail was a “physical object”.  It is not that the Grail was illusive (it was certainly) and well hidden behind the walls of a fortress (it was), or that riddles needed to be solved and quests achieved. All these were true.  However, the ultimate criteria for “achieving the Grail” was “purity”.  Sir Lancelot, perhaps the greatest knight of all Chistendom, could never achieve the Grail.  For despite his strength, despite his intelligence and ingenuity, and despite his great experience and wisdom, Sir Lancelot lacked a pure heart.  He was (of course) an adulterer, sleeping with the Queen.  And so while Sir Lancelot could come within the presence of The Grail, he could not actually see or achieve the Grail.

What the Grail means today

In some ways, what Exari claims to have achieved parallels the Grail myth.  They have claimed to have built a tool that will effectively import “negotiated changes” back into a template.  When I asked to see the Grail (oh… I was not worthy), I was told to come back in a few months when it went into beta—Not quite yet.  Was this an announcement of a technology like Microsoft, before it existed?  I had a client who was intrigued in building a web-based contract management system and wanted it now. I was on my quest.

But the more serious question is whether the eXari Grail will offer the miraculous curative powers of the real Holy Grail.  This made me ponder.  If you take a “bad form” and automate it, will the Grail of document assembly save you.  Or, will it more likely allow you to continue reusing a poorly automated template well beyond its natural life.  Will the “Grail” be used to prop up a corrupt Monarchy that should long ago have crumbled of its own weight.  Will the “lack of purity” … or poor quality of the automated template mean that you will “not achieve” the bliss that comes from possessing the grail.

When lawyers fail to look at contract automation as an iterative process of regular updates and redesign of forms, such systems fail to meet their full potential.  In fact, it is the “lack of the Grail” that has been the biggest stimulus to effective authoring of templates.  By forcing the template designed to “anticipate” the negotiable issues and build rules, it creates better contracts, better systems, more power.  Yes, I am sure my clients would love to have their own “Grail”.  But in the end, I have a concern that it will diminish their impetus to put the proper resources into automation.  It will allow them to go back to the bad old days of word by word negotiation.

Further Details from Exari:

But there’s good news. The holy grail is coming. When Exari V5 ships in the first half of 2007, a big part of this problem will be solved.

In simple terms, any document produced from Exari which then goes through a process of negotiations (typically in Word) will be able to be “round-tripped” back into Exari in a way that preserves any negotiated changes to the text of particular clauses. This means you’ll be able to save the answers given during document assembly, as well as the edits made during negotiations, and re-use them against the same template, or even against an updated version of that template. So it doesn’t matter that the template has changed since last year. You simply load it all up and what’s relevant will be used, and the rest will be ignored.

Wiki Wiki Wiki

For the past several years I have been running a virtual office with collaborators in multiple locations.  We have tried a number of collaboration tools, including GoToMeeting and GoToMyPC, Groove, Time Matters World, with mixed success.  Most of the work was project based, where control of the project files could be passed (as a football) from one collaborator to another.  This works as long as you can pass control.  However, there are times when we have needed to have simultaneous control of a project.  For those, we have now standardized on a Wiki.

What is a Wiki?

According to, it is:

Wiki is a piece of server software that allows users to freely create and edit Web page content using any Web browser. Wiki supports hyperlinks and has a simple text syntax for creating new pages and crosslinks between internal pages on the fly.

Wiki is unusual among group communication mechanisms in that it allows the organization of contributions to be edited in addition to the content itself.

Our Experience

I have talking with many programmers who work with source code Wiki’s to store and organize snippets of code.  What distinguishes a good programmer from a so-so programmer is the ability to understand and “reuse code” efficiently in different environments.  By using a Wiki, code can be annotated and placed in an environment where it is made available to other coders in the organization. But this is where most “databases end” and the “wiki begins.

Because each article in a Wiki can be edited, each person who finds the code and uses it, can improve on the code … revise it.  The wiki tracks prior version.  It also tracks discussion on the particular article.  In this way, a Wiki (used in open source development) can grow to become a vital resource of what works and doesn’t work in an organization.

At Basha Systems, we have recently implemented an internal Wiki.  Every time one of us has an idea, we toss it up on the Wiki.  Someone else may look at the idea and refine it (or reject it).  The idea can then develop into a procedure, process, or utility. Commentary can be refined as the utility is used in a feedback loop which then improves the program.  The wiki software we use is called [url=http:\]Expression Engine[url], the same tool we use to host this website.  But there are a number of “hosted” Wikis on Yahoo, Google, and other paid sites you can use.  We keep ours behind the firewall, but there is nothing to say you could not start a public wiki for open collaboration.

Adding Spacing to Dialog Elements

When working with Dialog Elements, particularly Horizontal Lines, you may wish to add a line (or vertical space) before the dialog element.  You COULD add a separate dialog element for the spacing. But that adds to your scripting and dialog management.  Instead, you should add a <.pm> Code before and after the Prompt for the Dialog Element.

  • Create the Dialog Element
  • Set to Horizontal Line
  • Choose Alignment:  Left/Center/Right
  • In the Prompt, Right-click and add a Paragraph Marker
  • Type your prompt
  • At the end, Right-click and add another Paragraph Marker

Optional, you can add formatting around the prompt to control things like Bold and Italics.