[This is preliminary documentation and is subject to change. Blank topics are included as placeholders.]

Assigns a client version policy at the global, site, service, or per-user scope. (The per-user scope enables you to assign policies to individual users or groups.) Client version policies enable you to specify which "downlevel "clients (such as Microsoft Office Communicator 2007 R2) will be able to log onto your Microsoft Communications Server 2010 system.


Grant-CsClientVersionPolicy -Identity <UserIdParameter> [-PolicyName <String>] [-Confirm [<SwitchParameter>]] [-DomainController <Fqdn>] [-PassThru <SwitchParameter>] [-WhatIf [<SwitchParameter>]]


Parameter Required Type Description



User ID Parameter

Indicates the Identity of the user account the policy should be assigned to. User Identities can be specified using one of four formats: 1) The user's SIP address; 2) the user's Universal Principal Name; 3) the user's domain name and logon name, in the form domain\logon (e.g., litwareinc\kenmyer); and, 4_ the user's Active Directory display name (for example, Ken Myer). Note that the SamAccountName cannot be used as an identity; that's because these names are not necessarily unique in a forest.

In addition, you can use the asterisk (*) wildcard character when using the Display Name as the user Identity. For example, the Identity "* Smith" would return all the users with the last name Smith.




"Name" of the policy to be assigned. The PolicyName is simply the policy Identity (minus the policy scope). For example, a policy with the Identity Redmond (which displays as tag:Redmond when you do a Get-CsClientVersionPolicy) has a PolicyName equal to Redmond; a policy with the Identity RedmondClientVersionPolicy has a PolicyName equal to RedmondClientVersionPolicy. To assign the global policy to a user, do not include the -PolicyName parameter when calling Grant-CsClientVersionPolicy.

Domain Controller





Switch Parameter

Returns an object representing the client version policy being assigned.



Switch Parameter

Describes what would happen if you executed the command without actually executing the command.



Switch Parameter

Prompts you for confirmation before executing the command.

Detailed Description

Client version policies are nothing more than a collection of client version rule. Client version rules are used to determine which client applications are allowed to log on to Microsoft Communications Server and which client applications are not allowed to log on. When a user attempts to log on to Communications Server, his or her client application sends a SIP header to the server; this header includes detailed information about the application itself, including the software’s major version, minor version, and build number. The version information included in the SIP header is then checked against a collection of client version rules to see if any rules apply to that particular application.

For example, suppose a user attempts to log on using Office Communicator version 2.0. Before logon can take place, the system will check to see if there is a client version rule that applies to Office Communicator 2.0. If such a rule exists, Microsoft Communications Server will then take the action specified by the rule. For example, the rule might tell Communications Server to allow the logon, it tell instruct Communications Server to block, or it might tell Communications Server allow the logon but then silently update the client application to the latest version of Microsoft Communicator. (This latter behavior can occur only if the user is logging on using a specified version of Office Communicator.”

Rules are designed to address client applications on a one-on-one basis: depending on your needs, you might have one rule for dealing with Office Communicator, a second rule for handling Communicator Phone Edition devices, and a third rule for Microsoft Office Live Meeting. Individual rules can then be bundled together in client version policies. These policies – which can be applied at the global scope, the site scope, the service scope (Registrar service only), or the per-user scope – give you considerable flexibility in determining which client applications can be used to access the system. For example, as a general rule you might want to prevent users from logging on using Office Communicator; after all, Office Communicator does not support the same features and capabilities as Microsoft Communicator. However, due to hardware or software conflicts you might also have a select group of users who cannot upgrade to Microsoft Communicator. In that case, you can create a separate rule – and a separate client version policy – that allows those users to log on from within Office Communicator.

The Grant-CsClientVersionPolicy cmdlet enables you to assign client version policies to individual users. (That is, policies configured at the per-user scope.) When you create a per-user policy that policy is not automatically assigned to anyone; assignment does not take place (and the policy is not actually used) until you call Grant-CsClientVersionPolicy top explicitly assign the policy to a user or set of users.

Return Types

Grant-CsClientVersionPolicy assigns instances of the Microsoft.Rtc.Management.WritableConfig.Policy.ClientVersion.ClientVersionPolicy object to users or groups of users.


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

Copy Code
Grant-CsClientVersionPolicy -Identity "Ken Myer" -PolicyName "RedmondClientVersionPolicy"

In Example 1, the client version policy RedmondClientVersionPolicy is assigned to user Ken Myer. Note that, when specifying the policy to be assigned, you do not include the scope prefix (tag:, which you’ll see as output when you call Get-CsClientVersionPolicy). Thus the parameter value assigned to -PolicyName is RedmondClientVersionPolicy instead of tag:RedmondClientVersionPolicy.

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

Copy Code
Get-CsUser -LDAPFilter "l=Redmond" | Grant-CsClientVersionPolicy -PolicyName "RedmondClientVersionPolicy"

The command shown in Example 2 assigns the client version policy RedmondClientVersionPolicy to all the users who work in the city of Redmond. To do this, the command first uses Get-CsUser and the -LDAPFilter parameter to retrieve the appropriate collection of user accounts; the filter value "l=Redmond" limits data retrieval to users who work in the city (locality) of Redmond. This collection is then piped to Grant-CsClientVersionPolicy, which assigns the specified policy to each user in the collection.

-------------------------- Example 3 --------------------------

Copy Code
Get-CsUser -OU "ou=Redmond,ou=North America,dc=litwareinc,dc=com" | Grant-CsClientVersionPolicy -PolicyName "RedmondClientVersionPolicy"

In Example 3, the all the users in a specified OU are assigned the client version policy RedmondClientVersionPolicy. To accomplish this task, the command first calls Get-CsUser and the -OU parameter; the parameter value represents the distinguished name of the OU whose users are to be assigned the client version policy (ou=Redmond,ou=North America,dc=litwareinc,dc=com). After the user accounts have been retrieved, the collection is piped to Grant-CsClientVersionPolicy, which assigns RedmondClientVersionPolicy to each of those users.

-------------------------- Example 4 --------------------------

Copy Code
Get-CsUser -Filter {VoicePolicy -eq "RedmondVoicePolicy"} | Grant-CsClientVersionPolicy -PolicyName "RedmondClientVersionPolicy"

The preceding command assigns the client version policy RedmondClientVersionPolicy to all the users who have previously been assigned the voice policy RedmondVoicePolicy. To do this, the first thing the command does is call Get-CsUser and include the -Filter parameter; the filter value {VoicePolicy -eq "RedmondVoicePolicy"} ensures that the only user accounts returned are those where the VoicePolicy property is equal to (-eq) "RedmondVoicePolicy". (When using a policy in a filter value, you must, again, leave off the tag: prefix.) The resulting user accounts are then piped to Grant-CsClientVersionPolicy and assigned the client version policy RedmondClientVersionPolicy.

-------------------------- Example 5 --------------------------

Copy Code
Get-CsUser -Filter {VoicePolicy -ne "*"} | Grant-CsClientVersionPolicy

In Example 5, all the users who have not been specifically assigned a voice policy have their specifically-assigned client version policy removed as well. For example, suppose Ken Myer was not explicitly assigned a voice policy, but instead used a site or global voice policy. Suppose further that Ken Myer had been assigned the client version policy RedmondClientVersionPolicy. After this command finishes running, Ken will no longer use the RedmondClientVersionPolicy policy, but will instead use the client version policy for his site (if such a policy exists) or the global policy.

To do all that, the command first calls Get-CsUser and the -Filter parameter; the filter value {VoicePolicy -ne "*"} limits the returned data to user accounts where the VoicePolicy property is not equal to (-ne) a value of some kind. (The asterisk wildcard, used by itself, stands for "any specifically assigned client version policy". The resulting collection is then piped to Grant-CsClientVersionPolicy, which removes any client version policy specifically assigned to the user (that is, any policy at the per-user scope). Calling Grant-CsClientVersionPolicy without any parameters removes any client version per-user policy assigned to the user.