Creates a new client version policy. Client version policies enable you to specify which "downlevel "clients (such as Office Communicator 2007 R2) will be able to log onto your Microsoft Communications Server system. If you do not wish to allow a particular client to use the system then you can create a policy that will prevent people using that client from logging on.
Syntax
New-CsClientVersionPolicy -Identity <XdsIdentity> [-Confirm [<SwitchParameter>]] [-Description <String>] [-Force <SwitchParameter>] [-InMemory <SwitchParameter>] [-Rules <PSListModifier>] [-WhatIf [<SwitchParameter>]] |
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
|
Identity |
Optional |
Unique identifier for the policy to be returned. To return the global policy, use this syntax: -Identity global. To return a policy configured at the site scope use syntax similar to this: -Identity "site:Redmond". To return a policy configured at the service scope use syntax like this: -Identity "service:Redmond-Registrar-1". The Registrar service is the only service that can host a client version policy. Policies can also be configured at the per-user (tag) scope. To return one of these policies, simply leave off the scope portion of the Identity. For example, the policy tag:SalesDepartmentPolicy would be referenced like this: -Identity "SalesDepartmentPolicy". If this parameter is not included then all the client version policies configured for use in your organization will be returned. |
|
|
Rules |
Optional |
PS List Modifier |
Collection of client version policy rules. Rules are most-easily added and removed from a policy by using the New-CsClientVersionPolicyRule and the Remove-CsClientVersionPolicyRule cmdlets. To add a new rule at the time you create the new policy, first create the rule and store the value in a variable (for example, $x). Then use syntax similar to this when creating the new policy: New-CsClientVersionPolicy –Identity "RedmondClientVersionPolicy" –Rules @{Add=$x} |
|
Description |
Optional |
String |
|
|
InMemory |
Optional |
Switch Parameter |
Creates an object reference without actually committing the object as a permanent change. If the output of the cmdlet is not assigned to a variable, the object will be lost and nothing will be created. |
|
Force |
Optional |
Switch Parameter |
|
|
WhatIf |
Optional |
Switch Parameter |
Describes what would happen if you executed the command without actually executing the command. |
|
Confirm |
Optional |
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.
New client version policies are created using the New-CsClientVersionPolicy cmdlet. These new policies can be created at the site scope, the service scope (Registrar service only), or at the per-user scope. (Although a global policy is created when you install Communications Server, you cannot create a new global policy. However, you can modify the global policy.) Note that policies at the site and service scope must be unique. For example, suppose you try to create a new client version policy for the Redmond site. If the Redmond site already hosts a client version policy, then your command will fail.
Return Types
New-CsClientVersionPolicy creates new instances of the Microsoft.Rtc.Management.WritableConfig.Policy.ClientVersion.ClientVersionPolicy object.
Examples
-------------------------- Example 1 --------------------------
 Copy Code |
|
|---|---|
New-CsClientVersionPolicy -Identity site:Redmond |
|
In Example 1, a new client version policy is created for the Redmond site. Because no parameters are specified (other than the mandatory -Identity parameter) the new policy will contain all the default values (that is, all the default rules) for a client version policy.
-------------------------- Example 2 --------------------------
| Copy Code |
|
|---|---|
Get-CsSite | Select-Object Identity | ForEach-Object {New-CsClientVersionPolicy -Identity ("site:" + $_.Identity)}
|
|
The command shown in Example 2 creates a new client version policy for each site in the organization. To accomplish this task, the command first calls Get-CsSite without any additional parameters; that returns a collection of all the sites in the topology. That collection of sites is then then piped to the Select-Object cmdlet, which extracts the Identity property (and only the Identity property) for each site. This collection of Identities is then piped to New-CsClientVersionPolicy, which creates a new client version policy for each Identity (that is, each site) in the collection. The Identity for each new policy is created by combining the string value "site:" with the actual name of the site; thus the Redmond site’s client version policy will be given the Identity site:Redmond.