Microsoft Dynamics CRM Address Validator

Microsoft Dynamics CRM Address Validator Address Validator Microsoft Dynamics CRM 2011 Version 2.0

Contents 1. Introduction... 3 2. Functionality... 4 Multi lingual interface... 4 New address entry... 4 Validation and enrichment of existing address... 6 Autocompletion (Dutch addresses only)... 6 3. Installation... 7 Test environment... 7 Import the solutions... 7 Version upgrade: re-import the solution... 7 4. Configuration... 9 Webservices.nl configuration... 9 Webservices.nl Account Data... 9 Username, password and balance... 9 Address Validation settings... 10 ISO mapping countries... 10 Address Blocks... 11 Authorization... 12 Address fields used by address validation... 12 Validation status field... 12 Address validation on different (e.g. custom) entities... 12 Proxy settings on CRM server... 13 Application Procedure for username and password... 13 Countries iso3 codes... 13 5. Troubleshooting... 14 Test Connection fails... 14 Message Webservices.nl configuration ERROR:... 15 Message missing permissions... 15 Message There is no address found... 15 Microsoft Dynamics CRM Address Validator Page 2 of 17

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. Microsoft Dynamics CRM Address Validator Page 3 of 17

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. Fig. 2: Enter address data and click Search Microsoft Dynamics CRM Address Validator Page 4 of 17

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. Fig. 5: Click Take over. Address data is transported to CRM Microsoft Dynamics CRM Address Validator Page 5 of 17

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. Fig. 7: Enter postalcode and housenumber and click Validate. The Address will be automatically completed Microsoft Dynamics CRM Address Validator Page 6 of 17

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. In the next step, the following options are shown: Microsoft Dynamics CRM Address Validator Page 7 of 17

- 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) Microsoft Dynamics CRM Address Validator Page 8 of 17

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. Microsoft Dynamics CRM Address Validator Page 9 of 17

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 Fig. 10: Address Validation settings Microsoft Dynamics CRM Address Validator Page 10 of 17

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. Microsoft Dynamics CRM Address Validator Page 11 of 17

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. Fig. 12: Address Block 1 for Account entity; specifying the Name enables the address validator. The address data fields are defaulted, however different (e.g. custom) fields can be used for each address component. Microsoft Dynamics CRM Address Validator Page 12 of 17

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). Whenever such a field is configured to be used by the address validator, it will be maintained automatically. Address validation on different (e.g. custom) entities Address Validation optionally can be configured on different entities (forms) then only Account, Contact, Lead and CustomerAddress. Contact Webservices.nl (www.webservices.nl) for detailed information on how to do that. Microsoft Dynamics CRM Address Validator Page 13 of 17

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 See http://nl.wikipedia.org/wiki/iso_3166-1 Microsoft Dynamics CRM Address Validator Page 14 of 17

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 1 st 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 SDKmessage= RetrieveMultiple If found: o check column Status, this should be Activated o If not activated, select the entry and click button Activate Otherwise: re-import the wscommon solution (see section Installation) and don t forget to check the option Activate any processes and SDK message Microsoft Dynamics CRM Address Validator Page 15 of 17

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. An Address Block is enabled when a Name is specified for it. Message There is no address found Problem When clicking the Validate Address button in a form s ribbon, the following message is shown. Microsoft Dynamics CRM Address Validator Page 16 of 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 Page 17 of 17