View source for Dynamics CRM:Configure Address Validation

{{DynamicsIntroNav}}

{{CustomTOC}}

==Configure Address Validation for CRM Entities==
Address Validation for Dynamics 365 can be configured to validate addresses on any entity in Dynamics
365/CRM that contains address fields.

To demonstrate how to setup and perform an address validation we'll use a configuration for the Account entity:

===Creating Sample Configuration Records for Account Entity===
;Optional Step
:Address Validation for Dynamics 365 can help you create sample configuration records to get you started.

#Navigate to a Address Verification API record. (Like the one created [[Dynamics CRM:License#Validate Service|here.]])
#Click on the "'''Create Sample Configuration'''" button.

::[[File:Dynamics_Config_CreateSampleRecord.png|frame|none|'''Create Sample Record''']]

:This will create two sample address verification records. To review them go to the '''''Address Validation → Address Fields Configuration''''' sitemap area.

::[[File:Dynamics_Config_EditSampleRecord.png|frame|none|'''Edit Sample Record''']]


===Define Address Fields on Target Entities===
#In the navigation, go to '''''Address Validation → Address Fields Configuration'''''.
#Create a new record.
#Enter the following information:
::*;Entity Name: Schema name of the source Entity (e.g. account).

::*;Configuration Name: Unique name of the configuration record (e.g. account1-sample).

::*;API Configuration Record: This is a lookup to select the API configuration record created in the previous section.

:::[[File:Dynamics_Config_APIRecord.png|frame|none|'''API Configuration Record''']]

::*;Address Verification Button: This is an ''optional step'' that allows you to customize the label of the verification button. To do so, enter the language code (Microsoft Locale ID Value) followed by a colon and then the label of the button, e.g. <code>[Language Code]:[Button label]</code>. For a list of supported languages and their codes, visit https://msdn.microsoft.com/en-us/library/ms912047(v=winembedded.10).aspx.

:::*This option also allows you to have multiple languages configured for the label of the button by adding a semi-colon followed by another code <code>[Language Code]:[Button Label];[Other Code]:[Other Language Label]</code>. For example: <code>1033:Verify Address;1036: Vérificationd'Adresse</code>.
:::*The button will display the language based on the system language you set.

::*;Default Country: If you are using the Melissa Data Express Entry Autocomplete, you can select the default country that will appear on the forms (e.g.: United States, Canada, etc.)

::*;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 configured web service.

::*;Use Same Fields for Input and Output: Select whether you want the validated address to overwrite the original address or not. When a different destination is selected, you will be given the option to identify the different source fields.

::::Address Validation for Dynamics 365 allows you to input the country of the address to be validated as a lookup or text field.

::::*The Source (Input) fields are the fields where the original address (to be validated) are located.
::::*The Destination (Output) fields are the fields where the verified address will be written to.

::::[[File:Dynamics_Config_SameFields.png|frame|none|'''Use Same Fields for Output''']]

<ol style="list-style-type:upper-alpha">
:::<li>Address Field - Full Address: Indicate a text field schema name (custom created or out of the box field) where the application can save the full formatted address after it is verified. A value is not required for this field, and it cannot be one of the Out of the Box address composite fields.</li>
:::<li>Address Validation Details Field: Indicate a text field schema name (custom created or out of the box field) where the application can save the details of the address correction returned by the verification API. A value is not required for this field.</li>
</ol>

::::<span style="color:red;">'''IMPORTANT – When a different destination is enabled for the validated address:'''
::::*If the country source is a lookup field, then the destination can be either a lookup or a text field.
::::*If the country source is a text field, then the destination must be a text field.</span>


===Country Lookup Field Configuration===
Address Validation for Dynamics 365 gives you the option to select a lookup field as the input for the address to be validated. The system will need an entity to store the country names and codes (for a table of names and codes, see https://msdn.microsoft.com/en-us/library/ee783932(v=cs.10).aspx), if you already have one then skip to step 4. If you need to create a new entity, follow these steps:

<ol>
<li>Navigate to the Entity configuration screen by going to '''''Settings → Customizations → Customize the System''''' or by using an Unmanaged Solution of your choice.</li>
<li>Create a new Entity (in this example we’ll name it "Country").</li>

:[[File:Dynamics_Config_CountryLookup-NewEntity.png|frame|none|'''Country Lookup - New Entity''']]

<li>Add fields in this entity for the country name and code, in this example we’ll call them <code>new_country_name</code> and <code>new_countrycode</code>. Set these to be of type simple and single line of text and '''Save and Close'''.</li>

:[[File:Dynamics_Config_CountryLookup-AddFields.png|frame|none|'''Country Lookup - Add Fields''']]

<li>Navigate to the source/input Entity (e.g. Account), select '''Fields''' and click on '''New''' to add a new field.</li>
<li>Change the '''Data Type''' to <code>Lookup</code> and the '''Target Record Type''' to the <code>Country</code> Entity previously created. Click on '''Save and Close''' and '''Publish All Customizations'''.</li>

:[[File:Dynamics_Config_CountryLookup-InputEntity.png|frame|none|'''Country Lookup - Source/Input Entity''']]

<li>Navigate to your source/input Entity (e.g. Account) and click on Forms and select the Main form.</li>
<li>In this form, add the country lookup field created in step #5. Click on '''Save and Close''' and then on '''Publish All Customizations'''.</li>

:[[File:Dynamics_Config_CountryLookup-MainForm.png|frame|none|'''Country Lookup - Main Form''']]

<li>In the navigation, go to '''''Address Validation → Address Fields Configuration''''' and open the configuration record previously created.</li>
<li>Change the '''Address Field – Country''' to <code>Lookup</code> and enter the name of the field that contains the lookup on the entity associated with this configuration (e.g. Account) created in step #5.</li>
<li>Enter the name of the field in the Country entity that contains the country code in '''Country code field''' (created in step #3 above).</li>

:[[File:Dynamics_Config_CountryLookup-Lookup.png|frame|none|'''Country Lookup - Lookup''']]
</ol>


===Configure Front End Address Verification===
This section provides the configuration steps to allow your Dynamics CRM/365 users to perform address verification from the web application on CRM forms.

<ol>
<li>Navigate to the Entity form configuration screen by going to '''''Settings → Customizations → Customize the System''''' or by using an Unmanaged Solution of your choice. In our example, we will navigate to the Account’s main form configuration screen.

:[[File:Dynamics_Config_FrontEndAddress-Customize.png|frame|none|'''Front End Address Verification - Customize the System''']]

<li>On the entity configured for Address verification (e.g. Account), add the Web Resource named <code>sharpxrm_/sharpxrm/widgets/AddressValidation.html</code> on the form you want to enable form address verification.</li>

:[[File:Dynamics_Config_FrontEndAddress-AddWebResource.png|frame|none|'''Front End Address Verification - Add Web Resource''']]

<li>In the '''Web Resource Properties Custom Parameter''' field, indicate the name of the '''Address Field Configuration''' record created for this entity type and fields (from our prior example, the name was <code>account-address1-to-address2</code>. <u>Make sure the '''Restrict cross-frame scripting, where supported''' checkbox is unchecked.</u>
<li>In the Formatting Tab for the Web Resource, select the following options (recommended)</li>

<ol style="list-style-type:upper-roman">
<li>Number of Rows: 2.</li>
<li>Scrolling: Never.</li>
<li>Display Border: Unchecked.</li>
</ol>

:[[File:Dynamics_Config_FrontEndAddress-Formatting.png|frame|none|'''Front End Address Verification - Web Resource Formatting''']]

<li>Save and publish the form.</li>
<li>Assign the Security Role named <code>SharpXRM - Address Validation User</code> to users that should be able to perform address verification.</li>

:[[File:Dynamics_Config_FrontEndAddress-AssignSecurity.png|frame|none|'''Front End Address Verification - Assign Security Role''']]

The <code>SharpXRM – Address Validation User</code> security role simply gives users the ability to access Configurations and License information. These privileges can be added to another custom security role to make the deployment of Address Validation easier.

Only do this if you know what you are doing.
</ol>


===Melissa Data Express Entry AutoComplete Configuration===
If you are using the Express Entry API, you have the option of configuring the AutoComplete address validation.

<ol>
<li>Follow the steps to configure the Front End detailed in the Front End Configuration” section but select the Web Resource named <code>sharpxrm_/sharpxrm/widgets/MDAutocomplete.html</code> on the form you want to enable form address verification.</li>

:[[File:Dynamics_Config_ExpressEntry-WebResource.png|frame|none|'''Express Entry Configuration - Web Resource''']]

<li>In the '''Web Resource Properties Custom Parameter''' field, indicate the name of the <code>Address Field Configuration</code> record created for this entity type and fields (from our prior example, the name was <code>account1-sample</code>. Make sure the '''Restrict cross-frame scripting, where supported''' checkbox is unchecked.</li>
<li>In the Formatting Tab for the Web Resource, select the following options (recommended)</li>
<ol style="list-style-type:lower-alpha">
<li>'''Number of Rows''': 10.</li>
</ol>
</ol>


==Performing the Verification from a Form==
===Address Validation===
Open a record configured for address validation, enter an address in the input fields, '''Save''' then click on the '''Validate Address''' button.

:[[File:Dynamics_Example_FormVerification-ValidateAddress.png|frame|none|'''Form Verification - Validate Address''']]


===Melissa Data Express Entry Validation===
If the Express Entry API is enabled, start typing and press enter when you have enough information to search and select the desired address from the list. To save the address, click on the '''Validate Address''' button.

:[[File:Dynamics_Example_ExpressEntry-ValidateAddress.png|frame|none|'''Express Entry - Validate Address''']]


==Configure Workflow Address Verification==
With Address Verification for Dynamics CRM/365, you can also perform address verification from the Dynamics 365/CRM backend. The add-on comes with a Custom Workflow activity that allows to run the address verification. Here are the steps to use it.

<ol>
<li>Navigate to '''''Settings → Processes''''' and create a new Process of Category Workflow. For the Entity, select the entity where your address fields to validate are located (in our case, we will continue with the Account entity).</li>

:[[File:Dynamics_Configure_WorkflowAddressVerification-CreateProcess.png|frame|none|'''Workflow Address Verification - Create Process''']]

<li>Once you have created the Workflow, click on '''Add Step''' and in the Sharp XRM menu, you will see a custom action named '''Verify Address'''</li>

:[[File:Dynamics_Configure_WorkflowAddressVerification-AddStep.png|frame|none|'''Workflow Address Verification - Add Step''']]

<li>Type a description for the Step (e.g. “Address Validation using SharpXRM Custom Activity”). Click on '''Set Properties''' and in the Value field enter the name of the address field configuration record (previously created) as a required input parameter for the custom action.</li>

:[[File:Dynamics_Configure_WorkflowAddressVerification-SetProperties.png|frame|none|'''Workflow Address Verification - Set Properties''']]

<li>The custom activity does not write the verified address to the destination fields. 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. The example below shows how the verified address fields are written a note.</li>

:[[File:Dynamics_Configure_WorkflowAddressVerification-Example.png|frame|none|'''Workflow Address Verification - Example''']]


[[Category:Clean Suite for CRM:Dynamics]]