Classic view
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.
Enable components
Loading delay
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.
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:
Choice and OptionSet
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.
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:
Field Value Api Attribute(s): province,country Api Values(s): ACT,AUSTRALIA OptionSet Name: new_countrystates Item Value: 722140008Note: the values given are for illustrative purposes only, actual values should be obtained from the OptionSet being used.
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.
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.
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:
Field Value Api Attribute(s): country Api Values(s): UNITED STATES OF AMERICA Lookup Name: new_countrylookup Lookup Id: a29f1eae-2a81-ec11-8d21-002248256434Note: the values given are for illustrative purposes only, actual values should be obtained from the Lookup entity being used.
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".