The HotDocs Variable Mapping API lets you create associations between data fields in your application and HotDocs variables in your templates. For example, if your application contains a data store with information about customers, you can map the fields in your data store to variables in a HotDocs template. Then when a user assembles a document from the template, your application can pre-populate the AnswerCollection with appropriate data from the data store, such as a customer name or address.
Ideally, if the names of your application's data fields matched the names of your HotDocs variables, then variable mapping would not be required. Likewise, if the variable names and your data store's field names were guaranteed never to change, you might choose to hard-code mappings in your application. However, the reality is that while data fields and variables represent the same information, they often do not use the same name. The HotDocs Variable Mapping API addresses both of these problems--you can match data with different names, and you can easily change mappings whenever required by changes to the template or your data store.
The associations (mappings) you set up between HotDocs variables and your application's data fields are saved in a separate HotDocs map (.HMF) file for each template. When a template with an associated map file is assembled, HotDocs loads the information from the map file into the Assembly. However, once HotDocs loads the map file, it doesn't actually do anything to retrieve values from your application's data store; it is up to your application to process the mappings found in the map file and send values from your data store to the AnswerCollection associated with the current assembly.
HotDocs allows mapping to flow both ways, which means that in addition to sending answers from your application to HotDocs, HotDocs can also send changed answers back to your application.
A HotDocs Variable Map contains three collections of information:
| Collection | Description |
| HDVariables | A list of HotDocs variables that can be mapped to fields in your data store. This collection is usually populated by copying the list of variables (and their types) from a HotDocs component file. |
| SourceNames | A list of fields in your data store. |
| Mapping | A list of mappings between variables and source names (fields) in your data store. Each item in this collection maps one variable name to one source name. |
Mapping files created using HotDocs 2009 (or later) are saved in an XML file format, which cannot be read by earlier versions of HotDocs. HotDocs 2009-11 can still read existing binary mapping files created by earlier versions, however.
The following topics explain how you can use the HotDocs Variable Mapping API to create and use mapping files: