Data Quality user documentation

Classic view

Use the 'classic' view for all configuration of the PCF components.

An address mapping maps a collection of data values returned by the address API (and additional enrichment datasets if configured) to a collection of MS Dynamics entity fields. An address mapping is always associated with a single MS Dynamics entity and must be named. An MS 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 MS 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:

Go to the Configuration page.
Click the Map fields tab.
From the entities list on the left select the entity for which you want to configure an address mapping.
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).
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.
- Three types of entity 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.
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.
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 Additional 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.
Click on the drop-down listbox under the additional data value 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 a field to accept the data value has been created on the entity beforehand.
For any standard address or additional data values that you want to ignore, choose the value Not mapped from the drop-down list.

To bind the fields to your forms:

Go to the Customize the system.
Expand Entities in the left panel.
Expand your chosen entity you want to add the fields to (e.g. Account) and click Forms under the chosen entity.
Click your chosen form you want to add a field to (e.g. Account Quick Create). This will open a new window.
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.
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.
Click "OK" to close the Form Properties dialog box.
Select the field you need to map.
Click Change Properties, and go to the Controls tab.
Click Add Control….
Scroll and select EDQAddress, and click Add.
Select where you want the control tobe enabled - Web, Phone and/or Tablet.
Click the pencil icon by Mapping name.
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.
Click OK.
Repeat steps 8-15 for each field you want mapped using the custom mapping you created in the
configuration page.

Advanced Configuration

Advanced mapping configuration requires adding records to the solution entities TextMap, OptionSetMap or LookupMap. The steps to add records to these entities are given below:

Select Solution in navigation bar on the left.
Click the link Experian Data Validation for Microsoft Dynamics 365 in the solutions list to open the solution.
Expand the Tables node in the navigation bar on the left.
Select Lookup > Data, OptionSet > Data or TextMap > Data to open the data page for the entity you selected.
From this page you can add new records and edit or delete existing records.

Go to Settings > Customizations > Customize the system.
Expand the Entities in the left panel and locate the entity "TextMap" and select it.
Under the section "Areas that display this entity" select the checkbox labelled "Settings".
Save and Publish the changes and then close the window.
Repeat steps 2 to 4 for the solution entities OptionSetMap and LookupMap.
Go to Settings and under Extensions click on "TextMaps", OptionSetMaps or LookupMaps (if they is not shown, refresh the page).
You will now be on a page titled "Active Text Maps", "Active OptionSet Maps" or "Active Lookup Maps". From this page you can add new records and edit or delete existing records.

More flexible configuration of Text, OptionSet and Lookup field mappings than that provided by the default matching rules is available. The configuration options available for each and instructions on applying them are detailed in the sections below:

Text maps allow you to substitute values returned by the address API with your own values. For example, rather than use the codes for the province values that the API returns you may prefer to use province names instead. It is possible to do this using text maps. The process will be illustrated using values returned by the API province property as examples:

For the Australian state of New South Wales the address API returns the code NSW for the province property value. In order to translate the code NSW returned by the API into the name New South Wales a record needs to be created for the TextMap solution entity.

Following the steps provided above, create a new record for the TextMap entity and enter the following values for the record fields:

            Field  Value
   Api Properties: Address Province
       Api Values: NSW
Transformed Value: New South Wales
     Entity Field:

Save the newly created record.

The above process of adding a transform record to the TextMap entity is the basic way to customize property values returned by the address API and can be applied to any property that returns text values.

In the above example the name for the API property is given as Address Province. This is the same name used for the mapping label in the configuration pages Map Fields tab:

It’s possible to create a TextMap record for any of the API properties, you just need to ensure the label name in the configuration page (illustrated above) is entered as the “Api Properties” value.

The other two compulsory values that must be entered in the new TextMap record are:

Api Values
This is the property value returned by the API that needs to be transformed. In the example above it is NSW. The wildcard characters '?' (matches any single character) and '*' (matches zero or more characters) are allowed when specifying these values. These allow many API values to match to a single transformed value.
Transformed Value
This is the transformed value that will get saved to the database record. In the example above it is New South Wales.

The last field Entity Field is optional and will in most cases be left empty. It is used to specify an entity field in order to restrict the transform to a particular entity field. When left empty the transform will apply to all mappings where the API property specified in the TextMap record is used.

Entity/Field and Table/Column

The terms 'Entity' and 'Table' are synonyms as are 'Column' and 'Field'. The terms 'Table' and 'Column' are the newer names that are used in Microsoft's Power Apps platform to refer to the original 'Entity' and 'Field' names. In this section we use the original terms.

Restricting text mappings using other values returned by the address api

The above approach fails when the same API value for a particular API property needs to be transformed to different values based other API property values. For example, the province code WA is present for both countries Australia and United State of America. In this case you would like the transformed value for WA to be Western Australia when the country is Australia and Washington when the country is United States of America. This can be done by creating two TextMap records, one for each country as shown below:

Api Properties	Api Values	Transformed Value
Address Province, Address Country	WA, AUSTRALIA	Western Australia
Address Province, Address Country	WA, UNITED STATES OF AMERICA	Washington

Here we have specified both Address Province and Address Country in a comma separated list as the API properties to be considered for this transform and provided the corresponding API values to match as a comma separated list in the Api Values field. The order of the API property names specified is important as the first property is considered primary and will be the one whose value is transformed. All additional properties provided in the list will be used only for matching purposes to ensure that the correct TextMap record is matched for the values returned by the api.

Using lists to transform many values in one TextMap record

It is possible to make a list of changes in one TextMap record with the use of the LIST() construct. It can be used as shown in the example below:

Api Properties	Api Values	Transformed Value
Address Province	LIST(AL,AK,AZ,AR,CA)	LIST(Alabama,Alaska,Arizona,Arkansas,California)

This example shows a few codes being transformed in one TextMap record. You would normally include all values to be transformed in a single list, although it is possible to partition long lists across several records if required.

Using the lists construct is the equivalent of specifying all the values and transformed values in individual records. Wildcard characters '?' and '*' are not supported in list values and neither are transform functions such as :lowercase, :uppercase.

Lists can also be used with more than one API property specified in the TextMap record. For example, you can specify the provinces for a single country in one TextMap record as illustrated below:

Api Properties	Api Values	Transformed Value
Address Province, Address Country	LIST(AL,AK,AZ,AR,CA), UNITED STATES OF AMERICA	LIST(Alabama,Alaska,Arizona,Arkansas, California)

This can then be repeated for each country configured for address validation.

Other transforms available when configuring a TextMap record

Rather than specifying a specific value as the transformed text you may want to transform the value in other ways. The following transforms are available and the syntax to use when specifying the transformed value is given below:

Transform to apply	Syntax to use in Transform Value field
Lower-case the API value	:lowercase
Upper-case the API value	:uppercase
Title case the API value	:titlecase
Set the first letter to upper-case	:initialcap
Use a regular expression	:replace "<pattern>" "<substitution>" "<flags>"

For the regular expression transform the <pattern>, <substitution> and <flags> are the same as those used in JavaScript regular expressions. They must be provided surrounded with double-quote ("), single-quote (') or back-tick (`) characters. The <flags> parameter is optional and may be left out but the other two are mandatory.

The wildcard character '*' is usually specified as the value of the Api Values field in these types of transforms as you want to apply the transform to all values of the API property. For example, the specification below ensures that all country values are returned in lower-case:

Api Properties	Api Values	Transformed Value
Address Country	*	:lowercase

'Entity Field' field in the TextMap record

The 'Entity Field' field in a TextMap record is used when you want to restrict the use of the transform specified in that record to a particular entity field, a particular entity or a particular field. The syntax is as below:

Where the transform is applied	'Entity Field' field syntax	Example
Any entity and any field	Empty field or : (this is the default)
Fields of the specified entity	<entity>	account
Specified field in any entity	*:<field>	*:address1_city
The specific entity field	<entity>:<field>	contact:address2_city

Where <entity> is the logical name of the entity (e.g. account, lead, contact) and not the display name, and <field> is the logical name of the field and not the display name.

Troubleshooting

If you have configured some TextMap records but the results of address searches appear not to have applied the transforms you have configured, then first try doing a hard refresh of the web browser page (Ctrl-F5 for the Chrome web browser). If you still do not see the transforms being applied, then open the the browser developer console and check for reported errors that may help you troubleshoot any issues.

Choice and OptionSet

The terms 'Choice' and 'OptionSet' refer to the same data type. The term 'Choice' is the newer name that is used in Microsoft's Power Apps platform to refer to the original 'OptionSet' data type. In the section below we use the original term 'OptionSet' to refer to this data type.

If you want to save a value for a particular address API property 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 property.

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 property 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 properties Address Province and Address Country as examples, but the same instructions apply to other address API properties also.

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

The address API returns two or three letter codes as values for the API province property. 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 property 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 property: 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:

Following the steps provided above, create a new record for the OptionSetMap entity and enter the following values for the record fields:
```
           Field  Value
  Api Properties: Address Province,Address Country
      Api Values: 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.
Click "Save and Close".
Repeat steps 1 & 2 for all the other province codes that need to be added.

In the above example the names for the API properties are given as 'Address Province' and 'Address Country'. These are the same names used for the mapping labels in the configuration pages 'Map Fields' tab:

It’s possible to create a OptionSetMap record for any of the API properties, you just need to ensure the label names in the configuration page (illustrated above) are entered as the "Api Properties" value.

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 property is involved in a mapping (as is the case above), the properties involved are given as a comma separated list, in this case "Address Province,Address Country". The order of the API property names specified is important as the first property is considered primary and will be the one whose value is transformed. All additional properties provided in the list will be used only for matching purposes to ensure that the correct OptSetMap record is matched for the values returned by the api.

When more than one API property is involved in a mapping the values to match for those properties are also given in a comma separated list in the same order as the property 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 Properties	Api Values	OptionSet Name	Item Value
Address Province,Address Country	ACT,AUSTRALIA	new_countrystates	722140001
Address Province,Address Country	NSW,AUSTRALIA	new_countrystates	722140002
Address Province,Address Country	…,AUSTRALIA	new_countrystates	…
Address Province,Address Country	AB,CANADA	new_countrystates	722140009
Address Province,Address Country	BC,CANADA	new_countrystates	722140010
Address Province,Address Country	…,CANADA	new_countrystates	…
Address Province,Address Country	CA,UNITED STATES OF AMERICA	new_countrystates	722140020
Address Province,Address Country	NY,UNITED STATES OF AMERICA	new_countrystates	722140021
Address Province,Address 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 Properties	Api Values	OptionSet Name	Item Value
Address Country	UNITED STATES OF AMERICA	new_countryoptions	733240002

TextMap alternative

Note that OptionSet text value matching occurs on the transformed values of any TextMap transforms, so simple substitutions like the above can also be performed with a TextMap transform. It may be easier to use TextMap transforms for simple cases, however, there may be cases where that will not work. For example, a province may have the same name in two different countries, so the same name will have more than one entry in an OptionSet for provinces (with a different numeric item value for each entry).

Also, the functionality described above that enables province OptionSet values to be filtered for the current country is not available when using TextMap transforms.

Troubleshooting

If you have configured some OptionSetMap records but the results of address searches appear not to have applied the overrides you have configured, then first try doing a hard refresh of the web browser page (Ctrl-F5 for the Chrome web browser). If you still do not see the overrides being applied, then open the the browser developer console and check for reported errors that may help you troubleshoot any issues.

If you want to save a value for a particular address API property 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 property.

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 by the address API for that property, 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 Address Country API property, but the same instructions apply to other address API properties 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:

Following the steps provided above, create a new record for the LookupMap entity and enter the following values for the record fields:
```
           Field  Value
  Api Properties: Address Country
      Api Values: 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.
Click Save and Close.
Repeat steps 1 & 2 if there are other values that need to override the default behavior.

In the above example the name for the API property is given as 'Address Country'. This is the same name used for the mapping label in the configuration pages 'Map Fields' tab:

It’s possible to create a LookupMap record for any of the API properties, you just need to ensure the label name in the configuration page (illustrated above) is entered as the "Api Properties" value.

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

Api Properties	Api Values	Lookup Name	Lookup Id
Address Country	UNITED STATES OF AMERICA	new_countrylookup	a29f1eae-2a81-ec11-8d21-002248256434

TextMap alternative

Note that LookupMap text value matching occurs on the transformed values of any TextMap transforms, so simple substitutions like the above can also be performed with a TextMap transform. It may be easier to use TextMap transforms for simple cases, however, there may be cases where that will not work. For example, if you want to use a lookup entity for the country but the country name is not held in the primary name column for the lookup entity, then TextMap transforms will not work.

Troubleshooting

If you have configured some LookupMap records but the results of address searches appear not to have applied the overrides you have configured, then first try doing a hard refresh of the web browser page (Ctrl-F5 for the Chrome web browser). If you still do not see the overrides being applied, then open the the browser developer console and check for reported errors that may help you troubleshoot any issues.

The naming of Api Properties when creating records for theTextMap, OptionSetMap and LookupMap entities has been explained in previous sections: you just need to ensure the label name in the configuration page under the Map fields tab is entered as the “Api Properties” value.

The above method of obtaining names for the Api Properties field of mapping entities extends to Component, Metadata and Enrichment properties also. You can use the label name as a value for an API Property:

Both standard address and additional data property names consist of two parts with an intervening space character. If you prefer you can remove the intervening space character. For example, the API property names 'Address Country' and 'AddressCountry' are equivalent as are 'main: country_iso_2' and 'main:country_iso_2'.

Next: Phone mapping

Microsoft D365 CE PCF

Create mappings and bind

Next topic:
Monitor usage
Previous topic:
Create fields

Related Resources

How to get to Customize the system