Integrating Microsoft MapPoint Web Service into Microsoft CRM

  • Article

 

Microsoft Corporation

April 2004

Applies to:
    Microsoft® CRM version 1.2

Requires:
    Microsoft Business Solutions CRM version 1.2
    Microsoft Visual Studio® .NET
    Microsoft MapPoint® Web Service SDK version 3.5

Summary: You can integrate the Microsoft MapPoint Web Service with the Microsoft CRM application to provide maps and latitude or longitude information for your customers. (10 printed pages)

Download the sample code for this article: CustomerAddressMap.exe.

Contents

Introduction
    Registering for MapPoint
Using the Sample Code
    Download and Install the Sample Code
    Customize Microsoft CRM
    Test the Maps
    Change the Center of Your Map
More Information

Introduction

Knowing where your customers are is important, and sometimes latitude and longitude coordinates can be just as important as street addresses. In this article, we incorporate new features into the account and contact forms and use Microsoft® MapPoint® .NET to help you find your customers more easily. The sample application adds user interface (UI) elements to those forms to look up and update the latitude and longitude coordinates of customer addresses, show a map of the United States with clickable pushpins for each of a given customer's addresses, and show detail maps of the area around a customer's address, as shown in the following two figures. Information about how to display a map of another country is available at the end of this article.

Click here to see larger image

Figure 1. The account form showing a map of all addresses (click picture to see larger image)

Figure 2

Figure 2. A detail map showing one address location

Registering for MapPoint

Before working with the sample code, you must get a free Microsoft MapPoint .NET trial account by performing the following steps:

  1. Open a Web Browser and go to the Microsoft MapPoint site. Click MapPoint Web Service in the left pane, and then click Evaluation Account. This opens the evaluation form.
  2. Fill out the form and click the Submit request button.
  3. Go to the MapPoint Web Service SDK download site and download the SDK. Alternatively, you can browse the SDK online.
  4. Install the SDK. The SDK consists of sample code and documentation for the MapPoint Web Service.
  5. Wait for your MapPoint Web Service user name and password to arrive through e-mail. This may take several days.

Using the Sample Code

Download the sample code CustomerAddressMap.exe.

Download and Install the Sample Code

After downloading the sample code, unzip CustomerAddressMap.exe to your c:\inetpub\wwwroot directory. A folder named CustomerAddressMap will be created.

Follow these steps to create a virtual directory that points to the CustomerAddressMap folder in Internet Information Services Manager:

  1. On the Start menu, click All Programs, and then Administrative Tools. Click Internet Information Services (IIS) Manager.
  2. Expand the node for your server, and then expand the Web Sites node.
  3. Right-click Microsoft CRM Version 1.2. Select New and then click Virtual Directory.

Step through the Virtual Directory Creation Wizard as follows:

  1. On the Welcome page of the wizard, click Next.
  2. On the Virtual Directory Alias page, type CustomerAddressMap and click Next.
  3. On the Web Site Content Directory page, browse to the CustomerAddressMap folder in the c:\inetpub\wwwroot location and click Next.
  4. On the Virtual Directory Access Permissions page, leave the default selections of Read and Run Scripts and click Next.
  5. Click Finish.

You must make several changes in the sample code before testing the code: add a Web reference to the MapPoint Web Service and fill in your Microsoft CRM server name, and your MapPoint user name and password. Perform the following steps to add a reference to the MapPoint Web Service:

  1. To open the project in Microsoft Visual Studio® .NET 2003, double-click the file CustomerAddressMap.csproj.

  2. In the Solution Explorer, right-click References and then click Add Web Reference.

  3. In the URL box, type this URL for the MapPoint Web Service: https://staging.mappoint.net/standard-30/mappoint.wsdl. You can also find this information in the MapPoint Web Service SDK. Click Go.

    Note   The URL used in this step is for a MapPoint staging server. For production, you should use the URL: https://service.mappoint.net/standard-30/mappoint.wsdl.

  4. Once the Web service is found, click Add Reference.

You must perform the following steps to fill in your Microsoft CRM server name, and your MapPoint user name and password:

  1. Open the file ISVAddress.cs. Change the name of the server in the CrmUrl member variable of the ISVAddress class to be that of your Microsoft CRM server. Save your changes.

  2. Open the file ISVMap.cs. Change the MapPointUsername and MapPointPassword member variables of the ISVMap class to be those of your MapPoint .NET trial account.

    Note   This sample contains a user name and password. This is a potential security issue. For more information, see Building Secure ASP.NET Applications.

  3. Rebuild your solution.

Customize Microsoft CRM

Before you can test the sample code, you must customize Microsoft CRM.

First you must add the latitude and longitude fields to the account, contact, and customer address forms by performing the following steps. These fields are a part of the Microsoft CRM database but are not used by the Microsoft CRM Web application.

  1. Open Microsoft CRM and go to Settings, System Customization.

  2. From the Record Type Management list, click Accounts, and then click Customize Form.

  3. Click Address to activate that portion of the form. On the Task Pane, click Add Fields, and add two new fields: address1_latitude and address1_longitude, as shown in the following figure.

    Click here to see larger image

    Figure 3. Adding the address1_latitude and address1_longitude fields to the account form (click picture to see larger image)

  4. Select the address1_latitude field on the account form and click Change Properties on the Task Pane. Type Latitude for the label.

  5. On the Formatting tab, select 5 from the Decimal Accuracy drop-down list.

  6. On the Values tab, specify a Minimum value of -180.00 and a Maximum value of 180.00. Click OK.

  7. Select the address1_longitude field on the account form and click Change Properties on the Task Pane. Type Longitude for the label.

  8. Repeat steps 5 through 6.

  9. Click the Save and Close button to save your changes to the form.

  10. Return to the Record Type Management list, and click Contacts. Follow the same instructions as listed above for Accounts.

  11. Return to the Record Type Management list, and click Address.

  12. Click Customer Address Information to activate that portion of the form. On the Task Pane, click Add Fields, and add two new fields: Latitude and Longitude.

  13. Select the Latitude field on the account form and click Change Properties on the Task Pane. Repeat steps 5 through 7.

  14. Click the Save and Close button to save your changes to the form.

You must now publish your form customizations using the following procedure:

  1. On the Start menu, point to All Programs, point to Microsoft CRM, and then click Deployment Manager.
  2. On the Action menu, click All Tasks and then click Publish Customization.
  3. Select the check boxes for the Account, Contact, and CustomerAddress objects and click Next.
  4. Click Add. Select your Microsoft CRM Web server, click Add, and then click Finish.
  5. When the Status dialog box is displayed, click OK.

Finally, you must add the Map button and the Update Lat/Long menu to the account and contact forms, as shown in the figure at the end of this section. This is done by editing the isv.config file. This configuration file is used to add custom pages and menu items to the application.

Make a backup copy of the original isv.config file before proceeding. You can find it in c:\inetpub\wwwroot\_Resources\. Copy the file from the sample code folder c:\inetpub\wwwroot\CustomerAddressMap to c:\inetpub\wwwroot\_Resources\.

When you make changes to the configuration file, you must restart IIS to make the changes available to users. To restart IIS, click Run from the Start menu, type iisreset, and click OK.

The following code shows a new navigation bar button named Map and a new menu item named Update Lat/Long that are added to the forms. For more information about how to customize this configuration file, see Customizing the Microsoft CRM Application in the Microsoft CRM SDK.

<configuration>
   <Root>
      <!-- The main Menu Bar found at the top of all root level areas -->
      <MenuBar>
         <!-- Custom Menu Bar items go between the Goto and Help menus -->
         <CustomMenus>
         </CustomMenus>
      </MenuBar>

      <!-- The left areas for each section in the application -->
      <Areas>
         <Home code="home"/>
         <Workplace code="workplace"/>
         <Sales code="sfa"/>
         <Service code="cs"/>
         <Reports code="reports"/>
      </Areas>

   </Root>

   <!-- Microsoft Customer Relationship Management Entities (Objects) -->
   <Entities>
      <account>
         <ToolBar ValidForCreate="0" ValidForUpdate="1">
            <Button Title="Update Lat/Long" 
                    ToolTip="Update Lat/Long values
                             using Microsoft MapPoint .NET"
                    Icon="/CustomerAddressMap/compass.gif"
                    Url="/CustomerAddressMap/UpdateLatLong.aspx"
                    PassParams="1" 
                    WinParams="status=0; menubar=0; toolbar=0;
                               height=200; width=400;" />
         </ToolBar>
         <NavBar ValidForCreate="0" ValidForUpdate="1">
            <NavBarItem Icon="/CustomerAddressMap/compass.gif" 
                        Title="Map"
                        Url="/CustomerAddressMap/mapAllAddresses.aspx" 
                        Id="accountMap" />
         </NavBar>
      </account>
      <contact>
         <ToolBar ValidForCreate="0" ValidForUpdate="1">
            <Button Title="Update Lat/Long"
                    ToolTip="Update Lat/Long values
                             using Microsoft MapPoint.NET"
                    Icon="/CustomerAddressMap/compass.gif"
                    Url="/CustomerAddressMap/UpdateLatLong.aspx"
                    PassParams="1"
                    WinParams="status=0; menubar=0; toolbar=0;
                               height=200; width=400;" />
         </ToolBar>
         <NavBar ValidForCreate="0" ValidForUpdate="1">
            <NavBarItem Icon="/CustomerAddressMap/compass.gif"
                        Title="Map"
                        Url="/CustomerAddressMap/mapAllAddresses.aspx"
                        Id="contactMap" />
         </NavBar>
      </contact>
      <lead/>
      <opportunity/>
      <incident/> <!-- Case -->
      <quote/>
      <salesorder/> <!-- Order -->
      <invoice/>
   </Entities>
</configuration>

Click here to see larger image

Figure 4. The account form showing the Map button and the Update Lat/Long menu (click picture to see larger image)

Test the Maps

Integration of the mapping service is complete. To use this sample application, create an account or contact, enter at least one address to an account or contact form and click Save. If you don't enter any addresses, clicking the Map button and Update Lat/Long menu will display an error. After you click the Update Lat/Long menu, a dialog box is shown briefly while the processing takes place. When it completes, click the Close button and the Latitude and Longitude boxes are filled in. To show the map for the address entered, click the Map button. The following two figures show the contact form with the computed latitude and longitude and the map page with two addresses, respectively.

Click here to see larger image

Figure 5. The contact form showing the computed latitude and longitude (click picture to see larger image)

Click here to see larger image

Figure 6. The contact map page showing two addresses (click picture to see larger image)

Change the Center of Your Map

This sample shows a map of the United States. The following code in the mapAllAddresses.aspx.cs file performs this task:

// Create a map of the contiguous United States of America.
ISVMap map = new ISVMap(38.88, -97.43);
map.SetHeight(400, 3500);
map.SetWidth(600, 3500);

You need to change this latitude and longitude setting to one appropriate to the area you are interested in. You may also need to change the height and width of the map.

In addition, you must change the MapPoint data source in the following code in the ISVMap.cs file to the area you specified previously:

mapSpec.DataSourceName = "MapPoint.NA";

For example, use this value to set the data source to Europe:

findAddressSpec.DataSourceName = "MapPoint.EU";

For information about alternative data sources, see the MapPoint Web Service SDK.

More Information

For more information about customizing the Microsoft CRM application, see the Microsoft CRM Software Development Kit (SDK).

For more information about MapPoint and the MapPoint Web Service SDK, see the MapPoint Web Service Home page on MSDN®.