Values Overview

A value is a piece of data of a type that HotDocs knows how to process. For example, HotDocs can process the number value "2" and the text value "Jane Doe".

Overview

In HotDocs, every piece of data you encounter is a value of a particular type, whether the actual value is currently known or unknown. All values in HotDocs Author are either known to you when you are authoring your template, or they are as yet unknown. In the case of known values, you provide them when you build your template. In the case of unknown values, you are seeking this data from your template users, for example through an interview. You arrive at a previously unknown value by evaluating an expression (the most simple case is a variable that HotDocs evaluates by looking up the answer a user supplies for that variable in an interview) or a computation using the HotDocs scripting language. You most often actively consider and use values when writing a script. The HotDocs scripting language exists so you can evaluate, calculate, and work with values. When writing a script, you express values as literals (part of the HotDocs scripting language syntax).

Common Tasks

Among others, a value enables you to perform the following common tasks:

Workflow

The most common way to obtain a value is from your end user when they answer questions in your interview. When scripting, you can also pass a value into a computation using a parameter. Similarly, you can provide a value to a dialog script using a local variable you set to a particular value. In addition you can SET a variable TO a known value of your choosing.

Known and Unknown Values

All values in HotDocs Author are either known or unknown when you are creating a template.

Known Values

When you write a script in the HotDocs scripting language, you often deal with known values. A known value is a value you already know at the time you are creating your template. For example, when create a Fixed Table component, you fill the table with data whose values you know. In the scripting language syntax, you express a known value as a literal.

Unknown Values

An unknown value is any value you do not yet know when you are creating your template. You can gather unknown values from your template users, or you can calculate them. There are several types of elements in HotDocs Author that enable you to represent unknown values:

Variables represent values that are not known at the time you are writing a template or script, but which you think you'll need during document assembly. Typically your template user types these values as answers to the interview questions.
Local variables represent unknown values that you define and manipulate only in the context of a specific script. The value is not provided by an interview user, but by calculations within the script.
Parameters represent unknown values that are specific to the context in which you want to call a computation (a call to a computation comprises the computation’s name, and if relevant, a list of parameters).
Computations each represent a calculated value the computation arrives at by evaluating the computation’s script. Similarly, Functions also represent values determined by logic internal to HotDocs. You make these values known by calling the respective function.

In all of the above cases (collectively, “unknown values”), when you want to refer to the unknown value, you do so using the name of the variable/parameter/computation/function that represents it. During assembly, the name resolves to a specific value. For instance HotDocs resolves the value represented by a variable's name by looking up the answer to that variable within the answer file. HotDocs resolves the value represented by a parameter's name by getting the value that was passed in for that parameter. (You could think of the list of parameters to a computation or function as a local mini answer set containing the values passed into that function.) HotDocs resolves the value represented by the name of a computation by evaluating the computation's script. Similarly, HotDocs resolves the value represented by the name of a function by performing whatever calculation the specific function performs.

In addition to representing an unknown value, some items take inputs that can be either known, or unknown values themselves:

Functions (or computations) typically take one or more values as an input (parameter) and produce a single value as a result. As noted above, you refer to the value represented by a function using the function’s name. This use of a function name (in the context where you want its value) is known as a function “call”; you call the function to request its value and the function executes, evaluating the script to produce a result.
Operators are a special kind of function with a streamlined syntax. While some operators (like functions) have names (for example, CONTAINS or STARTS WITH), most are represented by mathematical symbols (+, -, *, /). Instead of accepting (as input) a list of parameters, an operator accepts (as input) either one or (most commonly) two operands.

Value Types

Whether known, or unknown, each value in HotDocs is of a particular value type. A value type is a classification that identifies the kind of data the value contains. HotDocs uses four primary types of data HotDocs, called primitives:

These four primitive value types correspond to the variables of the same name. That is, a Text variable collects data of the text value type.

You can also gather data of one of these primitive types as the answer to a Single Select variable. You mark a single column of data in an option source (e.g., Built-in Table, Fixed Table, Table variables, or repeated dialogs) as a key so that the answer to a selection variable is a single primitive value type.

In addition, if your value requires more than one piece of data, you can use a record value. The record value type is a composite value combining one or more values of the same or differing value types.

You can also create a list value, which consists of a list of only one primitive value type, or a record list value, which consists of only record values.

Every list of values only accepts values of a particular value type. You cannot (for example) add a number value to a text list.

To gather image data, you use an image value.

You can read more about each of these value types below:

Text Value

A text value is any value you can express using alphabetic and numeric characters. For example:

85 South Street, Hobble Creek, A01, is a text value even though it contains letters and numbers
A Social Security number 555-55-5555 or any other ID number that contains any non-numeric characters other than a comma or decimal (such as a letter, dash, hyphen, colon, etc.) are also stored as text values in HotDocs, even though the general public usually thinks of such items as numbers

To gather a text value in an interview, you use a Text variable or a Single Select variable, then mark a single column of data in its option source as a key. To express a text value in a script, you use a Text literal.

Text Literals

To express a text value in a script, you use a Text literal. You express a Text literal as a string of characters within quotes:

"This is a text literal." For more information on working with Text literals, see Important Considerations when Working with Text Literals.

Number Value

A number value is any value you can express using only numeric characters (i.e. those that can be used in arithmetic, such as loan amounts, client age, etc.). For example:

55 is a number value
Numeric characters with commas and periods used as thousands separators or decimal points (e.g. 27,900.32) are also number values
"Numbers" that contain non-numeric characters other than commas and periods (e.g. 12:30 or 555-55-5555) are not number values, but are text values

To gather a number value in an interview, you use a Number variable or a Single Select variable, then mark a single column of data in its option source as a key. To express a number value in a script, you use a Number literal.

Number Literals

To express a number value in a script, you use a Number literal. You express a Number literal using only digits, and can include a decimal point, as follows:

7 1.25 0.75

In addition:

Numbers cannot contain commas (1250 not 1,250)
Decimal numbers less than one must have a zero before the decimal point (0.125 not .125)

Date Value

A date value is any value that you can express using any combination of the day, month, year (including the day of the week) in any sequence of your choice. For example:

11 June 2021 and 6/11/2021 are date values

The time of day (e.g. 12:30) is not a date value

To gather a date value in an interview, you use a Date variable or a Single Select variable, then mark a single column of data in its option source as a key. To express a date value in a script, you use a Date literal.

Date Literals

To express a date value in a script, you use a Date literal. You express a Date literal in day, month, year order, (abbreviating the month) as follows:

11 FEB 1964

True/False Value

A true/false value is any value that you can express as TRUE or FALSE. For example:

Any interview question that can be answered yes or no has a true/false value.

To gather a true/false value in an interview, you use a True/False variable or a Single Select variable, then mark a single column of data in its option source as a key. To express a true/false value in a script, you use a True/False literal.

True/False Literals

You express a True/False literal as:

TRUE or FALSE

List Value

A list value is a list of values of a single value type, e.g., a list of text values, or a list of date values. A list cannot store more than one type of primitive value. For example:

A repeated dialog that asks the variable Child Name collects a list of text values containing all the names of the template users' children; if there is only one child, the list has only a single value

To gather a list value in an interview, you can use a repeated dialog, or a Table variable. To express a list value in a script, you use a List literal.

HotDocs pays attention to the number, the type, and the order of the items in a list. There are some ramifications to comparing list values that involve unanswered items in a list. To learn more, see the Three-valued Logic Overview.

The list value is also the basis for the LIST CONTAINS EXPRESSION operator model you can use in a computation or expression to check if a list contains a particular record value as part of a conditional region.

List Literals

A List literal begins and ends with square brackets, and the values in the list are comma separated as follows:

Text list: ["John", "Mary"]
Number list: [5, 2]
Date list: [5 JAN 1984, 22 SEP 1990]
True/False list: [TRUE, FALSE]

A List literal also displays the literal syntax for the value types it expresses. For example, the quotes in the forgoing List syntax tells you that it contains a list of Text values. When comparing one List literal to another, order matters. When comparing two list literals, like this:[Sam, Jim, Sally] = [Sam, Jim], the comparison evaluates to FALSE.

Record Value

A record value is a composite value that combines one or more values of the same or differing value types. For example:

The combination of the text values First Name, Last Name is a record value composed of two text values
The same two pieces of data combined with the date value Birth Date is a record value composed of differing types of values

Record values are useful with Single Select variables. To gather a record value in an interview, you use a Single Select variable, then choose an option source other than Built-in. You mark multiple columns of data in its option source as keys so that the answer to the Single Select variable is a record containing the data from two or more columns of that option source. To express a record value in a script, you use a Record literal.

A record value stores a field name, the type of the field (say text, number, or date) and the value of the data in the field. Unlike a list, the order in which the fields occur in the record does not matter. For example, if in a script, you compare two Record literals like this: {F1: Jim Fitzgerald, f3: James Clarke, f2: Matilda Percy} = {f2: Matilda Percy, F1: Jim Fitzgerald, f3: James Clarke} the comparison evaluates to TRUE.

Record Literals

A Record literal value begins and ends with curly braces, and its values are comma separated as follows:

{Name: "John", Birth: 5 JAN 1984, Children: 5}

A Record literal also displays the syntax of the type of the value of the data it stores. For example, the name in quotes in the example above tells you that the Name: field is a text value, while the digit without quotes in the forgoing Record literal tells you that the Children: field contains a Number value expressed as a literal. When comparing two Record literals, the order of the fields in the two Records is not important, as long as the types and values for each field match one another.

Record List Value

A record list value is a list of record values, e.g., a list of the same composite values. Just as with a regular list, the record list can only contain a list of the same value type. For example:

If you gather a list of Employees, the underlying record must contain the same consistent data, say the text values First Name, Last Name, and the date value Date of Birth; you would then have a list of this record type

To gather a record list value in an interview, you use a Multi Select variable, whose option source is a Table variable, then mark multiple columns of data in the Table variables as keys so that the answer to the Multi Select variable is a list of record values containing the data from two or more columns of that Table variable. To express a record list value in a script, you use a Record List literal.

Record List Literals

A Record List literal represents a list of Record values and combines the formats of List literals and Record literals in that the brackets of the List literal enclose the curly braces of the Record literal as follows:

[{Name: "John", Birth: 5 JAN 1984, Children: 5}, {Name: "Mary", Birth: 22 SEP 1990, Children: 2}]

Because this is a list, unlike a record value, the order of the items in the list matters. Therefore, if you were to compare two record list literals as follows:

[F1: Jim Fitzgerald, f3: James Clarke, f2: Matilda Percy, f6:06 JUN 1989, f9: 27 September 2017] = [F1: Jim Fitzgerald, f3: James Clarke, f2: Matilda Percy, f9: 27 September 2017, f6:06 JUN 1989] the comparison evaluates to FALSE.

For lists, equality means the same number and the same order for each slot in the list. There are some other ramifications to comparing list values that involve unanswered items in a list. To learn more, see Three-valued Logic Overview.

Image Value

An image value is an image to be entered by the template user as an answer, such as a client's logo or a photograph of damage to support an insurance claim.

In interview, HotDocs Advance supports JPEG and PNG file formats image files as answers, with a default maximum file size of 10MB.

To gather an image value in an interview, you use an Image variable.

Common Reference Topics

Among others, the following reference topics may relate to this conceptual area: