In-Band Provisioning and Microsoft Lync Server 2010
Submitted by Daniel Monier-Reyes, Microsoft
In-band provisioning is not a new feature; in-band provisioning already exists in several versions of Microsoft Office Communications Server. With Microsoft Lync Server 2010 (formerly known as Microsoft Communications Server “14”), however, in-band provisioning becomes an especially powerful mechanism for managing the behavior of client applications such as Microsoft Lync.
If you aren’t familiar with the term, “in-band provisioning” involves configuration information sent from a server to a client application. In this article, we’re going to look at the information sent to Microsoft Lync after you first logon to Microsoft Lync Server 2010.
Before we go any further we should note that this article is based on the beta version of Lyn Server; therefore, you shouldn’t be surprised if there are changes between now and the time when Lync Server is actually released. In addition to that, most of the protocols and structures discussed in this article have not been fully documented; because of that, we use network and system traces to try and determine how in-band provisioning works in the new version of Lync Server. (Think of it as reverse engineering.) That means that much of this information is preliminary in nature; there will likely be much more information available on this subject in the future.
In case you’re wondering, we used Lync Server’s OCSLogger tool to collect the network and system traces; this tool is available when you install Microsoft Lync Server 2010. We also used Process Monitor to help trace system accesses, especially when trying to figure out how Lync reads configuration information from the registry.
This article is based on a very simple setup: a single, Standard Edition Lync Server front end. In addition, we looked only at Microsoft Lync; we did not examine Attendee Lync, Lync Attendant Console, or Lync Phone Edition.
In Lync Server 2010 several different provisioning mechanisms are available to manage client applications. For example, Lync Server includes:
· Group Policy, a provisioning tool available in previous versions of Office Communications Server.
· Registry keys on the client computer, in both the HKEY_LOCAL_MACHINE and HKEY_CURRENT_USER hives. We won’t spend much time talking about registry keys in this article.
· DNS, which is typically used to retrieve the name of the connection server.
· In-band provisioning, a SIP-based process allowing for central management of client applications.
These four provisioning tools differ in both capabilities and flexibility. For example, registry keys offer more options for configuring client applications than does Group Policy; however, it’s much easier to configure and apply Group Policy Objects (GPOs) than it is to “manually” change registry keys on all your client computers. Likewise, in-band provisioning enables you to retrieve configuration information over the Internet or from computers that are not members of your domain; that isn’t true for GPOs, which are applied only to computers logging on to your internal network.
The point is not that one provisioning mechanism is better than another; the point is that there is no such thing as the “ultimate” provisioning tool, and to manage client applications means using all the mechanisms available to you. That’s why it’s important to understand the precedence rule; that is, in case of a conflict, which of these tools takes priority.
Priority Between Mechanisms
The following table shows the priority ordering for Lync Server’s provisioning mechanisms:
How It Works
Reads the HKEY_LOCAL_MACHINE\Software\Microsoft\Communicator keys (Computer registry keys)
Reads the HKEY_CURRENT_USER\Software\Microsoft\Communicator keys (Current user registry keys)
Reads the HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Communicator keys (Computer GPO)
Reads the HKEY_CURRENT_USER\Software\Policies\Microsoft\Communicator keys (User GPO)
Communications via SIP (Session Initiation Protocol)
When you first start Microsoft Lync, the application reads the appropriate registry keys in both the HKEY_LOCAL_MACHINE and the HKEY_CURRENT_USER hives. After that’s done, the application next reads values configured in Software\Policies\Microsoft\Communicator; this is where Group Policy Objects store configuration information. After these registry keys have been read (from both HKEY_LOCAL_MACHINE and the HKEY_CURRENT_USER), Lync might then use DNS to retrieve the name of the connection server. It’s only after you make that connection that in-band provisioning comes into play.
Let’s now talk about in-band provisioning and how it works. After Lync has been authenticated (meaning it has successfully provided the server with a SIP address and its associated user credentials), the front end server begins to send information through the SIP channel. This information is organized in a series of XML structures that look similar to this:
The structures sent to the client, as well as the type of information contained in each structure, is shown in the following table:
Location Profile related
End Point Configuration
Presence Policy V2
Privacy Publication Grammar
UC Phone Settings
General user properties
As you can see there are basically five different structures sent to Lync:
· ms-location-profile-definition – This is information related to the user’s location profile. If the user has not been enabled for Enterprise Voice then this structure will be empty.
· vnd-microsoft-roaming-contacts – This is parameter information used to retrieve the user’s contacts. We’re not going to discuss this structure in this article.
· vnd-microsoft-provisioning-v2 – This structure provides a huge amount of information that is of particular interest to system administrators. We’ll discuss this structure in more detail in just a minute.
· vnd-microsoft-roaming-self – This structure includes general information such as the user’s display name, his or her location, and the his or her Activity Feed notes.
· Conferencing – This structure contains information about the conferencing capabilities of the server. It’s another structure we won’t discuss in any detail in this article.
Let’s take a closer look at some of these structures. In the next few sections of the article, we’ll take a look at:
· The structure parameters, which are equivalent to Lync/user properties.
· The default value for these parameters.
· The Windows PowerShell cmdlet and parameter that can be used to change the values for these properties.
As noted earlier, if you simply enable a user for Lync Server but do not assign that user any telephony options then this structure will be empty. In order to get back information, we have to enable a user for Enterprise Voice and assign him or her a line URI.
Note. For more information on setting telephony options for a user see the article How Can I Configure the Telephony Options for a User?
The following table shows the location profile information returned for a sample user (note the default values).
NameA friendly name for the dial plan.
Set-CsDialPlan (SimpleName parameter)
PatternA regular expression representing the number pattern to which the Translation will be applied.
Set-CsOutboundTranslationRule (Pattern parameter)
TranslationA regular expression that will be applied to the number matching the Pattern to prepare that number for outbound routing.
Set-CsOutboundTranslationRule (Translation parameter)
InternalEnterpriseExtensionIf True, the result of applying this rule will be a number internal to the enterprise. If False, applying the rule results in an external number.
Set-CsVoiceNormalizationRule (IsInternalExtension parameter)
ExternalAccessPrefixA number (or set of numbers) that designates the call as external to the organization. (For example, to dial an outside line, first press 9.) This prefix will be ignored by the normalization rules, although these rules will be applied to the rest of the number. This prefix is applicable only to off-hook (from a phone, not from Communicator) dialing.
Set-CsDialPlan (ExternalAccessPrefix parameter)
OptimizeDeviceDialingDetermines whether normalization rules will be applied differently based on whether a call was made from Lync or from an off-hook device (a phone). If True, the prefix in the ExternalAccessPrefix parameter will be applied to calls outside the organization.
Set-CsDialPlan (OptimizeDeviceDialing parameter)
The vnd-Microsoft-provisioning-v2 structure contains 5 substructures:
· End Point Configuration
· Location Policy
· Media Configuration
· Presence Policy V2
· Meeting Policy
The End Point Configuration includes parameters that dictate the maximum size of photos displayed in Lync; determine whether or not the Frequent Contacts list is displayed; and specify how the Address Book is searched. These parameters, shown in the following table, can be managed using the Set-CsClientPolicy and New-CsClientPolicy cmdlets.
ShowRecentContactsWhen set to True, the contact list will include an auto-generated category named Frequent Contacts. When set to False, the Frequent Contacts category will not be auto-generated.
Set-CsClientPolicy (ShowRecentContacts parameter)
ShowManagePrivacyRelationshipsWhen set to True, shows the "Manage privacy relationships" option in the View By menu. When set the True, hides the Manage privacy relationships" option in the View By menu.
Set-CsClientPolicy (ShowManagePrivacyRelationships parameter)
MaxPhotoSizeKBIndicates the maximum size (in kilobytes) for photos displayed in Microsoft Lync. Setting the MaxPhotoSize to 0 prevents any photos from being displayed in Lync.
Set-CsClientPolicy (MaxPhotoSize parameter)
ExchangeContactStoreAllowedWhen set to True, a user’s contacts will be kept on his or her Microsoft Exchange server rather than being kept by Microsoft Lync Server. This setting has no effect unless the user’s mailbox is stored on Microsoft Exchange Server 2010, Service Pack 1 or later.
Set-CsClientPolicy (ExchangeContactStoreAllowed parameter)
PhotoUsageDetermines whether or not photos (of both the user and his or her contacts) will be displayed in Lync.
Set-CsClientPolicy (DisplayPhoto parameter)
AbsUsageIndicates how users are allowed to access information in the Address Book server (that is, by using the Address Book Web service and/or by downloading a copy of the Address Book to their local computer).
Set-CsClientPolicy (AddressBookAvailability parameter)
The Location Policy substructure (shown below) includes an interesting parameter: EnhancedEmergencyServicesEnabled, which is used with the new E9-1-1 service. By default, this parameter is disabled.
EnhancedEmergencyServicesEnabledSpecifies whether the users associated with this policy are enabled for E9-1-1. Set the value to True to enable E9-1-1, so Lync Server clients will retrieve location information on registration and include that information when an emergency call is made.
Set-CSLocationPolicy (EnhancedEmergencyServicesEnabled parameter)
The Media Configuration substructure is used for media settings:
Meanwhile, the Presence Policy V2 substructure is used to manage the new privacy settings included in Microsoft Lync. Most of these settings can be managed using the Set-CsPrivacyConfiguration and New-CsPrivacyConfiguration cmdlets.
EnablePrivacyModeIf True, only people on your contact list will be allowed to view your presence information. If False, your presence information will be available to anyone in your organization.
Set-CsPrivacyConfiguration (EnablePrivacyMode parameter)
EnableLocationPromptIf True, then users will be prompted any time location data is requested by an out-of-process application; users can then choose not to send this data. If False, location data will automatically be sent to any application that requests it.
Set-CsPrivacyConfiguration (EnableLocationPrompt parameter)
AutoInitiateContactsIf True, Microsoft Lync will automatically add all of your team members to your contact list.
Set-CsPrivacyConfiguration (AutoInitiateContacts parameter)
PublishLocationDataDefaultIf True, location data will automatically be published in Microsoft Lync. If False, location data will not be available unless the user explicitly selects the option Show Contacts My Location.
Set-CsPrivacyConfiguration (PublishLocationDataDefault parameter)
DisplayPublishedPhotoDefaultIf True, the user’s photo will automatically be published in Microsoft Lync. If False, the user’s photo will not be available unless he or she explicitly selects the option Let others see my photo.
Set-CsPrivacyConfiguration (DisplayPublishedPhotoDefault parameter)
PersonalNoteHistoryDepthIndicates the maximum number of personal notes that are stored in the user’s note history. By default, the last 3 personal notes are maintained in the note history.
Set-CsUserServicesConfiguration (MaxPersonalNotes parameter)
And then is the very large and very comprehensive Meeting Policy substructure. These parameters can be modified by using the New-CsConferencingPolicy and the Set-CsConferencingPolicy cmdlets.
AllowIPAudioIndicates whether or not computer audio are allowed in the meeting.
Set-CsConferencingPolicy (AllowIPAudio parameter)
AllowIPVideoIndicates whether or not computer video are allowed in the meeting.
Set-CsConferencingPolicy (AllowIPVideo parameter)
Indicates whether participants are allowed to share applications (or their desktop) during the course of a meeting.
Set-CsConferencingPolicy (EnableAppDesktopSharing parameter)
EnableDataCollaborationIndicates whether users are allowed to join the meeting over the Internet, provided they are using a supported Web browser.
Set-CsConferencingPolicy (EnableDataCollaboration parameter)
MeetingSizeIndicates the maximum number of people who are allowed to attend a meeting. After the maximum number of participants has been reached anyone else who tries to join the meeting are turned away with the notice that the meeting is full.
Set-CsConferencingPolicy (MaxMeetingSize parameter)
EnablePSTNConferencingIndicates whether users are able to join the meeting by dialing in with a PSTN (Public Switched Telephone network) telephone.
Set-CsConferencingPolicy (EnableDialInConferencing parameter)
Indicates whether or not meeting participants are allowed to take control of applications shared during the meeting.
Set-CsConferencingPolicy (AllowParticipantControl parameter)
Indicates whether or not participants are allowed to make onscreen annotations on any content shared during the meeting.
Set-CsConferencingPolicy (AllowAnnotations parameter)
Indicates whether anonymous users are allowed to participate in the meeting. If set to false ($False) then only authenticated users (that is, users logged on to your Active Directory or the Active Directory of a federated partner) are allowed to attend the meeting.
Set-CsConferencingPolicy (AllowAnonymousParticipantsInMeetings parameter)
Indicates whether external users (that is, users not currently logged-on to your network) are allowed to take control of shared applications or desktops.
Set-CsConferencingPolicy (AllowExternalUserControl parameter)
Indicates whether external users (that is, users not currently logged-on to your network) are allowed to record the meeting.
Set-CsConferencingPolicy (AllowExternalUsersToRecordMeetings parameter)
Indicates whether users are allowed to record the meeting.
Set-CsConferencingPolicy (EnableRecording parameter)
Indicates whether file transfers to all meeting participants are allowed during the meeting.
Set-CsConferencingPolicy (EnableFileTransfer parameter)
Indicates the maximum resolution for meeting video.
Set-CsConferencingPolicy (MaxVideoConferenceResolution parameter)
Indicates whether or not users are allowed to schedule meetings that including application sharing.
Set-CsConferencingPolicy (AllowUserToScheduleMeetingsWithAppSharing parameter)
Indicates whether peer-to-peer file transfers (that is, file transfers that do not involve all participants) are allowed during the meeting.
Set-CsConferencingPolicy (EnableP2PFileTransfer parameter)
Bit rate (in kilobytes) used for audio transmissions.
Set-CsConferencingPolicy (AudioBitRateKb parameter)
Bit rate (in kilobytes) used for video transmissions.
Set-CsConferencingPolicy (VideoBitRateKb parameter)
Bit rate (in kilobytes) used for application sharing.
Set-CsConferencingPolicy (AppSharingBitRate parameter)
Bit rate (in kilobytes) used for file transfers.
Set-CsConferencingPolicy (FileTransferBitRate parameter)
The vnd-microsoft-roaming-self structure includes the display name for the user. In addition, this parameter is used to modify the interaction between Microsoft Lync and Microsoft Outlook, including such things as whether or not your Outlook calendar information is displayed as part of your presence information.
AD Display Name, …
autoRetrieveOofFromOutlookWhen set to True, any Out of Office message you configure in Microsoft Outlook will not be displayed as part of your presence information. When set to False, your Out of Office message will be displayed any time a user holds the mouse over your name in their contact list.
Set-CsClientPolicy (DisablePresenceNote parameter)
publishCalendarPresenceWhen set to True, calendar data taken from Microsoft Outlook will not be included in your presence information. When set to False, calendar data will be included in your presence information. For example, free/busy information will be reported in your contact card. Likewise, your status will automatically be set to Busy any time Outlook shows that you are in a meeting.
Set-CsClientPolicy (DisableCalendarPresence parameter)
imAutoArchivingWhen set to True, a transcript of every instant message session that a user takes part in will be saved to the Conversation History folder in Microsoft Outlook. When set to False, these transcripts will not be saved automatically. (However, users will still have the option to manually save instant message transcripts.)
Set-CsClientPolicy (EnableImAutoArchiving parameter)
callLogAutoArchivingWhen set to True, information about your incoming and outgoing phone calls is automatically saved to the Conversation History folder in Microsoft Outlook. (The actual call itself is not recorded. What is recorded is information such as who took part in the call; the length of the call; and whether this was an incoming or an outgoing call.) When set to False, this phone call information is not saved to Outlook.
Set-CsClientPolicy (EnableCallLogAutoArchiving parameter)
publishMeetingSubjectAndLocationWhen set to True, detailed information about a meeting - namely, the meeting subject and the location where the meeting is being held - will be displayed as a tooltip when you view free/busy information in a contact card. When set the False, this detailed information will not be displayed. (However, free/bust information will be displayed unless you also set DisableCalendarPresence to True.)
Set-CsClientPolicy (DisableMeetingSujectAndLocation parameter)
See How Can I Configure the Telephony Options for a User?
The user’s Enterprise Voice telephone number.
Set-CsUser (LineUri parameter)
Note that the telephonyMode parameter will be empty if the user has not been enabled for Enterprise Voice.
That’s All For Now
We hope you found this preliminary information useful; it should give you a basic understanding of how in-band provisioning affects client applications logging on to Microsoft Lync Server 2010. We’ll keep you posted as more information becomes available.