Create an Answer Mapping

Creating an answer mapping has the following prerequisites:

The user creating the mapping must have Template Administrator rights for Workspace
HotDocs Developer application
Relational database software (e.g. MS SQL Server, Oracle, Access).

Before following the instructions below you should create your answer mapping database. Example steps for setting up a database using MS SQL Server can be seen here.

Part 1: Answer Mapping Integration

There are two ways to integrate Answer Mapping with a HotDocs interview: Answer Source and Event-driven integration.

Answer Source

Displays a link on a template dialog. On clicking the link, the user sees a pop-up window from which they select answers. This is similar to the Answer Source in HotDocs desktop interviews.

To add an Answer Source Integration

Open HotDocs Developer and select the template in the HotDocs Library that requires an answer mapping. Edit the component file.
Edit the dialog on which the Answer Mapping will appear. Create a new Dialog Element.
In the Dialog Element Editor, select the Web Link style.
In the URL field, enter the following URL (with the *placeholders* filled in, see bullet list below) to create the answer source link : ../AnswerSource?mappingname=*Mapping Name*&datasource=*Data Source Name*&command=*Command Name*&multiselect=*true or false*.

In this URL:

- *Mapping Name* — a unique name for the new Answer Mapping
- *Data Source Name* — the name of the database you want to use
- *Command Name* — a unique Command name to tell Workspace what to run when the user selects the web link
- *true or false* — choose true to enable multiple selection.

Navigate to the Options pane and check the Display In Server Interviews option.
Save the changes to the Dialog Element and close the component file.
Upload this template to Workspace.

Please continue to Part 2: Create an Answer Mapping XML File.

Event-driven

When using an Event-driven integration, Workspace configures specific queries to run when certain events occur during the interview. These events can occur when the interview starts, on navigating to a dialog, on navigating away from a dialog, or when the interview ends.

To add an Event-driven Integration

Open HotDocs Developer and select the template in the HotDocs Library that requires an answer mapping. Edit the component file.
Create a new text variable with the name Workspace_Mapping.
In the custom interview component script, add the instruction SET Workspace_Mapping TO "dialogname=* &mappingname=* &datasource=* &command=* &EventMask=*", where:
- Dialog name — the name of the dialog to which the event applies.
- Mapping name — the name of the mapping file uploaded to Workspace.
- DataSource — the name of the DataSource within the mapping file.
- Command — the name of the Answer Source command with the Data Source.
- Event mask — a 4-bit mask that determines when Workspace should run the event. To turn on all events, use the bit mask 1111. To turn all events off, use the bit mask 0000.
- - 1st bit (1xxx) — event runs on interview start (ignores dialog name attribute)
  - 2nd bit (x1xx) — event runs on navigate to dialog
  - 3rd bit (xx1x) — event runs on navigate away from dialog
  - 4th bit (xxx1) — event runs on interview end (ignores dialog name attribute)

The template developer can also assign multiple commands per dialog / interview by setting the control variable using repeat indices, i.e.

SET Workspace_Mapping[0] TO "dialogname=* &mappingname=* &datasource=* &command=* &EventMask=*"

SET Workspace_Mapping[1] TO "dialogname=* &mappingname=* &datasource=* &command=* &EventMask=*"

SET Workspace_Mapping[2] TO "dialogname=* &mappingname=* &datasource=* &command=* &EventMask=*"

Part 2: Create an Answer Mapping XML File

Now, you must create a new Answer Mapping XML file using the Answer Mapping XML. This file specifies:

The relationship between the database fields and the interview answer fields
The connection string to the database
Any queries made to the database and associated filters

You can use this table to replace the red placeholders in the example XML below (using an SQL database):

Placeholder	Replace with	Example
NAME	The name of your database	employee_db
USER	The user name you use to access your database software on the server	sa
PASSWORD	The password you use to access your database software on the server	w0rkspac3
MACHINE	The name of your server machine followed by a backslash and your database program	MACHINENAME\SQLEXPRESS
COMMAND	The command name you used in your template	EmployeeSelect
TABLE	The name of your table in your database	Employee Details
COLUMN	Start with the name of the first column in your table and continue until all columns have been listed	Employee Number
VARIABLE	The name of the variable in your template that you want to map this column to	employee_number_n
TYPE	The type of variable you are mapping to	2
PROMPT	The column heading your want to display in the interview	Employee Number

<?xml version="1.0" encoding="utf-8" ?>

<ConnectionString>provider=SQLNCLI10;user id=USER;password=PASSWORD;data source=MACHINE;initial catalog=NAME</ConnectionString>

<Query Type="Table">TABLE</Query>

</Mapping>

</Command>

</DataSource>

</MappingData>

Once you have completed the XML file, you must save it by calling the Mapping Name you used in part 1.

Part 3: Add a Mapping in Workspace

Login to Workspace as a template administrator. Navigate to the Mappings section.
Click Create Mapping.
At the Mapping Details page you can enter the following information:
- Name — If you are using an Answer Source or Event-driven integration, you must use the Mapping Name entered in Part 1: Answer Mapping Integration. If not, enter a unique Mapping Name.
- Filename — Click Browse to select the Answer Mapping XML file (created in Part 2) detailing the structure of the Answer Mapping.
- Groups — select the Groups which may use this answer mapping.
Click Save. The new answer mapping will appear in the answer mappings list on the Mappings page.