Advanced configuration

1. Select Solutions from the left hand menu.
2. Click the link Experian Data Validation for Microsoft Dynamics 365 in the solutions list to open the solution.
3. Expand the Tables node in the navigation bar on the left.
4. Select TextMap and click the Edit button that appears on the right side of the page.
5. On the data grid page that appears click the drop down labeled "18+ more" to show the "Show existing column" panel.
6. On this panel, unselect the preselected columns and select the required edit columns as shown below. They will appear in the order that you select them, so select them in the same order as shown below.
7. From this page you can add new records and edit or delete existing records. Once you have existing records you can also edit them by selecting the row in the data grid and clicking the "Edit row using form" menu item.
8. Repeat steps 4 to 7 for the OptionSetMap and LookupMap tables to configure the edit columns for these tables as shown below:

1. Go to Settings > Customizations > Customize the System.
2. Expand the Entities in the left panel and locate the entity "TextMap" 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. Repeat steps 2 to 4 for the solution entities OptionSetMap and LookupMap.
6. Go to Settings and under Extensions click on "TextMaps", OptionSetMaps or LookupMaps (if they is not shown, refresh the page).
7. 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.

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.

1. 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: Addressprovince
          Api Values: NSW
   Transformed Value: New South Wales
        Entity Field: 
     Validation Type: Address
   

2. 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 Addressprovince. This name is obtained by manually copying the mapping label, with or without spaces, from the Map fields page of the Configuration app. As a shortcut you can place the mouse cursor over the mapping label and click the left mouse button while holding down the Ctrl key:

The name to use for the API property is copied to the clipboard and a message is displayed to indicate that the name has been copied:

It's possible to create a TextMap record for any of the API properties, you just need to obtain the name from the Configuration page (as illustrated above) and paste it in the "Api Properties" record field.

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

1. 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.
2. Transformed Value
   This is the transformed value that will get saved to the database record. In the example above it is New South Wales.
3. Validation Type
   Text maps can be used for Address, Email and Phone validations. The default is Address and the example above has been for an address validation type. The value should be set to Email or Phone when the transform applies to a data property from one of these validation types.

The 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.

Restricting text mappings using other values returned by the Address Validation API

The above approach fails when the same API value for a particular API property needs to be transformed to different values based on 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:

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:

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:

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:

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:

'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 <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.

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:

1. 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: Addressprovince,Addresscountry
         Api Values: ACT,AUSTRALIA
     OptionSet Name: new_countrystates
         Item Value: 722140008
    Validation Type: Address
   

   Note: the values given are for illustrative purposes only, actual values should be obtained from the OptionSet being used.
2. Click "Save and Close".
3. 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 'Addressprovince' and 'Addresscountry'. These are obtained by manually copying the mapping labels, with or without spaces, from the Map fields page of the Configuration app. As a shortcut you can place the mouse cursor over the mapping label and click the left mouse button while holding down the Ctrl key:

The name to use for the API property is copied to the clipboard and a message is displayed to indicate that the name has been copied:

It's possible to create a OptionSetMap record for any of the API properties, you just need to obtain the name from the Configuration page (as illustrated above) and paste it in the "Api Properties" record field.

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.

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:

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:

1. 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: Addresscountry
         Api Values: UNITED STATES OF AMERICA
        Lookup Name: new_countrylookup
          Lookup Id: a29f1eae-2a81-ec11-8d21-002248256434
    Validation Type: Address
   

   Note: the values given are for illustrative purposes only, actual values should be obtained from the Lookup entity being used.
2. Click Save and Close.
3. 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 'Addresscountry'. This name is obtained by manually copying the mapping label, with or without spaces, from the Map fields page of the Configuration app. As a shortcut you can place the mouse cursor over the mapping label and click the left mouse button while holding down the Ctrl key:

The name to use for the API property is copied to the clipboard and a message is displayed to indicate that the name has been copied:

It's possible to create a LookupMap record for any of the API properties, you just need to obtain the name from the Configuration page (as illustrated above) and paste it in the "Api Properties" record field.

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