Chapter 5: The Variables Tab

(Last updated November 2021)

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 to populate the fields in an assembled document, an A2J Template, a HotDocs® template, a case management system, a court management system, or an e-filing system.

 

This chapter will demonstrate how to manage variables under the Variables Table and Variables Editing Window. This chapter will provide a detailed look at the properties of each variable type, including the program variables which control the gender and skin tone of the Avatars, optional sign text, version, guide id number, and whether an end user has completed an A2J Guided Interview. Finally, this chapter will 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. 

 

Variables Table and Variable Editing Window

 

The Variables Table (Figure 5a) contains a list of all of the variables in your A2J Guided Interview. It is organized into columns. The Variables Editing Window is where you can edit variables and can be accessed by double-clicking on any variable name (Figure 5b).

 

Both the Variables Table and the Variables Editing 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 Editing Window is where you can modify these properties. Additionally, the Variables Editing Window indicates where the variable has been used (Figure 5c). You can see the questions that have used that variable by clicking on the “Quick Find" button next to the “Used by” label.  

 

Figure 5a: Variables Table in Variables Tab.

 

Figure 5b: The Variable Editing Window

Figure 5c: Quick Find feature indicates where the variable is currently used in the A2J Guided Interview. 

 

The Variables Table and the Variable Editing 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 Editing Window. There is a delete button within the Variable Editing Window (see Figure 5v). You can create new variables by clicking the “Add” button near the top 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, and Multiple Choice. A variable’s type can be changed by clicking on the variable name and editing the type in the Variable Editing Window (Figure 5d).

 

Figure 5d: Variable Type selected in Variable Editing 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 a field with gray suggested formatting of (xxx) xxx-xxxx. 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 template or content management system. If not, any data collected by that variable will not populate in the intended field.

 

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 Editing Window, indicate whether a particular variable has been used within a repeat dialog (Figures 5e & 5f). So, the indication suggests that the variable may collect multiple values during the interview.

 

Figure 5e: Repeat Column  in Variables Table.

Figure 5f: Repeat checked in Variable Editing 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, and Multiple Choice.. In addition, the following A2J Author® program variables will be described:  User Avatar, User Gender, A2J Step (1, 2, etc.), and A2J Interview Incomplete TF. The other program variables A2J Bookmark, A2J History, and A2J Interview ID are used internally by the authoring system and cannot be edited by the author, so they will not be covered in this Authoring Guide. A2J Navigation is a legacy program variable from version 4.0 and earlier of A2J Author. It is no longer used in A2J Author 6. 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: the default state is unanswered. True is the value populated in the associated variable when the box is checked, and False is the value populated if the previously checked 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.

 

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 A2J 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 to one of the options chosen by the author (see Appendix B for Avatar images). ***COMING SOON: New way to ask the end user to select an avatar, along with 6 additional user avatar options** (Expected by end of 2019)

 

Program Variables for Steps

 

There are thirteen “step” variables, one for each possible “step” in A2J Author®, as follows: A2J Step 0, 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 “Jessica's Information” (Figure 5g).

 

Figure 5g: 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 4 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 5h).

 

Figure 5h: Step Variable used to set Sign Text for Step 4.

 

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 5i, 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 first name TE]%%.

 

Figure 5i: Variable macro in the context of question text.

 

Macro to Set a Variable’s Value

 

In Figure 5j, 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 5j: 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 agents: “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 5k).

 

Figure 5k: Variable macro for a Radio Button label.

 

Figure 5l: Variable Macro in a label.

 

Ultimately, you want the name of the primary guardian (Figure 5l) to be reflected in the variable “Primary guardian TE.” In order for the selection’s value to populate this variable, you can see the below logic (Figure 5m).  You can also set the Backup guardian TE variable as well. 

 

Figure 5m: Radio Buttons guardian example