Microsoft Lync Server 2010 Locations


Microsoft Lync Server 2010 introduces the ability to provide location information about users. This feature is primarily used for Enhanced 9-1-1 (E9-1-1) to more effectively and efficiently dispatch emergency responders. Prior to the Cumulative Update 1 (CU1) for Microsoft Lync 2010, this feature was available in the United States only. This article describes how location information is managed and shown to the user. It is outside the scope of this article to describe how the location information is used for E9-1-1. For more information, see E9-1-1 Support in Lync Server 2010.

AuthorJens Trier Rasmussen

Publication date: March 2011

Product version: Lync Server 2010, Lync 2010 CU1

Lync Server 2010 includes the Location Information service, which provides location information to clients such as Lync 2010 and Microsoft Lync 2010 Phone Edition. The primary use of location information is for E9-1-1 emergency service in the United States; however, location information can also be used without implementing E911, to display location as part of a user's presence information. This article describes how to configure location information, the policies that control location settings, and the user experience.

Defining Locations

Lync Server associates locations, also known as civic addresses, with the following network components:

  • Ports
  • Switches
  • Subnets
  • Wireless Access Points (WiFi)

Locations are managed in the Lync Server Management Shell with the following cmdlets:

  • Set-CsLisLocation
  • Set-CsLisPort
  • Set-CsLisSwitch
  • Set-CsLisSubnet
  • Set-CsLisWirelessAccessPoint

Set-CsLisLocation only defines the location, while the other cmdlets create a mapping between a port, switch, subnet, or wireless access point and a physical address. The following is an example of associating a location to a subnet is shown:

Set-CsLisSubnet -Subnet 10.164.25.0 -Description "Corp" -Location "Redmond" -CompanyName "Contoso Corporation" -HouseNumber "123" -HouseNumberSuffix "" -PreDirectional "" -StreetName "Contoso Way" -StreetSuffix "" -PostDirectional "" -City Redmond -State "WA" -PostalCode 73291  -Country US

This cmdlet will associate the subnet 10.164.25.0 with the physical address Contoso Corporation, 123 Contoso Way, Redmond,  WA, 73291, United States.

To get a list of locations, use the cmdlet Get-CsLisCivicAddress. An example of output from this cmdlet is shown in Figure 1.

Figure 1 Output from Get-CsLisCivicAddress

Location information is stored in a dedicated database (lis) in the Central Management Server. After mapping location information to network subnets using the preceding cmdlets, use the cmdlet Publish-CsLisConfiguration. This cmdlet ensures that the location information is published into the Central Management Server database and, through Central Management Server replication, made available to all Lync Servers running the Location Information service.

Location Information Service

Every server running Microsoft Lync Server 2010, Front End Server or Microsoft Lync Server 2010 Standard Edition, runs the Location Information service, which is a web service that provides location information to Lync Server clients. The client issues the GetLocationsRequest web service, and the server responds with GetLocationsResponse. For details about these requests, see Web Services for E911 Support Protocol Specification at the MSDN website.

The Location Information service reads from its local replicated copy of the Central Management Server database.  After the Location Information service has updated the replicated location information, it writes an event with event source LS Location Information Service and event ID 52003 to the Lync Server event log on the server where it is running.

Requesting Location Information

The Lync client issues the GetLocationsRequest to the Location Information service when the user signs in and when it detects changes in the network it uses. The request includes information about the network location of the client, which is either the port, switch, subnet, or wireless access point. The following is an example of the request using a subnet:

<GetLocationsRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

  <Entity>sip:john@contoso.com</Entity>

  <RSSI>0</RSSI>

  <MAC>00-15-5d-19-41-06</MAC>

  <SubnetID>10.164.25.0</SubnetID>

  <IP>10.164.25.133</IP>

</GetLocationsRequest>

The request contains the MAC address of the computer or device running Lync, the IP subnet that the computer or device is connected to, and the IP address of the computer or device.

Receiving Location Information

Based on the information in the request, the Location Information service searches its database and returns the location associated with the network component that the user is connected to. The following is an example of a response:

<GetLocationsResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

  <ReturnCode>200</ReturnCode>

  <presenceList>

    <presence entity="sip:john@contoso.com xmlns="urn:ietf:params:xml:ns:pidf">

      <tuple id="_LIS:0">

        <status>

          <geopriv xmlns="urn:ietf:params:xml:ns:pidf:geopriv10">

            <location-info>

              <civicAddress xmlns="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr">

                <country>US</country>

                <A1>WA</A1>

                <A3>Redmond</A3>

                <PRD />

                <RD>Contoso Way</RD>

                <STS />

                <POD />

                <HNO>123</HNO>

                <HNS />

                <LOC>Redmond</LOC>

                <NAM>Contoso Corporation</NAM>

                <PC>73291</PC>

              </civicAddress>

            </location-info>

            <usage-rules>

              <retransmission-allowed xmlns="urn:ietf:params:xml:ns:pidf:geopriv10:basicPolicy">true</retransmission-allowed>

            </usage-rules>

          </geopriv>

        </status>

        <timestamp>2010-09-27T10:25:45.3967906Z</timestamp>

      </tuple>

    </presence>

  </presenceList>

</GetLocationsResponse>]

The civicAddress XML structure is defined in RFC 4119 and RFC 5139 at the RFC Editor website. The XML attributes used in the example are described in Table 1.

Table 1 CivicAddress XML attributes

XML attribute

Description

country

The country/region identified by the two-letter ISO 3166 code

A1

National subdivisions (state, region, province, or prefecture)

A3

City or township

PRD

Leading street direction

RD

Primary road or street

STS

Street suffix

POD

Trailing street suffix

HNO

House number, numeric part only

HNS

House number suffix

LOC

Additional location information

NAM

Name (residence, business occupant, or office occupant)

PC

Postal code

In this response, the client is given the location:

Contoso Corporation

123 Contoso Way

Redmond, WA 73291

United States

Types of Locations

Lync defines three location types:

  • Validated locations are defined by using cmdlets. They have been validated against the Master Street Address Guide (MSAG) by an E9-1-1 network routing provider by using the command Test-CsLisCivicAddress -UpdateValidationStatus $true. Validated locations have the attribute MSAGValid set to True in the output of Get-CsLisCivicAddress (see Figure 1).
  • Suggested locations are defined by using cmdlets and have not been validated against the MSAG. Suggested locations have the attribute MSAGValid set to False in the output of Get-CsLisCivicAddress. They are designated as Suggested by adding the XML attribute <method>Manual</method> to the geopriv tag in GetLocationsResponse.
  • Custom locations are entered by the user and stored locally on the computer. They are stored in the PersonalLISDB.cache file in the directory  %userprofile%\AppData\Local\Microsoft\Communicator\<SIP URI of the user>

Configuring Location Policy

The client can use location information for E9-1-1 and for presence. Client use of location information is controlled by the policies LocationPolicy and PrivacyConfiguration defined on the Lync Server by using the cmdlets Set-CsLocationPolicy and Set-CsPrivacyConfiguration

The location policy assigned to the user is transferred to the client through in-band provisioning. The client issues a SUBSCRIBE request to get the provisionGroup locationPolicy. The SUBSCRIBE request includes the subnet that the client is connected to. The response from the server provides the following settings about the location policy:

<provisionGroup name="locationPolicy">

<propertyEntryList>

<property name="EnhancedEmergencyServicesEnabled" >true</property>

<property name="LocationPolicyTagID" >user-tagid</property>

<property name="LocationRequired" >yes</property>

<property name="UseLocationForE911Only" >false</property>

<property name="PstnUsage">Emergency</property>

<property name="EmergencyDialString" >911</property>

</propertyEntryList>

</provisionGroup>

The policy can be defined with different scopes. The logic of which policy is applied depends on the client's location. This logic is described as follows:

  • If the subnet (defined by the cmdlet New-CsNetworkSubnet) is associated with a network site (defined by the cmdlet New-CsNetworkSite) and that network site is associated with a LocationPolicy, this location policy is returned to the client.
  • If the subnet is unknown or if the network site isn't associated with a LocationPolicy, the location policy associated with the user is returned.
  • If the user is not associated with a location policy, the global location policy is returned.

These different scopes enable the configuration of E9-1-1, depending on which network to which the the client is connected.  For instance, you can configure the mandatory use of E9-1-1 on your corporate LAN subnets and not define it for the user and global scope. This will mean that when users are connected to the corporate LAN in the office, they will use E9-1-1, but when they connect through the Internet, they will not use E9-1-1.

The relevant parameter in the policy PrivacyConfiguration is PublishLocationDataDefault. If this parameter is set to True, the location is automatically published to other users through presence. (For details, see the "User Experience for Using Location " section.) If the parameter is set to False, the location is published only in presence and only if the user manually configures it by using the client option Show Contacts My Location. The parameter is transferred to the client through in-band provisioning in presencePolicyV2 as follows:

provisionGroup name="presencePolicyV2" >

<propertyEntryList >

<property name="EnablePrivacyMode" >true</property>

<property name="AutoInitiateContacts" >true</property>

<property name="PublishLocationDataDefault" >true</property>

<property name="DisplayPublishedPhotoDefault" >true</property>

<property name="PersonalNoteHistoryDepth" >3</property>

<property name="SubscribeToCollapsedDG" >true</property>

</propertyEntryList>

</provisionGroup>

User Experience of Setting Location Information

Two parameters of LocationPolicy are important for the user experience:

  • EnhancedEmergencyServicesEnabled, which controls whether Enhanced Emergency Services is enabled and whether the location name or details can be edited (depending on the type of information the Location Information service returns).
  • LocationRequired, which controls whether location information is required and the font color and display of the prompt that asks the user to set a location. The exact display of the prompt is  shown in the following figures. Three possible values are permitted: No, Yes, and Disclaimer. If the value is set to No, the user is not prompted to set a location. If the value is set to Yes, the user is prompted to optionally enter a location. If the value is set to Disclaimer, the user is urged to enter a location and can't dismiss the prompt.

The combination of these settings and the different types of locations determines the user experience.

At Least One Validated Location Exists

When a validated location exists, the location name is displayed on the client as shown in Figure 2.

Figure 2 Validated location exists

The location name is based on the availability of the different XML attributes in civicAddress in the GetLocationsResponse and generated as follows in priority order:

  • <LOC> <A3>
  • <NAM> <A3>
  • <A3>

The client uses the LocationPolicy parameters in the following way:

LocationRequired: Because there is a validated location returned from the server, this location is automatically chosen, and the prompt is not displayed.

EnhancedEmergencyServicesEnabled: If this value is set to True, the client displays the Set Location option, the location name can be edited, and the result can be saved as a custom location, as shown in Figure 3.

Figure 3 Set Location option for validated location

If the value is set to False, the Set Location option will not be displayed, as shown in Figure 4.

Figure 4 No Set Location option for validated location

One Suggested Location Exists

When exactly one suggested location exists, the location name is automatically displayed on the client, as if the location had been validated, as shown in Figure 2.2. 

The client uses the LocationPolicy parameters in the following way:

LocationRequired: Because there is a suggested location returned from the server, it is automatically chosen, and the prompt is not displayed.

EnhancedEmergencyServicesEnabled: If the value is set to True, the client displays the Set Location option, the location name and details can be edited, and the result can be saved as a custom location, as shown in Figure 5.

Figure 5 Set Location option for suggested location

Multiple Suggested Locations Exist

If multiple suggested locations exist, they are not automatically displayed on the client.  The user has to manually select which location to display, as shown in Figure 6.

Note:   The Location Information service cannot return multiple suggested locations, but if it is connected to a third-party Location Information Server, multiple suggested locations are possible.

Figure 6 Suggested location (showing only one suggested location)


The client uses the LocationPolicy parameters in the following way:

LocationRequired: Because there are multiple suggested locations returned from the server, the format of the prompt is the same, regardless of the value of LocationRequired, and it is "Set Your Location," as shown in Figure 6.

EnhancedEmergencyServicesEnabled: If the value is set to True, the client displays the Set Location option, the location name and details can be edited, and the result can be saved as a custom location, as shown in Figure 7.

Figure 7 Set Location option for a suggested location

No Validated, Suggested, or Custom Locations Exists

When no location exists, there is no location name to display to the user. The client uses the LocationPolicy parameters in the following way:

LocationRequired: If the value is set to No, the prompt is "Set Your Location," as shown in Figure 8.

Figure 8 Normal prompt


If the value is set to Yes, the prompt displays in red font, as shown in Figure 9. The red font is used to attract the user's attention to help get the user to set the location.

Figure 9 Red prompt

If the value is set to Disclaimer, the prompt is shown in red font, an exclamation sign is prepended, and a red X is appended, as shown in Figure 10. The exclamation mark is used to signal the urgency of the request, and the red X is used as a way to display the enhanced emergency services disclaimer.

Figure 10 Red prompt with exclamation mark and X

When the value is set to Disclaimer, it is not possible to dismiss the prompt. If the user tries, the enhanced emergency services disclaimer (set on the server by the cmdlet Set-CsEnhancedEmergencyServiceDisclaimer) is displayed to the user, as shown in Figure 11.

Figure 11 Disclaimer prompt

EnhancedEmergencyServicesEnabled: If the value is set to True, the client shows the Set Location option, the location name and details can be edited, and the result can be saved as a custom location.

Note:   If LocationRequired is set to Disclaimer and the user clicks the Set Location button in the disclaimer (see Figure 11), the user can edit the location details, even if EnhancedEmergencyServicesEnabled is set to False.

Validated and Custom Locations Exist

If both a validated and custom location exists for the same location, the client will use the following logic to decide what to display:

  • If both locations have identical address details, the custom location name is displayed, as shown in Figure 12.
  • If the locations have different address details, the validated location name is displayed.

Figure 12 Location name with validated and custom location

The client uses the LocationPolicy parameters in the following way:

LocationRequired: Because there is a validated location returned from the server, it is automatically chosen, and the prompt is not displayed.

EnhancedEmergencyServicesEnabled: If the value is set to True, the client shows the Set Location option, the location name can be edited, and the result can be saved as a Custom location.

One Suggested Location and One Custom Location Exists

If exactly one suggested and custom location exists for the same location, the client always uses the suggested location name and details.

The client uses the LocationPolicy parameters in the following way:

LocationRequired: Because there is exactly one suggested location returned from the server, it is automatically chosen, and the prompt is not shown.

EnhancedEmergencyServicesEnabled: If the value is set to True, the client displays the Set Location option, the location name and details can be edited, and the result can be saved as a custom location.

Multiple Suggested and Custom Locations Exist

When multiple suggested locations exist, the location name is not automatically displayed on the client, even if the location details are the same. Instead, the client displays the Set Your Location prompt, and it is up to the user to select the location, as shown in Figure 13.

Figure 13 Suggested and custom location (showing only one suggested location)

The client uses the LocationPolicy parameters in the following way:

LocationRequired: Because multiple suggested locations are returned from the server, the format of the prompt is the same, regardless of the value of LocationRequired, and it is "Set Your Location."

EnhancedEmergencyServicesEnabled: If the value is set to True, the client displays the Set Location option, the location name and details can be edited, and the result can be saved as a custom location.

Only a Custom Location Exists

If only a custom location exists, the location name is displayed automatically to the user at sign-in, as shown in Figure 14.

Figure 14 Custom location

The client uses the MAC address of the default gateway it is associated with to distinguish between the different networks to which it is connected. The client uses the LocationPolicy parameters in the following way:

LocationRequired: Because a custom location exists, the prompt is not displayed.

EnhancedEmergencyServicesEnabled: If the value is set to True, the client displays the Set Location option, the location name and details can be edited, and the result can be saved as a custom location. If the value is set to False, only the location name can be edited.

User Experience for Using Location Information

This section describes how location information is used in relation to presence. It does not describe how location information is used for E9-1-1, which is outside the scope of this article.

If UseLocationForE911Only is set to True in the location policy, no location information is published through presence. If it is set to False, the value of PublishLocationDataDefault determines the usage. If PublishLocationDataDefault is set True, the location is automatically published to other users through presence. If PublishLocationDataDefault is set to False, location is published in presence only if the user manually configures it by using the client option Show Contacts My Location.

The location name is the only piece of information displayed to other users, and the display is controlled by the privacy relationship. The location name is displayed in the Colleagues, Workgroup, and Friends and Family privacy relationships.

It is displayed in the Contacts list, as shown in Figure 15. However, if the user has typed in a note, the note has precedence and is displayed instead of the location name.

Figure 15 Location name in Contacts list

 

The location is also displayed in the contact card, along with the time the location was set, as shown in Figure 16.

Figure 16 Location name in contact card

Resources

Lync Server Resources

We Want to Hear from You

Keywords: locations, Lync Server, Location Information server

Comments (16)
  1. Chad says:

    Is there a way to adjust the max characters for the location parameter in cslissubnet / cslislocation? 20 is not enough characters for what we would like to display.
    Thanks!

Comments are closed.

Skip to main content