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:
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:
Email and Phone validations
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.
Field Value Api Properties: Addressprovince Api Values: NSW Transformed Value: New South Wales Entity Field: Validation Type: Address
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 placing the mouse cursor over the mapping label in the Configuration page's Map fields tab and clicking 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:
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.
Entity/Field and Table/Column
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:
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.
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.
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 |
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
Choice and OptionSet
Email and Phone validations
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.
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:
Field Value Api Properties: Addressprovince,Addresscountry Api Values: ACT,AUSTRALIA OptionSet Name: new_countrystates Item Value: 722140008 Validation Type: AddressNote: the values given are for illustrative purposes only, actual values should be obtained from the OptionSet being used.
In the above example the names for the API properties are given as 'Addressprovince' and 'Addresscountry'. These are obtained by placing the mouse cursor over the mapping labels in the Configuration page's Map fields tab and clicking 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.
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.
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
Troubleshooting
Email and Phone validations
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.
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 Properties: Addresscountry Api Values: UNITED STATES OF AMERICA Lookup Name: new_countrylookup Lookup Id: a29f1eae-2a81-ec11-8d21-002248256434 Validation Type: AddressNote: the values given are for illustrative purposes only, actual values should be obtained from the Lookup entity being used.
In the above example the name for the API property is given as 'Addresscountry'. This name is obtained by placing the mouse cursor over the mapping label in the Configuration page's Map fields tab and clicking 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:
Api Properties | Api Values | Lookup Name | Lookup Id |
---|---|---|---|
Address Country | UNITED STATES OF AMERICA | new_countrylookup | a29f1eae-2a81-ec11-8d21-002248256434 |
TextMap alternative
Troubleshooting