TechNet Blogs

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.

Provisioning Mechanisms

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:

Priority	Mechanism	How It Works
1	Local registry	Reads the HKEY_LOCAL_MACHINE\Software\Microsoft\ Communicator keys (Computer registry keys)
2	Local registry	Reads the HKEY_CURRENT_USER\Software\Microsoft\ Communicator keys (Current user registry keys)
3	GPO	Reads the HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\ Communicator keys (Computer GPO)
4	GPO	Reads the HKEY_CURRENT_USER\Software\Policies\Microsoft\ Communicator keys (User GPO)
5	DNS	DNS requests
6	In-band	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.

In-band Provisioning

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:

<Name>Local.LitwareInc.com</Name>

<Rule>

<InternalEnterpriseExtension>false</InternalEnterpriseExtension>

</Rule>

</LocationProfileDescription>

The structures sent to the client, as well as the type of information contained in each structure, is shown in the following table:

Structure	Content type
ms-location-profile-definition	Location Profile related
vnd-microsoft-roaming-contacts	User Contacts
vnd-microsoft-provisioning-v2	End Point Configuration Location Policy, Media Configuration, Meeting Policy, Presence Policy V2 Privacy Publication Grammar Publication Grammar Server Configuration UC Phone Settings UC Policy User Settings,
vnd-microsoft-roaming-self	General user properties
Conferencing	Conferencing capabilities

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.

Structure: ms-location-profile-definition

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).

Location Profile

Parameter	Default Value	PowerShell Command
Name A friendly name for the dial plan.	DefaultProfile	Set-CsDialPlan (SimpleName parameter)
Pattern A regular expression representing the number pattern to which the Translation will be applied.	^(\d{11})$	Set-CsOutboundTranslationRule (Pattern parameter)
Translation A regular expression that will be applied to the number matching the Pattern to prepare that number for outbound routing.	+$1	Set-CsOutboundTranslationRule (Translation parameter)
InternalEnterpriseExtension If 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.	False	Set-CsVoiceNormalizationRule (IsInternalExtension parameter)
ApplicableForDeviceDialing	True
ExternalAccessPrefix A 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.	9	Set-CsDialPlan (ExternalAccessPrefix parameter)
OptimizeDeviceDialing Determines 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.	True	Set-CsDialPlan (OptimizeDeviceDialing parameter)

Structure: vnd-microsoft-provisioning-v2

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.

End Point Configuration

Parameter	Default Value	PowerShell Command
ShowRecentContacts When 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.	True	Set-CsClientPolicy (ShowRecentContacts parameter)
ShowManagePrivacyRelationships When 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.	False	Set-CsClientPolicy (ShowManagePrivacyRelationships parameter)
MaxPhotoSizeKB Indicates the maximum size (in kilobytes) for photos displayed in Microsoft Lync. Setting the MaxPhotoSize to 0 prevents any photos from being displayed in Lync.	30	Set-CsClientPolicy (MaxPhotoSize parameter)
ExchangeContactStoreAllowed When 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.	False	Set-CsClientPolicy (ExchangeContactStoreAllowed parameter)
PhotoUsage Determines whether or not photos (of both the user and his or her contacts) will be displayed in Lync.	AllPhotos	Set-CsClientPolicy (DisplayPhoto parameter)
AbsUsage Indicates 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).	WebSearchAndFileDownload	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.

Location Policy

Parameter	Default Value	PowerShell Command
EnhancedEmergencyServicesEnabled Specifies 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.	False	Set-CSLocationPolicy (EnhancedEmergencyServicesEnabled parameter)
LocationPolicyTagID	user-tagid

The Media Configuration substructure is used for media settings:

Media Configuration

Parameter	Default Value	PowerShell Command
bypassEnabled	False

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.

Presence Policy V2

Parameter	Default Value	PowerShell Command
EnablePrivacyMode If 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.	False	Set-CsPrivacyConfiguration (EnablePrivacyMode parameter)
EnableLocationPrompt If 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.	False	Set-CsPrivacyConfiguration (EnableLocationPrompt parameter)
AutoInitiateContacts If True, Microsoft Lync will automatically add all of your team members to your contact list.	True	Set-CsPrivacyConfiguration (AutoInitiateContacts parameter)
PublishLocationDataDefault If 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.	True	Set-CsPrivacyConfiguration (PublishLocationDataDefault parameter)
DisplayPublishedPhotoDefault If 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.	True	Set-CsPrivacyConfiguration (DisplayPublishedPhotoDefault parameter)
PersonalNoteHistoryDepth Indicates 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.	3	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.

Meeting Policy

Parameter	Default Value	PowerShell Command
AllowIPAudio Indicates whether or not computer audio are allowed in the meeting.	True	Set-CsConferencingPolicy (AllowIPAudio parameter)
AllowIPVideo Indicates whether or not computer video are allowed in the meeting.	True	Set-CsConferencingPolicy (AllowIPVideo parameter)
EnableAppDesktopSharing Indicates whether participants are allowed to share applications (or their desktop) during the course of a meeting.	True	Set-CsConferencingPolicy (EnableAppDesktopSharing parameter)
AllowAppSharingForExternalMeeting	None
RetainPPTForExternalMeeting	True
AllowPresenterToRecord	True
EnableDataCollaboration Indicates whether users are allowed to join the meeting over the Internet, provided they are using a supported Web browser.	True	Set-CsConferencingPolicy (EnableDataCollaboration parameter)
MeetingSize Indicates 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.	200	Set-CsConferencingPolicy (MaxMeetingSize parameter)
EnablePSTNConferencing Indicates whether users are able to join the meeting by dialing in with a PSTN (Public Switched Telephone network) telephone.	True	Set-CsConferencingPolicy (EnableDialInConferencing parameter)
TrustedConferencingPinRequired	False
AllowParticipantControl Indicates whether or not meeting participants are allowed to take control of applications shared during the meeting.	True	Set-CsConferencingPolicy (AllowParticipantControl parameter)
AllowAnnotations Indicates whether or not participants are allowed to make onscreen annotations on any content shared during the meeting.	True	Set-CsConferencingPolicy (AllowAnnotations parameter)
AllowAnonymousParticipants 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.	True	Set-CsConferencingPolicy (AllowAnonymousParticipantsInMeetings parameter)
AllowExternalUserControl Indicates whether external users (that is, users not currently logged-on to your network) are allowed to take control of shared applications or desktops.	False	Set-CsConferencingPolicy (AllowExternalUserControl parameter)
AllowExternalUserRecording Indicates whether external users (that is, users not currently logged-on to your network) are allowed to record the meeting.	False	Set-CsConferencingPolicy (AllowExternalUsersToRecordMeetings parameter)
AllowRecording Indicates whether users are allowed to record the meeting.	True	Set-CsConferencingPolicy (EnableRecording parameter)
AllowFileTransfer Indicates whether file transfers to all meeting participants are allowed during the meeting.	True	Set-CsConferencingPolicy (EnableFileTransfer parameter)
MaxConferenceVideoResolution Indicates the maximum resolution for meeting video.	VGA	Set-CsConferencingPolicy (MaxVideoConferenceResolution parameter)
AllowUserToScheduleMeetingsWithAppSharing Indicates whether or not users are allowed to schedule meetings that including application sharing.	True	Set-CsConferencingPolicy (AllowUserToScheduleMeetingsWithAppSharing parameter)
EnableP2PFileTransfer Indicates whether peer-to-peer file transfers (that is, file transfers that do not involve all participants) are allowed during the meeting.	True	Set-CsConferencingPolicy (EnableP2PFileTransfer parameter)
AllowedAppDesktopSharingLevel Indicates whether participants are allowed to share applications (or their desktop) during the course of a meeting.	Desktop	Set-CsConferencingPolicy (EnableAppDesktopSharing parameter)
AudioBitRate Bit rate (in kilobytes) used for audio transmissions.	200	Set-CsConferencingPolicy (AudioBitRateKb parameter)
VideoBitRate Bit rate (in kilobytes) used for video transmissions.	2000	Set-CsConferencingPolicy (VideoBitRateKb parameter)
AppSharingBitRate Bit rate (in kilobytes) used for application sharing.	2000	Set-CsConferencingPolicy (AppSharingBitRate parameter)
FileTransferBitRate Bit rate (in kilobytes) used for file transfers.	2000	Set-CsConferencingPolicy (FileTransferBitRate parameter)

Structure: vnd-microsoft-roaming-self

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.

Parameter	Default Value	PowerShell Command
contactCard	AD Display Name, …
Note	None
…	...
personalInformationManager	Outlook
autoRetrieveOofFromOutlook When 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.	True	Set-CsClientPolicy (DisablePresenceNote parameter)
publishCalendarPresence When 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.	True	Set-CsClientPolicy (DisableCalendarPresence parameter)
imAutoArchiving When 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.)	True	Set-CsClientPolicy (EnableImAutoArchiving parameter)
callLogAutoArchiving When 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.	True	Set-CsClientPolicy (EnableCallLogAutoArchiving parameter)
publishMeetingSubjectAndLocation When 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.)	True	Set-CsClientPolicy (DisableMeetingSujectAndLocation parameter)
telephonyMode	None	See How Can I Configure the Telephony Options for a User?
lineType The user’s Enterprise Voice telephone number.	None	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.

Lync PowerShell