Address mapping

Address mapping maps a collection of data values returned by the address API (and additional enrichment datasets if configured) to a collection of Microsoft Dynamics entity fields. An address mapping is always associated with a single Microsoft Dynamics entity and must be named. A Microsoft Dynamics entity may have as many address mappings configured as there are addresses held by the entity. The solution comes pre-configured with two simple address mappings (named Address1 and Address2) for the address1_* and address2_* fields of the standard entities Account, Competitor, Contact and Lead. These pre-configured mappings may be used out-of-the-box to perform simple address searches on the standard entities (skip to the section To bind the fields to your forms to start using the built-in address mappings).

The pre-configured address mappings can be modified to suit your needs. You can also create new address mappings for any Microsoft Dynamics entity.

Configure an Address Mapping

To populate entity fields with values returned by the address API configure an Address mapping by following the steps below:

1. Go to the Configuration page.
2. Click the Map fields tab.
3. From the entities list on the left select the entity for which you want to configure an address mapping.
4. Either select an existing mapping from the list in the MAPPINGS column or click + ADD to create a new mapping (enter a name in the textbox labelled Name in this case).
5. The names of the standard address values returned by the API are shown under the tab heading Standard address fields and under each name is a drop-down listbox that contains fields of the associated entity. Click on each drop-down listbox and select the field that you want populated by that API value.
   The dropdown list is separated into three types for convenience, depending on what the field was created under:
   * Text, the text returned by the address API is stored in the field.
   * Choice, the item selected for the choice field will be the one where the text of the choice item matches the text returned by the API using a case insensitive match. (Choice refers to Option set in the Classic version)
   * Lookup, the lookup record selected for the field will be the one where the text of the primary name column of the Lookup entity matches the text returned by the API using a case insensitive match.
   If you map to a Choice or Lookup field without additional configuration, an empty value will be saved to the mapped field if a match is not found amongst the Choice or Lookup values.
6. Optionally, if you want to save the validation result and timestamp, select field values from the drop-down listboxes for Address validation message and Address validation timestamp API properties after you have created these fields for the entity. See Validation tracking fields if you have not yet created these fields.
7. The names of the components, metadata and enrichment properties that have been selected under the Configure additional data tab are shown under the tab heading Address data fields. Click this tab heading to show the drop-down listboxes where you can map the data values returned by these additional data properties to entity fields.
8. Click on the drop-down listbox for each data property you would like to map and select the entity field that you want populated by the value returned by the API. You will need to ensure that the fields to accept the data values have been created on the entity beforehand.
9. For any standard address or other data property that you want to ignore, choose the value Not mapped from the drop-down list.

To bind the fields to your forms:

1. Go to Customize the System.
2. Expand Entities in the left panel.
3. Expand your chosen entity you want to add the fields to (e.g. Account) and click Forms under the chosen entity.
4. Click your chosen form you want to add a field to (e.g. Account Quick Create). This will open a new window.
5. Select Form Properties from the ribbon to open the Form Properties dialog box. In the Events tab click the top "Add" button and add the web resource "edq_formmanager" to the form.
6. With the OnLoad event selected, click the bottom "Add" button to open the "Handler Properties" dialog box. For library select the previously added "edq_formmanager" and in the textbox labelled Function type in "edq_onLoadHandler" (exclude the quotes). Be sure that both checkboxes labelled "Enabled" and "Pass execution context as first parameter" are selected.
7. Click "OK" to close the Form Properties dialog box.
8. Select the field you need to map.
9. Click Change Properties, and go to the Controls tab.
10. Click Add Control….
11. Scroll and select EDQAddress, and click Add.
12. Select where you want the control to be enabled - Web, Phone and/or Tablet.
13. Click the pencil icon by Mapping name.
14. Select Bind to a static value and in the text box enter the Mapping name (e.g. Address1) from the Map fields tab in the Configuration page.
15. Click OK.
16. Repeat steps 8-15 for each field you want mapped using the custom mapping you created in the Configuration page.