HotDocs Answer Source API

Every answer source DLL must expose and implement the following four entry points: IsAvailable, GetFieldName, ChooseRecord, and GetField. In addition to the required entry points, HotDocs 2005 SP2 introduced eight additional entry points to facilitate multiple record selection and two-way communication between HotDocs and the answer source. (For example, these entry points allow HotDocs to write answers back to the answer source if they are changed during the interview.)

Your answer source DLL must export these functions by name, without any C++ name mangling; that is, they must be exported as standard C language functions. Also, they should be declared to use the WINAPI calling convention (__stdcall in Visual C++).

Answer Source DLL Entry Points (Functions)

Function	Description
BeginUpdateBatch	This function is called to signify the beginning of a batch of updates.
ChooseMultipleRecords	This function is called during assembly when the end user clicks the Select button on a Spreadsheet dialog. The implementation of this entry point should display (or cause to be displayed) a modal dialog box where the user can browse, search, filter, or otherwise review information made available by the answer source application. When the user chooses one or more records containing the data, the implementation should close the modal dialog box and return the number of records selected.
ChooseRecord	This function is called during assembly when the end user clicks the Select button on a Regular or Repeated Series dialog. The implementation of this entry point should display (or cause to be displayed) a modal dialog box where the user can browse, search, filter, or otherwise review information made available by the answer source application. When the user chooses a single record containing the data, the implementation should close the modal dialog box and return a 32-bit integer identifier that HotDocs will use later (in calls to GetField or GetFieldW).
CloseRecord	This function is called by HotDocs to indicate that access to the specified record is no longer needed.
CommitUpdates	This function is called by HotDocs to commit (save) any changes that have been made to fields in the specified record. For example, if a user selects a record and then changes the answers that came from that record, this function is called to update fields in the original record with changed answers.
EndUpdateBatch	This function is called to signify the ending of a batch of updates. At this point, HotDocs writes answers back to the database as necessary.
GetChosenRecords	This function is called if ChooseMultipleRecords returns a value greater than zero. It fills the recordIDs array with the record identifiers of the selected records in the order in which they are to appear within HotDocs. The records associated with these identifiers are assumed to be in an open state ready for read-only access.
GetField	This function is called shortly after execution returns from the ChooseRecord entry point if the Unicode version of this function (GetFieldW) is not defined. It is called a number of times to retrieve the data from the individual fields of the selected record in the answer source application.
GetFieldW	This function is called shortly after execution returns from the ChooseRecord entry point. It is called a number of times to retrieve the data from the individual fields of the selected record in the answer source application.
GetFieldAccess	This function is called by HotDocs to determine what type of access is allowed for a field in the answer source, and only if the Unicode version of this function (GetFieldAccessW) is not defined. Access may be read-only, or read/write, meaning answers can be written back to the original record if they are changed during the interview.
GetFieldAccessW	This function is called by HotDocs to determine what type of access is allowed for a field in the answer source. Access may be read-only, or read/write, meaning answers can be written back to the original record if they are changed during the interview.
GetFieldName	This function is used by HotDocs to enumerate the names and data types of all the available fields in the answer source application if the Unicode version of this function (GetFieldNameW) is not defined. GetFieldName is called repeatedly when a template developer attempts to map variables in a dialog to fields in the answer source, in order to retrieve the list of possible fields for mapping. HotDocs passes 0 in fieldNum the first time it calls GetFieldName (i.e., when it requests the first field name), and increments the number with each successive call. The implementation should set the field name and return the data type of the field.
GetFieldNameW	This function is used by HotDocs to enumerate the names and data types of all the available fields in the answer source application. GetFieldNameW is called repeatedly when a template developer attempts to map variables in a dialog to fields in the answer source, in order to retrieve the list of possible fields for mapping. HotDocs passes 0 in fieldNum the first time it calls GetFieldNameW (i.e., when it requests the first field name), and increments the number with each successive call. The implementation should set the field name and return the data type of the field.
IsAvailable	This function is called by HotDocs to determine whether the answer source DLL has initialized itself properly, is in communication with the answer source application, and is ready to be used. It is called each time HotDocs loads the answer source DLL.
OpenRecord	This function is called by HotDocs to open the specified record in preparation for accessing it. The answer source should prepare the record for the type of access requested by the mode.
SetField	This function is called by HotDocs (if the Unicode version of this function, SetFieldW, is not defined) to set a new value for a particular field of a specified record in the answer source.
SetFieldW	This function is called by HotDocs to set a new value for a particular field of a specified record in the answer source.
SupportsBackfill	This function is called by HotDocs to determine if the answer source supports back-filling of modified field values. If HD_FAILURE (0) is returned then HotDocs will not call GetFieldAccess or GetFieldAccessW for each field and will not allow any values modified in HotDocs to be written back to the answer source (back-filled).