Chapter 4: Administering MapPoint Location Server

  • Article

The MapPoint Location Server management console is a Microsoft Management Console (MMC) snap-in that you can use to configure and administer MapPoint Location Server. You can use the console to modify MapPoint Location Server global settings; add, modify, and delete user accounts and Find Nearby categories; and to change the properties of location and notification providers. You cannot add or remove providers using the console.

The user interface of the MapPoint Location Server management console consists of a tree view on the left and a details pane on the right, as shown in Figure 4. The tree view contains the following nodes:

  • Global Settings

  • Users

  • Providers

  • Find Nearby Categories

When you expand a node in the tree view, details about the contents of the node appear in the details pane. Figure 4 shows the management console.

Figure 4.  MapPoint Location Server management console

Note  The MapPoint Location Server management console does not support all MMC features. Specifically, the Export List and All Tasks options are not available.

After opening the MapPoint Location Server management console, when you right-click Microsoft MapPoint Location Server and select Database, the Database dialog box appears and displays the name of the instance of SQL Server and the name of the MapPoint Location Server database. You can see the same information by using the Action menu.

*

On This Page

Modifying Global Settings Modifying Global Settings
Managing Users Managing Users
Managing Providers Managing Providers
Managing Find Nearby Categories Managing Find Nearby Categories
Using the Demonstration Location Provider Using the Demonstration Location Provider
Using the MapPoint Location Server Tools Using the MapPoint Location Server Tools

Modifying Global Settings

Global settings consist of your Microsoft MapPoint Web Service account ID and password, the URLs for the MapPoint Web Service Find, Render, Route, and Common services, and the maximum number of contacts a user can have.

Important  Changes that you make to global settings do not take effect until MapPoint Location Server Web Service is restarted.

To modify a global setting

  1. Expand the Global Settings node.

  2. In the right pane, click the global setting that you want to change, and then click Properties.

  3. In the Properties dialog box, type the new value, and then click OK twice to close all dialog boxes.

Managing Users

Administrative tasks related to users consist of adding and deleting users, associating providers with users, adding contacts, and modifying user properties such as phone number or notification address.

Adding a User

Users that you provision for MapPoint Location Server must already exist in a Microsoft® Active Directory® domain. This can be the domain of the computer running MapPoint Location Server Web Service or a domain that has a trust relationship with that domain.

To add a user

  1. In the tree view, expand the Users node.

  2. On the toolbar above the right pane, click New, and then do one of the following:

    • If you know the user's domain and alias, in Name, type the user's domain name and alias in the format domain\username, and then click OK.

    • If you want to search for a user, click Advanced, and under Common Queries, choose a search method and type a search string, and then click Find Now. Under Search Results, highlight the correct user, and then click OK twice to close each dialog box.

    If the user is found, the <Username> Properties dialog box appears. In this dialog box, you can add providers and contacts for users.

  3. In the Default Language drop-down list, select the culture to use for Find Nearby category names and notifications (the default is English), and then click OK.

Adding Providers for Users

You can assign location and notification providers for a user when you create a new account or at any time afterward. However, the user cannot use location or notification services until the respective providers have been assigned. For more information about providers, see "Adding Providers" earlier in this guide.

To add a location provider

  1. In the left pane, expand the Users node, and in the right pane, right-click the name of the user that you want to add a provider for, and then click Properties.

  2. Click the Providers tab, and then choose a location provider from the Select a location provider drop-down list.

  3. In the text boxes under Locatable phone number, type the fully-qualified international phone number of the user's handheld device, and then click OK.

To add a notification provider

  1. In the left pane, expand the Users node, and in the right pane, right-click the name of the user that you want to add a provider for, and then click Properties.

  2. Click the Providers tab, and then choose a notification provider from the Select a notification provider drop-down list.

  3. In Notification Address field, type the fully-qualified e-mail address to which MapPoint Location Server will send notification messages, and then click OK.

Adding and Removing Contacts for Users

You can add contacts to or remove contacts from a user's mobile contacts list. Contacts are reciprocal; for example, if you add Jeff to Norm's mobile contacts list, Norm is automatically added to Jeff's mobile contacts list. Similarly, if you remove Jeff from Norm's mobile contacts list, Norm is automatically removed from Jeff's list.

When you add contacts, you also set their status. The status you set is reciprocal also. The following status options are available:

  • Active—The contact can locate the user.  

  • Blocked—The contact cannot locate the user, although the user still appears in the other user's contact list.

  • Pending—The user can choose whether the contact can locate him or her. This is the default status for both the user and the contact.

Before you add a contact, the contact must already be provisioned as a user of MapPoint Location Server. You cannot add Active Directory groups as contacts.

To add a contact

  1. In the left pane, expand the Users node, and in the right pane, right-click the name of the user for whom you want to add a contact, and then click Properties.

  2. Click the Contacts tab, and then click Add.

  3. In the Search By drop-down list, select the method that you want to use to search for the contact. You can search for contacts by domain and alias, display name, e-mail address, first or last name, or phone number.

  4. In the field (or fields) below the Search By drop-down list, type the search information, and then click Next.

  5. Confirm the user's identity by selecting the correct user from the drop-down list, and then click Next.

    Figure 5.  Confirm user dialog box

    Figure 5.  Confirm user dialog box

  6. When you have located the contact that you want to add, set the user's relationship to the contact by clicking Active, Blocked, or Pending, click Finish, and then click OK to close the <User Name>  Properties dialog box.

To remove a contact

  1. In the left pane, expand the Users node, and in the right pane, right-click the name of the user for which you want to remove a contact, and then click Properties.

  2. Click the Contacts tab, highlight the contact you want to remove, click Delete, and then click OK.

Modifying User Properties

You can modify the properties of an existing MapPoint Location Server user; for example, you can add a contact or change a provider that is associated with the user.

To modify user properties

  1. In the tree view, expand the Users node.

  2. In the details pane, double-click the user whose properties you want to modify.

  3. In <User Name>  Properties, do one or more of the following:

    • To change the culture that is used for Find Nearby category names and notifications, click the General tab, select a culture from the Default Language drop-down list, and then click OK.

    • To change the location or notification provider for a user, click the Providers tab, follow the procedures described in "Adding Providers for Users" earlier in this guide.

    • To add or remove contacts, click the Contacts tab, and then follow the procedures described in "Adding and Removing Contacts for Users" earlier in this guide.

Managing Providers

You can use the MapPoint Location Server management console to modify certain provider properties, but you cannot use the management console to add or remove providers.

When you expand the Providers node and then click either Location Providers or Notification Providers, details about the providers that are installed appear in the right pane, as shown in Figure 3. The right pane lists the name of the provider along with the properties Assembly, Class, Version, and Public Token. These values are set during installation and cannot be modified.

Modifying Provider Properties

In addition to the read-only properties Assembly, Class, Version, and Public Token, each provider has specific properties that you can modify. Provider-specific properties are beyond the scope of this document. For information about the properties for a particular location or notification provider, see the documentation for that provider.

To modify location or notification provider properties

  1. In the tree view, expand the Providers node and click either Location Providers or Notification Providers.

  2. In the details pane, double-click the provider whose properties you want to modify, and in the Provider Properties dialog box, click the Configuration tab.

    Figure 6.  Configuration tab

    Figure 6.  Configuration tab

  3. Double-click the property that you want to modify, and in the Edit Property dialog box, under Value, type a new value, and then click OK.

  4. Repeat the previous step to modify additional properties for the provider, and when you are finished, click OK to close the Provider Properties dialog box.

Managing Find Nearby Categories

Find Nearby categories are types of locations that a MapPoint Location Server user can search for or locate. For example, a Find Nearby category called Coffee Shops can contain a list of coffee shops that users can locate and render on maps.

You can use the MapPoint Location Server management console to add new Find Nearby categories that are useful to users and remove categories that are no longer being used. You can also modify the properties of existing Find Nearby categories and configure search filters so that users can search for members of Find Nearby categories that have specific properties and values. When you expand the Find Nearby Categories node in the tree view of the management console, the Find Nearby categories are listed in alphabetical order in the details pane.

A Find Nearby category can be associated with one or more languages, or cultures. These languages are used to display information about the category to users, based on the user's language preference. Each category requires a default language; however, after you create a Find Nearby category you can add additional languages and change the default language if necessary. For information about how to set the language preference for a user, see "Managing Users" earlier in this guide.

Adding or Removing a Find Nearby Category

To add a Find Nearby category

  1. In the tree view, right-click the Find Nearby Categories node, point to New, and then click Find Nearby Category.

  2. On the General tab, do the following:

    • In the New Find Nearby Category dialog box, in Category ID, type a unique ID for the category; for example, GasStations. This ID becomes the primary key for the category in the MapPoint Location Server database.

    • In Icon Source, provide the name of the icon data source that contains the icon you want to use to identify the category, and in Icon ID, type the name of the icon. MapPoint Web Service provides a wide variety of stock icons and you can also supply your own custom icons. For more information about icons, see the online documentation on the MapPoint Web Service Customer Services site. This site is available to MapPoint Web Service customers only.

    • In Select the properties to display for this place of interest, select the properties you want to associate with the category.

      Figure 7.  General tab

      Figure 7.  General tab

  3. Click the Languages tab, and under Add or Update category information, do the following to set a default language for the Find Nearby category:

    • In the Language drop-down list, select the language you want to use for the default language.

    • In Name type a display name for the category; for example, Gas Stations.

    • (Optional) In Description, type a brief description for the category.

    • Click Add.

      Figure 8.  Languages tab

      Figure 8.  Languages tab

  4. Click the Data tab, and under Data Source, do the following:

    • In the Select a data source drop-down list, select the data source that contains the entities for the category

    • Next to Entity type for this place of interest, click Change, select the entity type that you want to use, and then click OK.

      Figure 9.  Data tab

      Figure 9.  Data tab

  5. Click OK to create the Find Nearby category.

To remove a Find Nearby category

  1. In the tree view, expand the Find Nearby Categories node.

  2. In the details pane, right-click the category that you want to delete, and then click Delete.

  3. In the Confirm Find Nearby Category Delete dialog box, click Yes to delete the category or No to cancel.

Modifying a Find Nearby Category

After you create a Find Nearby category, you can change the icon that is associated with it, add or remove languages, change the default language, change the data source, and create filters that can narrow search results for users.

You modify a Find Nearby category by using the <Category name> Properties dialog box.

To access the dialog box

  • In the tree view, expand the Find Nearby Categories node, and in the details pane, double-click the category you want to work with.

To change the icon for a Find Nearby category

  1. On the General tab, do the following:

    • In the Icon Source drop-down list, select a new source for the icon

    • In Icon ID, type the name for the new icon.

  2. Either click OK to save the settings, or click another tab to continue setting properties.

To add a new language for a Find Nearby category

  1. On the Languages tab, do the following:

    • In the Language drop-down list, select the language that you want to add.

    • In Name type a display name in the new language.

    • (Optional) In Description, type a brief description in the new language.

    • Click Update.

  2. Either click OK to save the settings, or click another tab to continue setting properties.

To change the default language for a Find Nearby category

  1. On the Languages tab, in the Select the default language drop-down list, select a new language to use as the default.

  2. Either click OK to save the settings, or click another tab to continue setting properties.

To change the data source and entity type for a Find Nearby category

  1. On the Data tab, do the following:

    • In the Select a data source drop-down list, select a new data source.

    • Next to Entity type for this place of interest, click Change, select the entity type that you want to use, and then click OK.

  2. Either click OK to save the settings, or click another tab to continue setting properties.

To set a filter for a Find Nearby category

In a Find Nearby category, you can set filters to enable MapPoint Location Server users to search for specific properties and values associated with a specific place of interest. For instance, you might add a filter to the entries in the Coffee Houses category with a name of "State" and values of "WA" and "OR". When users search for coffee houses, they can additionally specify that they want only to see results that match the values that they have selected. You can configure up to 11 filters for each place of interest.

To modify a filter, you must delete the existing filter and add it again with the changes that you want to make.

  1. On the Data tab, do the following:

    • In the Property drop-down list, select a property that you want to use in a filter.

    • In Value, type a value for the property.

Note The value you supply is not validated. If the value does not exist, the result of a search will be NULL.

  - Click **Add** to add the filter to the list.

  1. (Optional.) Repeat the previous step to add additional filters.

  2. (Optional.) Select Places must meet all filter conditions if you want to create an AND query that uses all of the filters you've defined. If you select this check box, places of interest are not returned in a search unless they meet all of the filter criteria. If this check box is cleared, the filters are used in an OR query, and points of interest that meet any of the criteria are returned.

  3. Either click OK to save the settings, or click another tab to continue setting properties.

Using the Demonstration Location Provider

The Setup program for MapPoint Location Server Web Service includes a demonstration location provider (demo provider). You can use the demo provider to demonstrate or verify the end-to-end functionality of MapPoint Location Server without requiring a connection to a mobile operator. You can also use the demo provider as a troubleshooting tool because it is not dependent on a mobile operator's network.

You can use the demo provider by adding it as the location provider for a user. This can be done by choosing Microsoft.MapPoint.LocationServer.DemoLocationProvider as the location provider for the user. You can select the demo provider as the location provider for more than one user.

After selecting the demo provider for a user, add the locatable phone number of the user to the Testlocations.txt file in the Program Files\Microsoft MapPoint Location Server\MLS\WebService\Bin directory. You must add a line to Testlocations.txt for the locatable phone number of each user whose location provider is demo provider. Use the following format for each line:

Locatable Phone Number, Status Code, Latitude, Longitude, Delay

  • Locatable Phone Number—The locatable phone number of the user. The locatable phone number consists of the country code, area code, and phone number for the user, displayed by the Management Console in the Providers tab for the user; for example, 14255551212.

  • Status Code—A value that identifies whether the request is successful. Set this value to Success.

  • Latitude—The latitude that will be reported by the demo provider for this phone number. Positive values are in the northern hemisphere. Latitudes can be specified with up to 12 digits of precision.

  • Longitude—The longitude that will be reported by the demo provider for this phone number. Positive values are in the eastern hemisphere. Longitudes can be specified with up to 12 digits of precision.

  • Delay—The delay, in seconds, before the demo provider responds with a location. This value is optional. If the delay is not specified, the demo provider responds immediately. Only integer values can be specified for Delay; fractions and decimal values are not allowed. It is recommended that Delay be set to greater than or equal to 4 if the demo provider is being used for performance and stress testing of MapPoint Location Server.

The following line causes the demo provider to return 47.6446802586242,-122.130220099595 as the latitude and longitude pair for a user whose locatable phone number is 14255551212 after a time delay of 1 second:

14255551212,Success,47.6446802586242,-122.130220099595,1

You can also use the demo provider to simulate failures. In this case, the format of the line in Testlocations.txt must be as follows:

Locatable Phone Number,Status Code,Failure Code,Delay

  • Status Code—Failure.

  • Failure Code—One of the failure codes listed in Testlocations.txt.

  • Delay—Optional delay in seconds before the Demo Provider returns the failure code. Only integer values can be specified for Delay; fractions and decimal values are not allowed.

Using the MapPoint Location Server Tools

The MapPoint Location Server CD-ROM contains the following tools in the Tools folder:

  • Active Directory Sync tool (contained in <CD>:\Tools\Active Directory Sync)

  • Set Password tool (contained in <CD>:\ Tools\Set Password)

The following sections describe these tools and how to use them.

Active Directory Sync Tool

The Active Directory Sync tool is a command-line tool that synchronizes the user account information in the MapPoint Location Server database with the instance of Active Directory in which the user accounts exist.

When a user is provisioned, MapPoint Location Server queries Active Directory for the following properties: Domain\Alias, Display Name, First Name, Last Name, and Email address. These Active Directory values are then inserted into the MapPoint Location Server database. After provisioning, these Active Directory properties can change. For example, a user's surname can change after marriage. If such a change is made in Active Directory, the change should also be made in the MapPoint Location Server database.

When you run the Active Directory Sync tool, it queries Active Directory for each MapPoint Location Server user and can update the MapPoint Location Server database if any of the Active Directory fields have changed. You can also use the Active Directory Sync tool to delete users that no longer exist in Active Directory.

Running the Active Directory Sync Tool

You run the synchronization tool from a command prompt, using the following syntax:

mlsadsync –s SQLServerName -d DatabaseName

Parameters

-s—The name of the SQL Server instance that hosts the MapPoint Location Server database

-d—The name of the MapPoint Location Server database

-p—Show pending synchronization changes

-delete—Delete users that cannot be found in Active Directory

-ls—Delimit the output using a semicolon

-lt—Delimit the output using a tab

You must provide a server name and a database name.

The server name must follow the –s parameter.

The database name must follow the –d parameter.

If you want to run the tool but do not want to make changes to the database, you can specify the optional –p parameter. The tool then displays the changes that need to be made, but it does not actually update the database.

The –delete parameter deletes users from the MapPoint Location Server database that do not match users in Active Directory. If you use the –delete parameter in conjunction with the -p parameter, the output of the tool includes a list of users that cannot be matched to users in Active Directory, but no deletions are made.

When you run the tool, it displays the set of changes that have been made or need to be made (depending on the –p parameter). For example:

<fourthcoffee>\<JoeC>, Update required, Email address changed from 
"joe@ fourthcoffee.com" to "joec@ fourthcoffee.com"

By default, the tool separates the user name from the type of change with a comma.

Scheduling Synchronization

You should run the Active Directory Sync tool on a regular basis (such as once every 24 hours). You can run the tool directly from the Windows Task Scheduler if you do not want to store an output log. However, you can add a synchronization command that includes a command extension to log the results to a batch file that you can then run by using the Windows Task Scheduler. A sample batch file is as follows:

REM *************************************************************************** 
REM **  File Name:       mlsadsynch.bat 
REM ** 
REM **  Description:     Calling this batch file from Windows Task Scheduler will
REM **                   allow piping the output to a file for logging purposes.
REM **  Called By:       Windows Task Scheduler 
REM ** 
REM **  Calls:           mlsadsynch.exe 
REM ** 
REM ** Usage: 1.edit path to mlsadsynch.exe 
REM **        2.edit servername 
REM **        3.edit databasename 
REM **        4.edit path\output file name      
REM ** 
REM *************************************************************************** 
C:\MLSADSynch\Mlsadsynch.exe -s servername -d databasename >> c:\MLSadsynch\synchlog.txt

Set Password Tool

MapPoint Location Server uses the MlsWebService domain account to connect to the MapPoint Location Server database. The password for this account is stored in encrypted form in the MapPoint Location Server Web Service Web.config file. The Set Password tool is a command-line tool that you can use to update the encrypted password in the Web.config file when the password changes; for example, to comply with your company's security policy.

Running the Set Password Tool

You can run the tool in interactive mode from a command prompt by typing the following line:

mlssetpassword

You will be prompted for the following information:

  • The full path of the Web.config file; for example, C:\Program Files\Microsoft MapPoint Location Server\MMLS\WebService\Web.config.

  • Old password—The old password for the MlsWebService account

  • New password—The new password for the MlsWebService account

  • Confirm password—Confirm the new password for the MlsWebService account

Before running the tool, ensure that you have the permission to update the Web.config file—you must be a member of the local administrators group, the global administrators group, or the MLSAdministrators group.

You can also run the tool in command-line mode by using the following syntax:

mlssetpassword /w:<full path of Web.config> /o:<old password> /p:<new password>

Note If either the old or the new password contains quotation marks ("), you cannot run the Set Password tool in command-line mode.

If the old password that you provide does not match the password stored in the Web.config file, the tool will not update the password. If you forget the old password, you must manually update the value attribute of the add element (<add key ="Password", value ="encrypted old password"/>) in the appSettings section of the Web.config file, as follows:

<add key="Password" value="" />

Save the Web.config file after making the change, run the Set Password tool again, and do not provide any input for the old password.