Whenever possible it is best to use some sort of convention for naming variables in your A2J Guided Interviews®. Using a standard convention is even better. Using a convention helps you keep track of what the variables represent, thus making editing and troubleshooting much easier.
Using a standard helps others also. Through the use of the LHI server, Guided Interviews and templates are made readily available to other organizations. Leveraging and combining the work of others with your own corresponding template or Guided Interview, whatever the case may be, is much easier where variable names are consistent. Furthermore, as time goes on, the possibilities for integration of Guided Interviews with document e-filing and case management system integration increase. Integration with these types of systems involves the transfer of data using XML standards. In the event an XSL transform for a particular A2J Guided Interview has already been built to correspond to a particular system, a lesser amount of modifications to that transform will be necessary as additional A2J Guided Interviews are designed, so long as those Guided Interviews have used the same naming conventions for variables.
Suggested Variable Naming Convention
The examples in this Appendix were formulated by consulting formats developed by Marc Lauritsen of Capstone Practice Systems and Jeff Hogue of Legal Aid of Western New York; the LSXML schema, a standard for exchanging information between different law-related software; and, some peer review by other developers.
Variable Formatting
In general, variable names are formatted with a capitalized first word, normal spaces, and then two capital letters at the end. These two capital letters tell everyone what kind of variable it should be: Text, Number, Multiple Choice, etc. For example, the variable you assign to capture the client’s first name should be called [Client name first TE]. TE stands for “text”. If you use a proper noun, though, capitalize the proper noun, e.g., [Landlord is Massachusetts corporation TF].
Variable Suffix
The variable types and corresponding suffix conventions you will use most often in A2J Guided Interviews® are:
|
Variable Suffix |
Variable Type |
Description |
|
TE |
Text |
Use for the vast majority of variables. Numbers are usually stored as text variables unless used to calculate something. Ex: Client name first TE or Client postal code TE |
|
MC
|
Multiple Choice |
Use when you want the end-user to pick a single answer from a list or series of “radio buttons”. (Note: Use true-false variables when you want to allow the end-user to select more than one choice from a list.) Ex: Client state MC |
|
DA |
Date |
Use when a specific date is captured. Ex: Client birth date DA |
|
TF |
True/False |
Use when the result can only be true or false. Ex: Print bad conditions factsheet TF might be set in an A2J Guided Interview® to decide whether or not to print a certain factsheet with the output. |
|
NU |
Number |
Use when the variable is used in a math equation. Ex: Client asset amount NU |
|
CO |
Computation |
Used in HotDocs® templates, NOT in A2J Guided Interviews®. It is most often used to combine other variables. Ex: Client name full CO Can be set to equal = Client name first TE + Client name middle TE + Client name last TE |
Community Standard Examples
The following are examples of variables widely used within the document assembly community.
Client Information
The Client is the person who will be filing the pleading, or the “person served.” Only programmers see this variable name, so we use Client, understanding that we don’t mean a client of an attorney.
|
Variable Name |
Description |
|
Client name first TE |
|
|
Client name middle TE |
|
|
Client name last TE |
|
|
Client suffix MC |
|
|
Client address line1 TE |
|
|
Client address line2 TE |
|
|
Client city TE |
|
|
Client county MC |
(If client might be from another state, this can be Client county TE) |
|
Client state MC |
There is a standard external file called ussstates.xml |
|
Client postal code TE |
This is the zip code, but postal code matches the xml lingo. |
|
Client address CO |
HotDocs® variable that combines the address info |
|
Client phone home TE |
Today, cell and home phone are often the same |
|
Client phone cell TE |
|
|
Client phone alternate TE |
Phone that belongs to family or shelter |
|
Client marital status MC |
We need a standard list of status choices. |
|
Client mailing address line1 TE |
|
|
Client mailing address line2 TE |
|
|
Client mailing city TE |
|
|
Client mailing state MC |
There is a standard external file called ussstates.xml |
|
Client mailing postal code TE |
|
|
Client birth date DA |
|
|
Client email address TE |
|
|
Client has children TF |
True/false variable that is set to true if client has children. Generally, this should mean client has children in the financial household, since this variable might be used for eligibility in some interviews. |
|
Client is married TF |
|
|
Client primary language TE |
|
|
Client ethnicity TE |
|
|
Client citizenship MC |
USA, for example. Oddly, LSXML uses a 3 letter code for countries. A standard list is needed. |
Adverse Information
When there is only one opposing party, use Adverse as the tag for the opposing party. If you have more than one opposing party, identify them by role: [Undertenant name last TE], etc. We are not creating standards for all of these potential roles.
|
Variable Name |
Description |
|
Adverse name first TE |
Could be the soon-to-be-former husband |
|
Adverse name middle TE |
|
|
Adverse name last TE |
|
|
Adverse suffix MC |
|
|
Landlord1 first name TE |
If it is possible to have two adverse parties, identify by role. (Linda and Lenny Landlord both brought the eviction proceeding) |
|
Landlord2 first name TE |
|
Spouse Information
|
Variable Name |
Description |
|
Client is married TF and Client is divorced TF If using a multiple choice option, then use: Client marital status MC |
Marital status. |
|
Spouse name first TE |
The spouse name variables follow the same convention as the client names. |
|
Spouse birth date DA |
|
|
Spouse gender MC |
|
|
Spouse information dialog CO |
HD only |
Child Information
|
Variable Name |
Description |
|
Children NU |
Number of children in the household. If you need a different count, such as minor children or children not in foster care, use a different variable. |
|
Child name first TE |
Same convention as the client name variables. |
|
Child gender MC |
|
|
Child state MC |
|
|
Child birth date DA |
|
|
Children dialog title CO |
HotDocs® only |
The default questions in a new Guided Interview in A2J Author® use variables according to this convention. Keep in mind, however, that the standard naming convention issue has yet to be settled, and we expect that standards acceptable to most developers will change, even if only slightly, from what is suggested here. As this Authoring Guide is a living document, it will be revised as needed in accordance with standards ultimately accepted by the authoring community. To ‘stay tuned’ to the standards conversation occurring most frequently on the Document Assembly listserv, request a subscription to that list at the following location: http://lists.lsntap.org/cgi-bin/mailman/listinfo/docassembly