This reference is designed to assist you when creating document templates, formerly called print templates. The syntax required for inserting field variables, formulas, conditions, and other elements are listed below.

Field Variables

Field variables can be inserted into document templates so that the field's value is displayed in the document when the document template runs.

The general form for field variables is $FieldLabel.  For example, in the People table the variable for the Login field is $login.

You can construct chains of field variables to find values in other tables linked to the current record. These are in the form $Field1.Field2 where Field2 references a field in another table linked through Field1. Field variable chains must be constructed manually by locating the appropriate field names in each table.

Syntax

$formula($field) 
$formula($field1.field2)

Examples

Note that if you are putting dollar signs ($) into a document template to format values in a number field, you can enter a backslash (\) to ensure that the dollar sign does not get eliminated by the system while it is processing the variables and formulas in the document template. For example, \$25,000 will appear as $25,000. You can configure the system so that it does not eliminate the backslash by changing the value of the Keep slash prior escaped dollar sign global variable to Yes. 

View or Download Field Variables

A list of field variables for the current table can be displayed when creating or editing a document template.

• Click Show Field Variables to open the Formula Help wizard with a list of the Fields, Global Variables, and Functions.
• Click Download Template to save an MS Word file which lists the field name and field label for each field in the current table.

Formulas and Conditions

Formulas and conditions are used in document templates to calculate totals, insert different fields based on the values, and insert or delete text when a condition is met. A longer list of available formulas can be found in the Formula Help window, available from the Mass Edit Wizard and other system locations.

The following formulas and examples represent the most common uses and will help you create complex document templates. 

Basic Formulas

Standard mathematical operations can be used with numeric data types such as integer, floating point, and calculated result fields.

Syntax

$formula($equation)

Examples

Concatenate Strings

The concatenate strings command allows you to combine field values with text strings, field variables, or other formulas that use variables. For example, if you use $formula(concat("x",$field_name,"z",...)), the "x" and "z" placeholders are where you insert text strings, field variables, or formulas.

It can also be used when inserting a Choice field value, if the value is rendered as code such as 1@2 rather than the text of the value. To do so, enter the value as the only parameter.

Syntax

$formula(concat("x",$field,"z",...))

The variables may be text strings, field variables, or other formulas and variables. Text strings must be surrounded in double quotation marks (""), while variables and formulas do not.

If the first piece is a text string, you can use shorthand to combine variables and strings, but $formula() is still required in email templates:

$formula("x"+$variable+"z"+...)

Examples

Dateformat

Dateformat() is used to display a date/time field in a particular format, often for localization. Dateformat() takes two arguments: the desired pattern format, and the field variable. Date time patterns are indicated with a series of letters that represent elements such as month, day in month, day of week, year, hour, and minute. For a full list of possible formats see this page from Java about SimpleDateFormat().

Syntax

dateformat("output pattern","$field")

Examples

The following results are expected when $contract_start_date evaluates to February 10, 2016 at 01:00:00.

num2words

The num2words formula converts numerals into words. For example, you can use the function to render "12" as "twelve," "twelfth," or "12th," or you can format it as currency. If you want to output words in another language, you can specify an alternate language code as the last parameter. The currency option requires a language to be specified in order to identify the appropriate currency.

The format options are cardinal; ordinal; ordinal_num, which renders the ordinal format with numerals; and currency, which requires a language code.

The first input parameter must be a numerical value. For ordinal formatting, the number must be an integer. The default format is cardinal, and the default language is U.S. English.

Syntax

num2words(value, "format", "language")

Examples

Document Template Examples

In a document template, use the $formula wrapper. These examples render a contract value of $1,000.20, with the second example capitalizing the first word.

Format Formula Outputs

format() is used to determine the output format of a formula based on the display characteristics of a chosen field. It is most commonly used to set the appropriate display for the output of a formula that includes Currency fields.

Syntax

$formula(format("table_name.field",$value))

In the syntax above, table_name.field is the reference to the field whose formatting you want to use.  For instance, contract.dollar_amount could indicate using the $1.00 standard US currency display format. The formatting field can be referenced from any table. The $value may be any valid formula such as a field or formula including multiple field variables.

Examples

The following example formulas will help you create your own formulas.

Conditional Text, Paragraphs, or Clauses

A common requirement is whether to show words, multiple lines, or paragraphs of text based on the values in a record or a condition based on those values. Conditions can use a full range of logical operators such as == (equivalency), != (not equal), >, <, >=, <=.

Ternary Operator

Short conditional statements can be inserted with the ternary operator "a ? b : c." This works like an if-else statement: if the condition "a" evaluates true, then insert "b;" if "a" is false, insert "c." You must provide all parameters for the ternary operator to function, even if one parameter simply inserts a blank space. If you want to output a string in the b or c parameters, include quotation marks around the string.

The ternary operator is useful in formulas that divide by a variable, where that variable might sometimes equal zero. Otherwise, the attempt to divide by zero results in an error. Use the ternary operator to check whether that variable is zero and then provide formulas for each situation. For example, if you want to calculate a percentage using two fields, but $field2 might sometimes equal zero, you could use "$field2 == 0 ? 0 : 100*($field1/$field2)" to output zero if $field2 is zero and otherwise output the calculated percentage.

In some cases, the ternary operator might unintentionally render a Choice field value as code, such as 1@2, instead of the text of the value. To show the text instead, use the concat() function inside the ternary syntax. For example: $formula($choice_field=="Choice A" ? concat($preselected_value_in_choice_field2) : concat($ preselected_value_in_choice_field3))

Syntax

$formula($condition ? "True Output" : "False output")

Example

In this example the statement compares the variable $n to the value 1. If it is 1, "$n is 1" is shown. If it's not 1, "$n is not 1" is shown.

($n==1) ? "$n is 1" : "$n is not 1"

In this example, the statement uses functions inside the ternary formula. This outputs information about the delegation timeline, if the delegation is time-based, and otherwise states that the delegation isn't time-based. Notice that inside the ternary function, $formula is not used a second time.

$formula(($delegation_type=="Time-Based") ? "Delegation from " + dateformat("MMM dd, yyyy", $delegation_start_date) + " to " dateformat("MMM dd, yyyy", $delegation_end_date) : "Delegation is not time-based.")

Additional Examples

If-Then-Else Conditions to Display Field Variables

The $if statement evaluates a condition to decide which field variable to display. It is similar to the ternary operator, but the true and false outputs may only be field variables or the $merge command with an attached file field.

Syntax

$if(condition) ? $fieldTrue : $fieldFalse

The second (else) field variable may be left out to display blank if the condition is not met.

$if(condition) ? $fieldTrue

Or, the $merge($filefield) command may be used as an output:

$if(condition) ? $merge($filefield) : $fieldFalse

Examples

Conditional Paragraphs using $startif

Use the $startif() command in a document template if some paragraphs of text should only be included under certain conditions. For example, suppose a certain liability clause only appears in a final contract when the contract amount is over $50,000. The conditional text comes after the $startif($condition) and is followed by $endif to close the statement.

Syntax

$startif($condition)
Paragraph 1
Paragraph 2
$endif

Examples

isEmpty

The isEmpty operator checks whether a field has a value or not, and is formatted as follows:

isEmpty($field)

This returns true when the $field is null or empty and false if the field has a value.

New line or insert line break

To insert a new line or a line break, use \n within a document template or field value formula. This can help start new paragraphs in certain cases.

Merge Documents

The $merge command can be used to merge multiple files held in a single field, or files held in multiple fields into one final document.

Using the $merge($fieldname) command within a document template will merge all attached .docx/.html files from the field in the current record into the resulting document template's .docx file. Documents held in a versioned file field will be merged in the order in which they were uploaded or appended to the field.

Syntax

To merge multiple documents held in a single file field with versioning or multiple files enabled:

$merge($fieldname)

To merge multiple documents held in separate file fields, use the format:

$merge($field1) $merge($field2) $merge($field3) ...

This makes it possible to compile a large PDF or Word document from several attachments.

The $merge command must be placed within the body of the document template. This function will not work if the $merge function is placed within the header or footer of the template, or within a table.

Integration

You can choose to configure a document template to automatically push changes that occur to field values or formulas of the Word document back to the pre-existing record in the KB. You can tag field and formula references, as well as references to fields from other tables. This is a valuable feature that ensures the value in the document template and the value in the actual record stay synchronized. These tags are also recognized as annotations when the generated documents are used with the Agiloft add-in for Microsoft Word. The options for tagging data can be found beneath the Published section of the Word/PDF Template:

Agiloft Contract Assistant print template settings

You can select one or more options:

• Automatically tag field and formula references in the document template: this option is used to tag metadata in the document template.
• Automatically tag references to $field_from_other_table: this option is used to tag contract clauses in the document template. You can choose to use Contract Clause table variables within tags for identification purposes and additional detail. 

The "tags" mentioned by the system text are actually ContentControl objects, which are the colored boxes you see in Microsoft Word when something has been labeled. When the document is opened in Microsoft Word with the  Agiloft add-in installed, the tags hidden in the document's text by the options above are identified and listed as annotations on the Annotations page of the add-in. This can be used to automatically generate annotations in the add-in without the use of AI.

Bookmarks in Templates

You can add bookmarks to Word templates and configure your system to preserve the bookmarks in the finished output. To do this, go to Setup > System > Manage Global Variables, open the Customized Variables tab, and select New > Choice Constant. Create a new global variable named print_template_remove_bookmark and set it to No.

Bookmarks can only be preserved in Word-format document templates, not PDF or HTML formats.