Create an Answer Source Integration

From HotDocs Wiki

Jump to: navigation, search

To create an answer source integration

  • Create an answer source DLL.

An answer source is a standard Microsoft Windows 32-bit Dynamic Link Library (DLL) that provides a link from HotDocs to the source application through a defined API that the answer source DLL implements. This API consists of a number of functions that HotDocs uses to communicate with the source application. The answer source DLL can be written using any language which supports the creation of standard Windows DLL files.

The answer source DLL allows HotDocs to query the application for the data it needs to populate the fields of a HotDocs dialog when asked. For this to work, the following must be true:

  1. HotDocs must be able to determine if the answer source is installed correctly and if it is ready to be called. (See IsAvailable.)
  2. HotDocs must be able to retrieve a list of names and types of all available fields in the answer source. This information will be used when mapping variables to the fields in the answer source. (See GetFieldName.)
  3. HotDocs assumes the data source contains records which can be uniquely identified by a 32-bit integer.
  4. The answer source must display (or cause to be displayed) some user interface whereby users can browse or search the data in the application and select a record. The answer source must then return to HotDocs the 32-bit ID of the selected record. (See ChooseRecord and ChooseMultipleRecords.)
  5. After the user chooses a specific record, HotDocs must be able to use the 32-bit record ID to request data for specific fields of that record. (See GetField.)
  • Register the answer source DLL.

Once the answer source DLL has been created, it must be saved in the HotDocs program files folder (for example, C:\Program Files\HotDocs 6). In addition, you must create a registry entry that allows HotDocs to recognize the DLL and display it at the Dialog Editor. This registry entry is also used during an interview when the user attempts to access the answer source.

To create the registry key, navigate to HKEY_LOCAL_MACHINE > SOFTWARE > HotDocs > HotDocs > Answer Sources. (Versions prior to HotDocs 10 will instead use HKEY_LOCAL_MACHINE > SOFTWARE > LexisNexis > HotDocs 6 > Answer Sources; you may need to create the Answer Sources key.) Then create a new string value in this key using an easily identifiable name for the answer source. (This name is what appears in the Answer source drop-down list at the Dialog Editor.) The value should be the file name and extension of the answer source DLL.

Once this answer source DLL is created, registered, and saved to the HotDocs program folder (for example, C:\Program Files\HotDocs), HotDocs will call this DLL to obtain the information it needs from the application.

  • Map HotDocs variables to answer to answer source fields.

In this step, you must associate the answer source with dialogs in your HotDocs templates. This is done by specifying an answer source at the Options tab of the Dialog Editor. Once the answer source is selected, the template developer must then map (associate) variables in the dialog to fields in the answer source.

When matching fields in the answer source to variables in HotDocs, it helps to understand that HotDocs recognizes five basic data types: text, number, date, Boolean, and multiple choice. Any fields in the application that you wish to allow users to map to HotDocs variables should be associated with one of these types. Each type has an integer equivalent that is used in calls to the answer source DLL. These integers, as well as other specific information about each HotDocs data type, is listed here:

HotDocs Data Type Integer Equivalent Notes
TEXT 1 Text values in HotDocs are 8-bit strings (Windows-1252 or Latin-1 encoding) up to a maximum length of 15,000 bytes.¶
NUMBER 2 Number values are passed to HotDocs as strings. Numbers are always interpreted in base 10. Both decimal and integer values are accepted.¶
DATE 3 Date values are passed to HotDocs as strings. Dates should be formatted in an unambiguous manner when passed to HotDocs, for example, as YYYY-MM-DD. HotDocs does not currently support time values.¶
TRUE/FALSE 5 True/False (Boolean) values are passed into HotDocs as strings. To pass a true value in, the string should contain the word TRUE. To pass a false value in, the string should contain the word FALSE
MULTIPLE CHOICE 6 Multiple choice values can be passed into HotDocs two ways—as single-select values or as multiple-select values. Single-select values are passed as simple strings. Multiple-select values are passed as delimited strings, with multiple answers delimited by the vertical bar ( | ). For example, "Value1|Value2|Value3" would pass three values to HotDocs.

(Note: In earlier versions, you could use the string <^> to delimit options. While this delimiter still works, you are encouraged to use the vertical bar instead.)¶

UNANSWERED If the answer source returns an empty string when HotDocs requests a value, HotDocs will not change the current answer. Answer source DLLs can cause HotDocs to clear an existing answer by passing a special string token to HotDocs: <^UNANSWERED^>.¶

Once the answer source is specified and the variables are mapped, HotDocs displays a Select button in the answer-gathering dialog for these questions. When the user clicks Select, HotDocs displays a modal dialog box with the available records from your application. When the user selects a record, the information in the record is automatically merged into the corresponding answer files in the dialog.