Microsoft Dynamics CRM Address Validator

(1)

Microsoft Dynamics CRM

Address Validator

Address Validator Microsoft Dynamics CRM 2011

(2)

1. Introduction

The addressvalidator Addon offers functionality to validate and enrich address data. The following is supported.

a) Multilingual interface

b) Data entry international addresses

c) Validation of existing international addresses

For Dutch addresses, additional functionality is available for autocompletion of an address when the postalcode and housenumber are entered.

(4)

2. Functionality

Multi lingual interface

All functionality supports the multi language functionality of CRM. The functionality at this moment is available in 2 languages:

a) Dutch b) English

According to the user language settings in CRM, the functionality is displayed in Dutch (when the user has language Dutch specified in CRM), or in English (for all other user languages specified).

New address entry

The entry of a new address is done with only a few mouseclicks.

Fig. 1: Click “Validate”

After selecting a country it is possible to search for postalcode and housenumber (with extension), or when these are unknown, for address and city. Below 3 examples are shown.

(5)

Figuur 3: Enter address data and click “Search”; select the correct address.

Fig. 4: Enter address data and click “Search”; for non-Dutch addresses icons are shown with detailed explanations about corrections.

(6)

Validation and enrichment of existing address

Validation and enrichment of an existing address is done in a few moments.

Fig. 6: Open the account and click “Validate”. Select the correct address and click “Take over”

Autocompletion (Dutch addresses only)

For Dutch addresses, autocompletion is supported when entering only the postalcode and housenumber.

(7)

3. Installation

The AddressValidator Addon exists of a zip-file with this manual, and 2 zip-files:

 wsnlWebservicesCommon_x_x_ managed.zip

 wsnlWebservicesAddressValidator_x_x_managed.zip _x_x means the version-/revisionnumber of the solutions.

Installation is done by importing both zip-files as solutions into CRM. Below is a detailed description of how to do that.

Test environment

It is explicitly recommended to always first test the solutions in a test environment.

Import the solutions

Two solutions need to be imported into CRM, in the following order:

1. wsnlWebservicesCommon_x_x_ managed.zip (common components)

2. wsnlWebservicesAddressValidator_x_x_managed.zip (addressvalidator specific components)

NOTE: the order of import is important. The 2nd zip-file will fail to import without the 1st already done.

1. Go to Settings – Solutions 2. Click button Import 3. Browse the zip-file:

1st import: wsnlWebservicesCommon_x_x_managed.zip

2nd import: wsnlWebservicessAddressValidator_x_x_managed.zip 4. Click Next to see solution details

5. Click Next to specify import options

NOTE: the 2nd import has no option for SDK plugin step!

6. Check the option “Activate any processes and…SDK message…” 7. Click Next to start the import.

8. When the import is finished, importresults are shown. Click Close Repeat these steps for the 2nd zip-file.

Version upgrade: re-import the solution

Whenever an upgrade of a solution (1 of both) is imported following the steps described above, the CRM system detects that the solution already is installed. This is shown in step 4, solution details.

(8)

- The recommended option “Maintain customizations” is correctly checked.

- The option “Activate any processes and…SDK message…” also needs to be checked (only when this option is shown, for wsnlWebservicesCommon)

(9)

4. Configuration

Webservices.nl configuration

Fig. 8: nieuw record: Webservices.nl instellingen

Webservices.nl Account Data

Username, password and balance

To be able to use the addon, a valid username and password need to be entered. See section Proxy settings on CRM server

The CRM server needs access to the following url: https://ws1.webservices.nl The addon uses the proxy-settings as configured in Internet Explorer on that server. Ensure that the proxyserver

 EITHER allows access for the CRM Sandbox User (tot this specific url)

 OR completely allows access to this specific url (optionally as IP-address) for everyone Application Procedure for username and password for information on how to obtain these.

(10)

Fig. 9: Settings Webservices.nl, Account Data

The entered username and password can be validated by clicking the button “Test connection” on the right in the ribbon.

On the right of the username and password, the current balance is shown in euro’s.

NOTE: every CRM user uses these username and password to validate addresses. However, CRM users can

be authorized separately for usage of the addon, see section Authorizati.

Address Validation settings

(11)

ISO mapping countries

Fig. 11: Address Validation settings; ISO mapping countries

In this field all countries to support must be entered, together with their corresponding ISO3-code (see section Countries iso3 codes).

Picklists and Lookups are supported by entering either the picklist-value (number) or lookup displayvalue (text) as the CRM-values.

Whenever a textfield is used for country (like the standard field address_country) then the crm-value must be specified as the complete countryname as typed by the user.

(12)

Examples per country field type:

for a picklist e.g. 1=NLD the picklist-value is specified per country 2=BEL

3=GER 4=USA

for a lookup e.g. Nederland=NLD the lookup-displayvalue is specified per country België=BEL

Duitsland=GER

Verenigde Staten=USA

For a text field e.g. Netherlands=NLD the full countryname is specified per country, Holland=NLD including different spelling forms

Belgium=BEL Germany=GER United States=USA America=USA

TIP: for a text field, different spelling forms can be specified in the list, all corresponding with the same

ISO3-code.

NOTE: every country which has to be supported must be specified! Only countries specified here are shown

in the Address Validation window. Address Blocks

Up to 3 address blocks can be configured for the Account-, Contact- en Lead entity. One address block can be configured for the “More addresses” entity.

Each address block is configured by specifying a Name for the address block. Next the fields which contain the address data have to be specified.

(13)

Mandatory fields to be configured per address block are:

 Name address block a logical name to recognize the address

 Address the field with the address’s street (optionally including the housenr)

 City the field with the address’s city

 Country the field with the address’s country

Authorization

CRM users are authorized to use address validation by assigning predefined roles to them.

Fig. 13: Predefined Security Roles: the above is for Dutch addresses only, the role below includes all international addresses

NOTE: even a system administrator needs these roles tob e able to use the address validator!

Address fields used by address validation

After installation, the “Validate address” button is pre-installed on the following entities.

 Lead

 Account

 Contact

 CustomerAddress (“more addresses” in Account and Contact). The first 3 mentioned can contain up to 3 address blocks, the latter only one.

The specific fields used for each of those addresses can be configured in the settings area (see above). Those are defaulted as follows.

Address component CRM field schemaname

Address line1 <address1/2_>line1

Housenr -

Address line 2 <address1/2_>line2 Postalcode <address1/2_>postalcode City <address1/2_>city

Province / State <address1/2_>stateorprovince Country <address1/2_>country Validation status wsnl_<address1/2>_status Table 1: default addressfields used by address validator Validation status field

Every address block can be provided with a “Validation status” field.

This field must be of type “Picklist”, and attached to the Global Picklist “Address Validation Status” (wsnl_addressstatus).

(14)

Proxy settings on CRM server

The CRM server needs access to the following url: https://ws1.webservices.nl The addon uses the proxy-settings as configured in Internet Explorer on that server. Ensure that the proxyserver

 EITHER allows access for the CRM Sandbox User (tot this specific url)

 OR completely allows access to this specific url (optionally as IP-address) for everyone

Application Procedure for username and password

Contact Webservices.nl (www.webservices.nl) to obtain a username and password.

Countries iso3 codes

(15)

5. Troubleshooting

‘Test Connection’ fails

Problem

In the Webservices.nl Settings form with username / password / balance, when clicking the button ‘Test Connection’ one of the following message is shown.

Possible causes

1. During import of the solution, the option “Activate any processes and…SDK message…” was not checked.  the 1st message above is shown, without any detailed explanation!

2. The CRM server’s internet connection is broken 3. Proxy settings for the CRM server are invalid Solution

For checking cause nr 1 (“Activate any processes and…SDK message…” was not checked during import) do the following.

 Go to Settings – Customizations

 Click Customize; the default solution is opened with all customizations

 Navigate (left) to “SDK-message…”

 Search the list for an entry with Name=”WSNL.MSCRM.Plugin…” and SDK-message=”RetrieveMultiple”

 If found:

(16)

For checking cause nr 2 and nr 3 (CRM server internet connection/proxy settings), see section Proxy settings on CRM server.

Message ‘Webservices.nl configuration ERROR: …’

Problem

When opening a form, the following message is shown.

Possible causes

1. One or more of the mentioned Configured fields do not appear on the form Solution

Go to the Address Validator Settings and double-check the configured fields in all enabled Address Blocks.

 An Address Block is enabled when a Name is specified for it.

 The configured fields should all be available on the form.

Message ‘…missing permissions…’

Problem

When clicking the ‘Validate Address’ button in a form’s ribbon, the following message is shown.

Possible causes

1. User does not have the required Security Role(s) 2. No Address block(s) are configured on the entities form Solution

Go to user management and doublecheck the User’s Roles (see section Authorization). Go to the Address Validator Settings and doublecheck the enabled Address Blocks.

(17)

Possible causes

1. The current address values do not represent a valid address. 2. There is a connection error to the Webservices.nl server. Solution

Retry with different address values.

If no success, go to Address Validator Account settings and test the connection (see section Username, password and balance and section ‘Test Connection’ fails).

Microsoft Dynamics CRM Address Validator