HotDocs Answer Files Overview
Each piece of data that is gathered in a HotDocs interview or merged into an assembled document is defined (within HotDocs) as a Variable. Each variable has a name that uniquely identifies it and a type that identifies the type of data associated with the variable: text, number, date, true/false or multiple-choice types are possible. The actual data (value or values) associated with each variable -- whether gathered in an interactive interview or plugged in from some other data source -- is known as an Answer. Variables and answers are associated by name and type: if a document is being generated and a variable with a certain name and type is encountered, the answer will be looked up (in the current answer collection) using that name and type.
When a user completes an interview in HotDocs, the answers they enter are captured in an Answer Collection. Likewise, integrated applications can also generate Answer Collections. These answers can then be used to assemble a document or pre-populate additional interviews, and can subsequently be used to recreate the same document or assemble other documents that require the same information. Performing an assembly with a particular template and a particular answer collection will always generate the same completed document.
If you have multiple templates that require the same pieces of information (Answers), the same Answer Collection can be used across all those templates as long as the templates were created with consistent variable names and types. This can eliminate a user's need to re-enter information he has already provided.
Values and Repeated Answers in HotDocs
Some variables have regular (scalar) answers, and others have what are known as repeated answers. A variable may have a repeated answer if that variable is merged into a portion of the document that needs to be repeated multiple times -- for example, suppose a paragraph needs to be repeated in a document, once for each child in a family. A repeated answer for that variable allows a different value to be merged into each of those repeated paragraphs. It's worth taking a few minutes to understand how repeated answers (and nested repeats) work in HotDocs answer collections.
Let's suppose we're dealing with a HotDocs template for a will. An obvious text variable might be the DecedentName -- the name of the individual who has died. This is known as a regular (non-repeated) variable, and it has a regular (non-repeated) Answer. The Answer object will contain exactly one text-type Value.
<Answer name="DecedentName"> <TextValue>John Smith</TextValue> </Answer>
Now suppose the will contains a paragraph regarding each named beneficiary. In such a paragraph it would make sense to have another text variable called BeneficiaryName -- the name of the individual to whom the decedent has willed something. Because the will entails a list of beneficiaries, we say that BeneficiaryName (as well as any other variable related to each beneficiary) is a "first-level repeat". There is still only a single Answer for the BeneficiaryName variable, but that Answer object will contain a list of Values embedded inside of a RptValue element:
<Answer name="BeneficiaryName"> <RptValue> <TextValue>Mary Smith</TextValue> <!-- repeat index is [0] --> <TextValue>John Smith, Jr.</TextValue> <!-- repeat index is [1] --> <TextValue>Julie Smith</TextValue> <!-- repeat index is [2] --> </RptValue> </Answer>
Within HotDocs itself, and within APIs and client libraries that deal with HotDocs answers, note that each of these repeated values has a "repeat index" associated with it. Repeat indexes are based on the position of a value within the RptValue element.
Now suppose the will contains a list of bequests intended for each beneficiary. Since variables related to beneficiary information are already repeated (at level 1), variables related to each bequest will be repeated at level 2. So BequestDescription might be a second-level repeated text variable. This means that an Answer object for BequestDescription will actually contain a list of lists: a list of bequest descriptions for the first beneficiary, followed by a list of bequest descriptions for the second beneficiary, and so on.
<Answer name="BequestDescription"> <RptValue> <RptValue> <TextValue>the contents of my bank account</TextValue> <!-- repeat index is [0,0] --> <TextValue>the house</TextValue> <!-- repeat index is [0,1] --> </RptValue> <RptValue> <TextValue>the dog</TextValue> <!-- repeat index is [1,0] --> <TextValue>the cat</TextValue> <!-- repeat index is [1,1] --> <TextValue>the three gerbils</TextValue> <!-- repeat index is [1,2] --> <TextValue>my collection of rare stamps</TextValue> <!-- repeat index is [1,3] --> <TextValue>my red gym shoes</TextValue> <!-- repeat index is [1,4] --> </RptValue> <RptValue> <TextValue>a pony</TextValue> <!-- repeat index is [2,0] --> </RptValue> </RptValue> </Answer>
HotDocs supports repeats nested up to 4 levels deep.
When working with repeated values in HotDocs itself (for example, in template development and in the HotDocs Script language), repeat indexes are 1-based, meaning that the first repeated value has an index of 1, the second 2, and so on. In HotDocs programming interfaces and client libraries, however, all repeat indexes are 0-based as in the example above.
Answer Collection File Format
HotDocs answer collections are typically saved in an XML format that adheres to the HotDocs Answer File Schema, describing their structure and content. These answer files normally use a .anx file name extension.
An answer collection can include zero or more answers, each of which can contain either a text, number, date, true/false, multiple-choice, or repeated value (as indicated above). For example:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <AnswerSet title="empagreement" version="1.1"> <Answer name="Employee Name"> <TextValue>Larry Johnson</TextValue> </Answer> <Answer name="Number of Vacation Days"> <NumValue>20.0000000</NumValue> </Answer> <Answer name="Agreement Date"> <DateValue>29/5/2012</DateValue> </Answer> <Answer name="Employee to Complete Trial Period"> <TFValue>true</TFValue> </Answer> <Answer name="Employee Gender"> <MCValue> <SelValue>Male</SelValue> </MCValue> </Answer> <Answer name="Multi-select"> <MCValue> <SelValue>B</SelValue> <SelValue>D</SelValue> </MCValue> </Answer> </AnswerSet>