Chapter 5: The Variables Tab

A variable is a place to store information. Each variable is given a name which usually reflects the type of information it is meant to collect. For instance, the information meant to be collected by the variable name “Employer name TE” is the name of the employer and it is stored in a text (TE) variable. Ultimately, information stored in a variable is used, primarily, to populate the fields in an assembled document, a HotDocs® template, a case management system, or a court management system.

 

Thus, this chapter will first explain how to import the template’s variable names into A2J Author® from a HotDocs® component file and keep track of your associated HotDocs® template. This chapter will also demonstrate how to manage variables under the Variables Table and Variables Information window. Finally, this chapter will provide a detailed look at the properties of each variable type, including fifteen program variables which control the gender and color of the Avatars, optional sign text, and the appearance of the Back, Next and My Progress navigation bar items.

 

HotDocs® Template and Variable Names

 

The Variables Tab includes an Add from HotDocs .CMP import feature.

A2J Author® was originally designed to work with HotDocs®, where an A2J Guided Interview® is used as the alternative customer interface. So while there are alternative uses for A2J Guided Interviews®, most A2J Guided Interviews® are associated with a particular HotDocs® template for which it is collecting data. Coordinating versions of a HotDocs® template and associated A2J Guided Interview® can be troublesome once the process of revising begins. Thus, it may be useful to keep track of the name of the HotDocs® template in the About Tab (see Figure 33).

An entry in this field is for informative purposes only and has no effect on the coordination of the interview and template on a server.

Figure 33: Revision History section in the About Tab with HotDocs template information.

 

Variable names stored in a HotDocs® component (.cmp) file can be imported into an A2J Guided Interview. This import feature is located at the bottom of the Variables Tab screen and is indicated by a button labeled “Add from HotDocs .CMP” (Figure 34).

To use the “Load Variables” function, click on the button to browse for the correct component (.cmp) file for the corresponding HotDocs® template. After selecting the component file, all variable names will be loaded into the Variables Table.

Figure 34: Add HotDocs component file button.

 

An essential key to a successful project is ensuring that you have addressed all of the required data components of the HotDocs® template. One way to avoid missing a data component is to design the HotDocs® template first and then to import the HotDoc variables into an A2J Guided Interview®. This helps to avoid typos of variable names in the A2J Guided Interview®, which can cause errors in assembling a template. However, it is not necessary to start your document assembly project with designing the HotDocs template. You can design your A2J Guided Interview first. Unfortunately, there is no mechanism in HotDocs to import your A2J Guided Interview variables. But, if you do decide to create your A2J Guided Interview first, you can facilitate your HotDocs template work by printing a Full Report from the Reports Tab. This will provide a list of all the variables you used in your A2J Guided Interview.

Variables Table and Variable Information Window

 

The Variables Table (Figure 35) contains a list of all of the variables imported from a HotDocs® component file and variables added during the design of the A2J Guided Interview®. It is organized into columns. The Variables Information window is an editing window and can be accessed by double-clicking on any variable name.

 

Both the Variables Table and the Variables Information window include the following properties:  

• a variable’s “name” and “type,”

• whether the variable is included in a “repeat” dialog, and

• a comments/notes section.

 

The Variables Table is where you can view these properties, and the Variable Information window is where you can modify these properties. Additionally, the Variables Information window indicates where the variable has been used (Figure 35). You can see the questions that have used that variable by clicking on the “Quick Find" button next to the “Used by” label.  

 

Figure 35: Variables Table and Variable Information window in the Variables Tab.

 

The Variables Table and the Variable Information window indicate the names of variables, and give you an opportunity to delete or edit variable names.

 

The Variable Table column entitled “Name” indicates the names of all of the variables imported or created during development, whether or not they have been used in a question. (For more on naming conventions for variables, see Appendix C.)  You can delete variables by clicking on the variable name in the Variable Table and opening the Variable Information window. There is a delete button within the Variable Information window (see Figure 35). You can create new variables by clicking the “Add” button near the bottom of the Variables Tab.

 

Variable Type

 

The Variable Table indicates what variable “type” is assigned to each variable. The Variables Information window will allow you to change the assigned type.

Each variable can be assigned one of the following types: Text, True/False, Number, Date, Multiple Choice, Unknown, or Other. A variable’s type can be changed by clicking on the variable name and editing the type in the Variable Information window (Figure 36).

 

Figure 36: Variable Type selected in Variable Information window.

 

A variable’s “type” determines how the data collected in that variable will later be evaluated. Thus a “variable type” is much different from a “field type,” which merely designates the format in which the data will be collected. For example, a variable entitled “Phone number TE” may be assigned the field type “Number Phone,” which tells A2J Author® to provide three consecutive fields to collect each portion of the phone number. But, the variable type assigned to “Phone Number TE” would be “Text,” because the phone number will never be used in a numerical calculation. Rather, a phone number is treated as text.

 

Also, variable names are case and type sensitive. So a variable’s name and type must match the variable used in the HotDocs® template. If not, any data collected by that variable will not populate in the intended field on the HotDocs® template.

 

For a complete description of all variable type properties, please see the main subheading below entitled Variable Type Properties.

 

Repeating

 

The entry in the “repeat” column of the Variables Table, and the checkmark indicating “repeating” under the Variables Information window, indicate whether a particular variable has been used within a repeat dialog (Figure 37). So, the indication suggests that the variable may collect multiple values during the interview.

 

Figure 37: Repeat Column and Repeat Checkbox in Variables Table and Variable Information window.

 

The chapter entitled “Creating Questions” provides a detailed explanation of how to create repeat dialogs.

 

Comment Column

 

The comment column contains information that you may wish to note about the variable. It is purely for reference purposes. It tells a future author what the variable is supposed to do. It is especially helpful for variables that are used behind the scenes to conduct calculations.

 

Variable Type Properties

 

Each of the following variable types is described below:  Text, True/False, Number, Date, Multiple Choice, Unknown, and Other. In addition, the following A2J Author® program variables will be described:  User Avatar, User Gender, A2J Step (1, 2, etc.), A2J Navigation TF, and A2J Interview Incomplete TF. The charts included at the end of this section provide a quick reference to the properties of each variable type.

 

“Text”

 

A Text variable type is used to collect data that should be treated only as text. So a text variable can be used to collect numbers that will not be used to perform calculations, such as phone numbers, social security numbers, and zip codes. The text variable type in A2J Author® corresponds with the “text” variable type in HotDocs®.

 

“True/False”

 

The True/False variable type is used to collect a value of true or false only and corresponds with the True/False variable type in HotDocs®. However, True/False variables can be implemented in a couple of different ways in A2J Author®, either through a checkbox or a pair of buttons.

First, every Checkbox and Checkbox (none of the above) field automatically functions as a True/False option. A checkbox functions as follows: True is the value populated in the associated variable when the box is checked, and False is the value populated when the box is unchecked.

Secondly, a True/False variable can be manually set in the context of two buttons. If two Buttons are created, you have the option of manually assigning a variable and variable value to each. So, for instance, if you were to provide a selection of two buttons in order to advance to the next question – let’s say you provide the options “yes” and “no”  as options for answering a question – each Button could be assigned the same variable, one with a default value of True and the other False. (See the Buttons subheading in the Creating Questions chapter.)

 

“Number”

 

Number variables are used to collect numbers which need to be immediately evaluated, or will otherwise be needed at some point in the interview as part of a larger calculation. Thus number variables are often used to collect data such as asset values, income or benefits, pay rate, age, number of children, etc.

Even though the Number (Pick from list) appears as a drop down list providing multiple options, typically the value collected will later be needed in a calculation. Therefore, they should be set as number variable types, not multiple choice variable types. The number variable type in A2J Author® corresponds with the number variable type in HotDocs®.

 

“Date”

 

While a text variable type could be used in conjunction with a text field to collect a date, the date field and variable type provide additional functionalities such as the capability of conducting calculations using a date. (See the Date Field Type under the “Creating Questions” chapter for additional information on the functionality of the Date Field.)  

 

“Multiple Choice”

 

Multiple-choice variables are used to collect a single value from a set of multiple choices. Multiple-choice variables can be used in the context of a series of radio buttons or a multiple-choice drop down text list.

The Multiple-choice variable type does not allow for collecting multiple values or selections from a set of multiple choices for a single variable. To provide the end-user with an option of selecting multiple items from a list, you must use True/False variables in coordination with Checkbox fields.

 

“Other” and “Unknown” Variable Types

 

Any variable designed in association with a Button is automatically assigned the variable type “Unknown.” The variable type “Unknown” is also assigned to the twelve “step” variables (see subheading Program Variables for Steps, below).

The variable type “Other” is a reserved variable type not currently in use. Either “Unknown” and “Other” can also be used as placeholders in the event you are unsure what variable type you want to use – just be sure to modify it to the correct variable type before you complete the A2J Guided Interview.

 

Program Variables for Gender and Avatar

 

There are two program variables that change the presentation of the Avatar Guide and User Avatar: User Gender and User Avatar. The variable “User Gender” determines whether the Avatar Guide speaks to a male or female Avatar. The value for this variable must be collected early in the Guided Interview, in a Gender field, in order for the Avatars to show up in the interface. The variable “User Avatar” determines which avatar group is chosen, changing the Avatar Guide and the End User Avatar’s skin tone from Avatar 1 to Avatar 2, or to Avatar 3 (see Appendix B for Avatar images).

 

Program Variables for Steps

 

There are twelve “step” variables, one for each possible “step” in A2J Author®, as follows: A2J Step 1, A2J Step 2….A2J Step 12. These variables allow a step’s sign to be customized. For example, a sign defined as “Spouse’s Information” under the Step Tab, can be reflected later on as “John’s Information” (Figure 38).

 

Figure 38: Sign modified by Step Variable.

 

In order to accomplish this customization, you need to collect a value that you eventually want to use in a sign’s text. So, “Spouse name first TE” might be used to collect a spouse’s first name. Following the collection of a value for that variable, you can then set the desired step variable equal to the value previously collected plus whatever other text you would like included in the sign. Thus, A2J Step 2 could be set equal to: %%Spouse first name TE%% + “’s Information”. Setting a step variable takes place under the Advanced Logic section of the Question Design Window (Figure 39).

 

Figure 39: Step Variable used to set Sign Text for Step 2.

 

Program Variable for Navigation

 

Authors can remove the Back and Next navigation buttons by setting the A2J Navigation TF program variable to false. The default setting for A2J Navigation TF is true. Thus, unless an author chooses to set the program variable to the value “false” under the Advanced Logic Section of a question, the Back and Next buttons will appear in each question of an A2J Guided Interview®. (See the Creating Questions chapter for more information about setting conditions under the Advanced Logic section of the Question Design Window.)

 

Program Variable to Track Exit Point

 

The A2J Interview Incomplete TF program variable applies when an A2J Guided Interview® has been enabled with the Exit feature which allows an end-user to exit to the LHI server before they have completed all of the questions. Upon selecting the Exit button provided by the author in the Exit Question, the A2J Interview Incomplete TF variable is set to true. (See the Creating Questions chapter for a complete description of the exit to save incomplete data feature.)

 

Computation Variables in HotDocs®

 

Computation variables are not imported into A2J Author®, leaving you with two options for handling computation variables. The first option is to collect the data which feeds into a computation, thereby letting HotDocs® complete the computation. The second option is to complete the computation in A2J Author®, in which case you can get rid of the computation in HotDocs® and simply represent the computation value in a text or number variable.

 

Variables Reference Chart

 

 

Program Variables Reference Chart

 

 

Variable Macros

 

Any variable can be used as a macro in order to call the value of the variable to include the value in the context of question text, to set the value of another variable, or to include the value of a variable in a field label. The variable macro format below is only needed in the question text and the Learn More sections. It should not be used in the advanced logic section. In the advanced logic section, you do not need the double % signs.

 

The macro format is:  %%[Variable name here]%%

 

Question Text Macro

 

In Figure 40, the author is calling up the value of a variable that was used in an earlier question to collect the user’s first name. The variable used was “Client first name TE.”  Thus, the macro format used in the question is: %%[Client name first TE]%%.

 

Figure 40: Variable macro in the context of question text.

 

Macro to Set a Variable’s Value

 

In Figure 41, the author is calling up the value of three separate variables that were used in the current question to collect the end-user’s first, middle, and last name. The variables used were “Client name first TE,” “Client name middle TE,” and “Client name last TE.”  The author then writes an expression in a condition under the Advanced Logic section of the Question Design Window to determine whether the end-user has entered a middle name.  If the end-user has entered a middle name, the variable “Client name full TE” will be set to equal the values of the first, middle, and last name together.  If the end-user has not entered a middle name, the variable “Client name full TE” will be set to equal just the first and last name together.

 

Figure 41: Using a macro to help set the value of a different variable.

 

Macro to Set a Label

 

Assume you use two different variables to collect the names of two guardians: “Guardian 1 name TE” and “Guardian 2 name TE.” You would then call up the value of each variable separately in the context of a radio button label for the purpose of determining the primary guardian. The macro format is: %%[Guardian 1 name TE]%% and %%[Guardian 2 name TE]%% (Figure 42).

 

Figure 42: Variable macro for a Radio Button label.

 

Figure 43: Variable Macro in a label.

 

Ultimately, you want the choice of primary guardian (Figure 43) to be reflected in the variable “Agent primary TE.” In order for the selection’s value to populate this variable, you must index the selections. Using the variable “Agent index,” assign the default value “agent 1” and “agent 2” to the radio button options (Figure 44). Then, under the advanced logic section, the variable “Agent primary TE” can be populated according to the value of the indexing variable (Figure 45).

 

Figure 44: Radio Buttons agent index example

 

Figure 45: Index variable used to set variable