Configure Field Mapping for Background Address Validation

Modified on Tue, 13 Jun, 2023 at 1:59 PM

What this article cover : In order to run address verification in background process (workflows), you must identify for each entity/table and the fields/columns where your address information is stored. This article explains how to create the the field mapping record where admins will identify the table and columns for their addresses.  



TABLE OF CONTENTS


Identification of Table and Field Mapping Parameters

  • In the navigation bar, go to Address Validation -> Settings -> Field Mappings.
  • Create a new record and enter the following information:
  • Configuration Name: Unique name of the configuration record (e.g. account-billingaddress)
  • Table Name: Schema name of the source Table (e.g. account).
  • API Configuration : This is a lookup to select the Address Validation API Key that will be used to run the background process against the table for which the field mapping is being created.
  • Overwrite existing address with verified address: Yes or No. 
    • When set to Yes, you will get to pick on set of addresses that will be used as input and output, this means the process will read the values from these fields, process them with the address validation API and overwrite their values with the result. 
    • When set to No, you'll have to pick a set of fields for input address and a different set of fields for the output (i.e. we will read from input, and write the validated address to the output). This is often used to preserve the data entered by users when Dataverse Auditing is disabled.


Other Non Required Parameter 
  • Output Language: By default, verification APIs will return the verified address in English US. This option allows you to specify the language to use with the selected configurated web service. 
    • Selecting "Custom Language" will display a separate field to allow you to pick your output language.
    • Note that output language can only be changed when utilizing the Bing Maps API (possible values) and Google Maps API (values here). There is a limited number of available languages - Sharp XRM does not have any control over the available languages.


Legacy Parameter :

  • Address Verification Button: Ignore.


Selection of address fields

Once the General information is completed, you must fill out the information in the Address fields. 

  • Only fields of type text are allowed for all address fields except for Latitude and Longitude, which require a Floating Point Number.



Configure Dataverse Workflow Process to validate an address 

Once you have created a field mapping record, you can create a workflow that will leverage the mapping to verify your addresses. 


  • Start by navigating to your Power Apps Maker portal
  • Go the Solutions area and pick the solution where you want your workflow to be included
  • Click on New -> Automation -> Process -> Workflow to create  your workflow.

  • On the next window, select the table where the address to validate is located, and type in a name for your workflow and click on the Create button at the bottom of the window.

  • After you have created the Workflow, click on "Add Step" and in the "Address Validation" menu, you will see a custom step named "Verify Address"

  • Type a description for the Step (e.g. “Validate Account Address 1”). 
  • Click on Set Properties
    • The parameters are both optional in the user interface, but one of them is required to function. If both are provided, the lookup will be used first. If none is provided, the workflow will return an error. 
    • You can provided the Configuration Name : this is the name of the Field Mapping Configuration record (see previous section of this article document in the General tab of the Field Mapping record OR
    • Select the lookup of the Field Mapping record (Field Mapping Configuration property) 
    • Note that only one of the parameters is needed. 

  • The custom workflow does the following operations when it runs
    • It reads the input parameters from the Field Mapping record. 
    • It processes the address validation using the configured address verification API.
    • It returns the verified address component as output parameters giving administrators the ability to configure the application behavior in a way that meet their needs. 
    • It does not write the verified address to the destination fields. 
    • The example below shows how the verified address fields are written the Account's description field.

  • The following table shows the list of columns returned by the custom workflow step


As a reference, we are using the following address to show examples in the table below : 

175 W Jackson Blvd, Ste 500

Chicago, Cook County, IL 60604-3024

United States of America


Property NameExpected Value
Street AddressThe street address :

175 W Jackson Blvd

Unit NumberThe unit number when found :

Ste 500


Note that only Melissa and Canada Post have the ability to return unit numbers. 
CityThe city :
Chicago 
CountyThe county when found :
Cook
State/ProvinceThe State or Province
IL  
Zip/Postal CodeZip or Postal Code :
60604-3024


Note that only Melissa consistently returns the Zip+4 element. Google and Azure return them when found. US Only. 

Full AddressReturns the full address in a single line of text :
175 W Jackson Blvd, Ste 500, Chicago, IL 60604-3024
LatitudeThe Latitude
41.87776
LongitudeThe Longitude
-87.63321
ConfidenceThe confidence is only return by Google and Bing. It is helpful in Workflows to determine if we want to overwrite the input address with the verified address.

Bing Maps Confidence Values (product documentation available here) :
  • LOW
  • MEDIUM
  • HIGH
  • UNKNOWN

Google Maps Confidence Values (this returns the precision level of the geocoding search result as documented here): 
  • ROOFTOP indicates that the returned result reflects a precise geocode - high.
  • RANGE_INTERPOLATED indicates that the returned result reflects an approximation (usually on a road) - medium. 
  • GEOMETRIC_CENTER the returned result is the geometric center of a result - low.
  • APPROXIMATE indicates that the returned result is approximate - low.
Entity TypeThe Entity Type is the type of object that was returned by the address validation (ex. a street address vs a intersection). It is only return by Google and Bing. It is helpful in Workflows to determine if we want to overwrite the input address with the verified address.

Bing Maps Entity Type Values (product documentation available here) :
  • ADDRESS (indicates that an address was found)
  • NEIGHBOHOOD 
Google Maps Entity Type Values (this returns the types of location - documented here): 
  • ROOFTOP indicates that the returned result reflects a precise geocode - high.
  • RANGE_INTERPOLATED indicates that the returned result reflects an approximation (usually on a road) - medium. 
  • GEOMETRIC_CENTER the returned result is the geometric center of a result - low.
  • APPROXIMATE indicates that the returned result is approximate - low.

Verification DetailsThe Verification Details returns different information based on the Address Verification API being used.

Bing Maps API : Returns Bing Maps request's HTTP Status Code.
Google Maps API : Returns Google's request Status Code.
Melissa Global and Personator : Returns the list of Melissa Result Codes, comma separated.
Canada Post Autocomplete : Not supported
Azure Maps : Not supported
 
Melissa Result CodesMelissa Only.
Returns a comma separated list of the Melissa Result Codes
Melissa Result Code Descriptions Melissa Only.
Returns a comma separated list of the Melissa Result Code Short Descriptions.



Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article