Data Quality user documentation
home/Integrations/Microsoft D365 CE PCF/Create mappings and bind/Address mapping

Address mapping

While the solution is preconfigured to use specific fields for all kinds of validation, it is possible for these settings to be changed. All the preconfigured fields are managed through the solution’s Mapping tab. When you first get the MS Dynamics 365 solution an example mapping exists. If you do not create your own custom mapping, then the example preconfigured mapping is used.

Latitude, Longitude and Match level fields are shown if Geocoding (global datasets) is checked in the Select components tab. These components are used when a custom dataset is not specified for the request being sent.

For example, if a GBR address is searched and a custom regional dataset has been specified, fields used to store the data will be those which names start with Enrichment_. If a USA address is searched and there is no custom dataset specified for USA, then Latitude, Longitude and Match level mapped fields will be used. So, the typical settings for such a situation would be to map both Latitude and Enrichment_latitude to same field, for example address1_latitude.

To map the fields to your forms:

  1. Go to the Configuration page.
  2. Click the Map fields tab and select the entity you want your address validation mapping to appear in.
  3. Next select your chosen mapping:
    • For all standard entities and fields there will already be preinstalled mapping, click 'Address 1' or 'Address 2'.
    • Click ADD to create a new mapping (keep the name to less than 40 characters).
  4. Map the fields where you want each bit of information returning from the API to appear. If you do not want to use a field, select "Not mapped".
    • Three types of form fields can be selected: Text, Choice or Lookup. If you select:
    • 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.
    • 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.

Without additional configuration, for both (the Choice and Lookup) cases an empty value will be saved to the mapped field if a match is not found amongst the Choice or Lookup values.

  1. In the Address Validation column, map the corresponding validation message field and validation timestamp field you created earlier to where you want the information returning from the API to appear.
  2. Under the Enrichment components column, map the latitude, longitude and Match level fields where you want each bit of information returning from the API to appear (If you do not want to use a field, select "Not mapped").
  3. There are additional address validation components in the Additional Components column to the right, which are all optional.

To bind the fields to your forms:

  1. Go to the 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 tobe 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 Mappings 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.

Advanced Configuration

More flexible configuration of Choice and Lookup field mappings than that provided by the default matching rules is available and detailed in the sections below:

If you want to save a value for a particular address API attribute to a form field whose underlying type is an OptionSet, then by default the set of text values that make up the OptionSet type must match the values that the address API returns (ignoring case) for that attribute.

If you have an OptionSet field that you would like updated with values that are returned by the address API but the values held in the OptionSet field do not match in part or any off the values returned for that attribute by the address API, then it is possible to provide overrides where the default matching behavior is insufficient. Those overrides are configured for fields of type OptionSet by adding records to the solution entity named "OptionSetMap".

Configuration of these records is illustrated below by using the address API attributes "province" and "country" as examples, but the same instructions apply to other address API attributes also.

Example One: Mapping address API province codes to state names.

The address API returns two or three letter codes as values for the province attribute. These can be saved to an entity field of type OptionSet if all the two and three letter codes returned by the address API for this attribute are present as text values of the OptionSet items. However, you may use state names instead of codes as your text values for the entity field of OptionSet type to which you want to save the province values returned by the address API. As an example, for the country Australia the address API returns the following codes for the province attribute: ACT,NSW,NT,QLD,SA,TAS,VIC and WA. You may use the state names, Australian Central Territory, New South Wales, etc in your OptionSet field instead. In order to use state name text values for an OptionSet type field a mapping record needs to be created for each province code returned by the address API that maps the returned code to the numeric value of the OptionSet item that it matches. The steps to add such records are given below:

  1. Go to Settings > Customizations > Customize the system.
  2. Expand the Entities in the left panel and locate the entity "OptionSetMap" and select it.
  3. Under the section "Areas that display this entity" select the checkbox labelled "Settings".
  4. Save and Publish the changes and then close the window.
  5. Go to Settings and under Extensions click on "OptionSetMaps" (if it is not shown, refresh the page).
  6. You will now be on a page titled "Active OptionSet Maps". Click "New" to add a new mapping record.
  7. Add the following values for the four form fields:
               Field  Value
Api Attribute(s): province,country
   Api Values(s): ACT,AUSTRALIA
  OptionSet Name: new_countrystates
      Item Value: 722140008
    Note: the values given are for illustrative purposes only, actual values should be obtained from the OptionSet being used.
  8. Click "Save and Close".
  9. Repeat steps 6 to 8 for all the other province codes that need to be added.

Note that although we are saving a province value, the configuration also uses the country value as part of the mapping. This is because the same province code may potentially appear in more than one country, so the country value returned by the address API is also matched to disambiguate such potential clashes. This allows the same OptionSet to hold the state names of multiple countries.

When more than one API attribute is involved in a mapping (as is the case above), the attributes involved are given as a comma separated list, in this case "province,country", with the first attribute being the one whose value is being mapped and any subsequent attributes being ones whose values are also matched as part of the mapping.

When more than one API attribute is involved in a mapping the values to match for those attributes are also given in a comma separated list in the same order as the attribute names, in this case "ACT,AUSTRALIA".

Below is given an example list of records configured for the OptionSetMap entity that shows the values of an OptionSet named new_countrystates that holds the state names of three countries, Australia, Canada and United States of America. Note that this is an incomplete list of records with only two records being shown for each country.

API Attribute(s) API Value(s) OptionSet Name Item Value
province,country ACT,AUSTRALIA new_countrystates 722140001
province,country NSW,AUSTRALIA new_countrystates 722140002
province,country …,AUSTRALIA new_countrystates …
province,country AB,CANADA new_countrystates 722140009
province,country BC,CANADA new_countrystates 722140010
province,country …,CANADA new_countrystates …
province,country CA,UNITED STATES OF AMERICA new_countrystates 722140020
province,country NY,UNITED STATES OF AMERICA new_countrystates 722140021
province,country …,UNITED STATES OF AMERICA new_countrystates …

Another benefit that accrues in the above example is if all values for the OptionSet "new_countrystates" have a mapping record in OptionSetMap, then the drop-down list that is displayed in the UI is automatically filtered to show just those states/provinces that belong to the country given by the country field for the address.

Example Two: Overriding an address API country name.

It may be the case that most text values of an OptionSet match the values returned by the address API but there may be one or two values that do not. In this case just those values can be remapped in a mapping record for the OptionSetMap entity. As an example, the address API returns the country value "UNITED STATES OF AMERICA" but the OptionSet being used for the entity field that is mapped may hold the value "United States". All other country names may match with those returned by the address API. In this case a single record can be added to the OptionSetMap entity as shown in the example below:

API Attribute(s) API Value(s) OptionSet Name Item Value
country UNITED STATES OF AMERICA new_countryoptions 733240002

If you want to save a value for a particular address API attribute to a form field whose underlying type is a Lookup, then by default the set of text values for the primary name column of the Lookup entity must match the values that the address API returns (ignoring case) for that attribute.

If you have a Lookup field that you would like updated with values that are returned by the address API but the values held in the Lookup field do not match in part or any off the values returned for that attribute by the address API, then it is possible to provide overrides where the default matching behavior is insufficient. Those overrides are configured for fields of type Lookup by adding records to the solution entity named "LookupMap".

Configuration of these records is illustrated in the example below by using the "country" address API attribute, but the same instructions apply to other address API attributes also.

Example: Mapping an address API country name to a Lookup entity record.

For this example, assume you have a Lookup entity that holds country names in its primary name column and the value held for America is "United States". The address API returns the value "UNITED STATES OF AMERICA" which does not match the text value of "United States" held in your Lookup entity's record and you would like the API value to match to the same record. All other country names match with those returned by the address API. Follow the steps below to configure an override record for the United States of America:

  1. Go to Settings > Customizations > Customize the system.
  2. Expand the Entities in the left panel and locate the entity "LookupMap" and select it.
  3. Under the section "Areas that display this entity" select the checkbox labelled "Settings".
  4. Save and Publish the changes and then close the window.
  5. Go to Settings and under Extensions click on "LookupMaps" (if it is not shown, refresh the page).
  6. You will now be on a page titled "Active Lookup Maps". Click "New" to add a new mapping.
  7. Add the following values for the four form fields:
               Field  Value
Api Attribute(s): country
   Api Values(s): UNITED STATES OF AMERICA
     Lookup Name: new_countrylookup
       Lookup Id: a29f1eae-2a81-ec11-8d21-002248256434
    Note: the values given are for illustrative purposes only, actual values should be obtained from the Lookup entity being used.
  8. Click "Save and Close".
  9. Repeat steps 6 to 8 if there are other values that need to override the default behavior.

The record will appear in the LookupMap entity as shown below:

API Attribute(s) API Value(s) Lookup Name Lookup Id
country UNITED STATES OF AMERICA new_countrylookup a29f1eae-2a81-ec11-8d21-002248256434

To determine the name of the API attribute to use in mapping records for the OptionSetMap or LookupMap entities search for the column in the solution’s Mapping entity corresponding to the attribute of interest. The name of the column will begin the prefix "edq_" and the attribute name to use in a mapping record will be the column name with this prefix removed. For example for the "country" and "province" attribute names used in the examples above the column names in the Mapping entity are "edq_country" and "edq_province".

For enrichment components the attribute name to use is a combination of the dataset name and the dataset attribute separated by two dashes "--". For example for the NZL dataset "nzl_cv_household", if the dataset attribute "mosaic_group" was being mapped in an OptionSetMap or LookupMap record, then the attribute name to use would be "nzl_cv_household--mosaic_group".

Microsoft D365 CE PCF

Create mappings and bind

Related Resources