New-CsClientVersionMap [-FriendlyName <String>] [-UserAgent <String>]

Parameters

Client version configuration settings help determine which client applications are allowed to log on to Microsoft Communications Server and which client applications are not allowed to log on to the system. The action to be taken when a specific client application tries to access the system is managed by client version policy policies and client version rules: a rule might specify whether or not client X should be allowed to log on, while a policy is simply a collection of these individual rules. The purpose of the client version configuration settings is to manage the overall process of client version checking and filtering. For example, what happens if a user tries to log on using an application that is not handled by a client version rule? That’s fine: there’s a configuration setting (DefaultAction) that lets you specify the action to be taken in just such a case. Likewise, the configuration settings can be enabled or disabled. When the settings are disabled, then no client version checking of any kind takes place.

Client version configuration settings also store user agent mappings for client applications. When a client attempts to log on to Microsoft Communications Server, the application transmits a SIP header that includes information identifying the application type; for example, Office Communicator includes the designator OC in order to inform Communications Server that it is an instance of Office Communicator. OC is all the information that the serve needs; however, a designator such as OC might not be particularly useful for administrators. (For example, what do you suppose the designator UCCP stands for?) To help put a friendlier face on these designators, user agent mappings associated friendly name with each designator. UCCP? As it turns out, the friendly name for that designator is Unified Communications and Platform Client.

User agent mappings for a number of SIP clients are provided for you when you install Microsoft Communications Server. It’s possible, however, that you will need additional mappings somewhere down the road; for example, your organization might develop its own SIP client for use in-house. The New-CsClientVersionMap cmdlet provides a way for you to add new mappings (or delete existing mappings) from a collection of client version configuration settings.

New-CsClientVersionMap creates new instances of the Microsoft.Rtc.Management.WriteableConfig.Policy.ClientVersion.Map object.

-------------------------- Example 1 ------------------------

	Copy Code
$x = New-CsClientVersionMap -UserAgent LIC -FriendlyName "Litwareinc Client" Set-CsClientVersionConfiguration -Identity site:Redmond -UserAgentMapping @{Add=$x}

The command shown in Example 1 adds a new user agent mapping to the client version configurations settings applied to the Redmond site. To do this, the first command in the example uses New-CsClientVersionMap to create a mapping between the user agent designator LIC and the friendly name Litwareinc Client. The new mapping is then stored in a variable named $x.

In the second command, Set-CsClientVersionConfiguration is used to add this new mapping to the client version configuration settings with the Identity site:Redmond. This is done by adding the –UserAgentMapping parameter and the parameter value @{Add=$x}. That parameter value tells Set-CsClientVersionConfiguration to add the value stored in the variable $x to all the other mappings currently housed in the UserAgentMapping property.

-------------------------- Example 2 ------------------------

	Copy Code
$x = New-CsClientVersionMap -UserAgent LIC -FriendlyName "Litwareinc Client" Set-CsClientVersionConfiguration -Identity site:Redmond -UserAgentMapping @{Remove=$x}

The preceding command removes a user agent mapping from the client version configurations settings applied to the Redmond site. To carry out this task, the first of the two commands uses New-CsClientVersionMap to replicate the mapping between the user agent designator LIC and the friendly name Litwareinc Client. This mapping is then stored in a variable named $x.

The second command then uses Set-CsClientVersionConfiguration to remove the mapping from the client version configuration settings for the Redmond site. This is done by including the –UserAgentMapping parameter and the parameter value @{Remove=$x}. That syntax tells Set-CsClientVersionConfiguration to remove the value in the UserAgentMapping property that matches the value stored in the variable $x.