Common Confusions

In HotDocs there are a some features which, while working as expected, may at first seem counter intuitive. The following is a list of common confusions and known issues:

See the Troubleshooting section of this help file to resolve other issues you encounter.

Template Development

Microsoft Word Features that Cannot Be Used with HotDocs

There are a couple of Microsoft Word features that are not supported in HotDocs templates. To avoid errors, we recommend you remove the following features from your documents before converting them into templates:

• Mail merge
• Smart quotes

Microsoft Word 2016 Right-click Menu Restrictions

Due to a change by Microsoft, custom right-click menus are no longer possible in Microsoft Word 2016 and later. As a result, right-clicking on HotDocs fields within Word templates will no longer present a custom menu allowing you to edit the field or related component. This is unfortunate, but expected, behavior. HotDocs fields can still be edited by double-clicking in Word, and fields and components cat still be edited using the HotDocs ribbon in Word as well.

Using Smart Returns

We recommend becoming familiar with how HotDocs uses smart returns after inserting an instruction, before you develop any complex templates with multi-level lists. The way you set the smart returns options can alter the formatting in your assembled document. You can set your default options for smart returns at the HotDocs Options dialog box.

Clauses and Clause Libraries

HotDocs Clauses and Clause Libraries are an old feature which we do not recommend relying upon for your template functionality.

Dialog Element Image Display Issues in Browser Interviews

When you develop a template for browser interviews, we recommend you thoroughly test how images display when included as dialog elements because  Silverlight and JavaScript handle image display in slightly different ways. If an image is too big to fit in the allotted space, Silverlight interviews clip the image, while JavaScript interviews resize the image. To avoid any display issues, in such cases, we recommend you resize the image so that it displays equally well in both Silverlight and JavaScript.

Using Multiple Choice Merge Text

If you are using merge text in a computation variable, make sure you remember to use quotations around the multiple choice variable name otherwise you will be using the option text. For example using «MCVariable» will use the option text in the assembled document but using "«MCVariable»" will use the merge text.

Apparent Issues with Dot Codes

Sometimes, it can appear that special characters are being considered as punctuation, so that the assembled document omits (for example)  the period. 

The behavior of the sentence punctuation dot codes—the dot codes for period (<<.>>), comma, semicolon, colon, exclamation point, and question mark—insert punctuation only if the preceding character is not another sentence punctuation of the kind that HotDocs inserts. For example, the period dot code will insert a period after a closing parenthesis, but will not do so if the dot code is preceded by an exclamation point.

Ampersands in Variable Prompts

You can type an ampersand (& ) immediately before a character in a variable prompt to make that character an accelerator key. During the interview, an accelerator key enables the user to move the cursor to that answer field by pressing the Alt key while also pressing the underlined character in the prompt. This functionality can create an issue if you need to include a word in your prompt that has an ampersand immediately preceding a character. To do this without creating an accelerator key, you must type two ampersands (&&) where you want the ampersand to appear as a single ampersand. For example, to have "R&D" as your variable prompt you would need to type "R&&D".

ASSEMBLE instructions must be included in the template as well as in the interview script

To ensure that templates are added to, and remain in, the assembly queue, you should include identical ASSEMBLE instructions in both your interview and template scripts. This way, no matter which script HotDocs processes last, it will put the desired templates in the assembly queue.

Template Uploading

Template ID Conflicts

When uploading multiple templates, you may encounter an issue with duplicate template IDs. If two or more templates share the same template ID, HotDocs generates an error message alerting you to the problem, and specifying the templates that are in conflict.

A conflict of this sort most often occurs in cases where you copy a template (whether using Widows Explorer, or HotDocs native copy a template feature) to avoid recreating all the components in the accompanying component file. Since HotDocs assigns a unique ID to each template, merely copying a template to another location in this way, and even renaming that copy, does not change the template ID. In such cases, you end up with two templates, each with the same ID number. The proper method for creating a copy is to use HotDocs to create a new template based on an existing template.

You can fix the problem that caused the error message by following the steps below:

To change a template ID number

1. In the HotDocs Developer library, select the template whose ID you want to change.

2. On the right side of the toolbar at the top of the library, click Component Manager; then just below the Save icon, click Component File Properties.

3. On the General tab, to the right of the Template Identifier box, click New. This updates the template ID.

4. Repeat until you resolve all ID conflicts; then try uploading again.

Document Assembly

Problems with Text Pushing Too Far to the Left Side of the Assembled Document

Templates developed in Word 2007 with smart tags enabled can display text incorrectly. This results from a bug in Microsoft's Open XML Format SDK. If you have templates automated from documents developed in Word 2007, be sure to remove the smart tags in your templates  or ask your template developer to resolve this problem.

Enabling Update table of contents, references, fields etc in HotDocs Server templates

On the HotDocs Server tab of Component File Properties, if you enable Update table of contents, references, fields, etc option, you may find that it does not produce exactly the same results as the desktop option of the same name on the Assembly tab. Unlike in desktop HotDocs, using this feature with server is known to occasionally alter or lose advanced formatting features in the assembled document. Not enabling this feature removes the chance of this error occurring but you loose the ability to dynamically update the table of contents, references, fields etc in the interview. If you choose to use this feature when converting a template for use with HotDocs server, we recommend testing all features that previously relied on the desktop version of this option.

Using the /nw Command-line Switch with the /of Switch Does Not Support Converting a Document to PDF

Server Assembly Behavior Differs from Desktop

Using a SET instruction in a repeated dialog script can result in unanswered repetitions in the assembled document

In a dialog script, if you SET a variable to an answer in a repeated dialog script without using a condition on the SET instruction, HotDocs sets that variable every time you create a new iteration of the dialog. As a result, your answer file may contain more answers than what you intended. (This is especially true if the variable in the SET instruction is hidden on the dialog.) Although you may not see that repetition in the interview, it exists in the answer file.

During a desktop assembly, HotDocs keeps track of how many repetitions of the dialog are visible and then uses that information when assembling the document to prevent seemingly unanswered repetitions from appearing in your document. However, if you perform the assembly silently (without showing the assembly window), or you perform the assembly using HotDocs Server, HotDocs does not track the number of repetitions shown in the interview and must assemble the document based only on what is available in the answer file.

You can avoid the situation where these extra, unanswered repetitions appear in your assembled document by adding an IF instruction to the dialog script so that the script only SETs the variable if some other variable in the repetition is answered. Likewise, you can add a FILTER on the REPEAT instruction in your template to filter out any unwanted repetitions in which the only answered values are the ones that are hidden.

The following is an example of a dialog script that only SETs a variable if you answer another variable:

HIDE Repeat Variable

IF ANSWERED(Test2)

SET Repeat Variable TO “AutomaticallySetValue”

ELSE

SET Repeat Variable TO UNANSWERED

END IF

Special characters that cannot be used in Cloud Services package IDs

'/', '\', and '?' cannot be included in the template name when you are creating a template package for use in a HotDocs Cloud Services direct interview.

Update Table of Contents, References, Fields, etc. Option

There are potential formatting issues in your template if you select the “Update table of contents, references, fields, etc.” option on the HotDocs Server tab of the Component File Properties dialog. While we review all reported formatting issues, some issues cannot be addressed:

• Paragraphs numbered using the AutoNum field do not format correctly. Microsoft considers this field obsolete and suggests you use the ListNum field. To avoid this issue, you may also consider updating your template's paragraph numbering using Word's Numbering found in Paragraph group of the Home tab.  

Known Issues

The following issues are known and are either not addressable by HotDocs as they originate in external software or are planned to be resolved the future releases. In the meantime you can use the workarounds listed below:

• Multiple choice variables populated using a SET instruction do not differentiate between upper and lower case when you edit an answer in the interview. For example, the multiple choice variable won't honor changing the answer "JOHN DOE" to "John Doe". It continues to display the uppercase answer until you make a character change, only then does it recognize you have typed in a new answer. To avoid this problem you need to add an ERASE VAR instruction to the beginning of your computation, rather than using CLEAR VAR. For example, a computation like this would honor the changes between upper and lower case:

ERASE MCVariable

ADD Txt1 TO MCVariable

SET MCVariable TO Txt1

• Double ampersand is not escaped correctly in the dialog title when the Combine Default Dialogs option is selected. When the Combine Default Dialogs option is on, HotDocs takes the variable title, for example "R&&D", and instead of correctly escaping the first ampersand, so it appears in the interview correctly as "R&D", it appears incorrectly as "RD". To avoid this issue it is best to not use Combine Default Dialogs if you want to use ampersands in your dialog titles and instead create your own dialogs using the component file.
• If you try to assemble a .dot template on a new installation of HotDocs Developer, Windows is occasionally unable to open Microsoft Word correctly to assemble the document. To avoid this problem HotDocs recommends assembling an .rtf or .docx template after installing a new version of HotDocs Developer. If you do assemble a .dot template first, and experience this issue, you need to remove the template from your library, restart HotDocs Developer, then add the template again. That should solve the issue.