Grant-CsArchivingPolicy

Syntax

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

Detailed Description

Many organizations find it useful to keep an archive of all the IM sessions that their users take part in; other organizations are legally required to keep such an archive. In order to archive IM sessions with Microsoft Lync Server 2010, you must perform two steps. First, you need to enable archiving at the global and/or the site scope by using the Set-CsArchivingConfiguration cmdlet. This gives you the ability to archive IM sessions; however, it does not automatically begin archiving those sessions.

To actually save transcripts of your IM sessions, you must complete step 2: create one or more IM session archiving policies. These policies determine which users will have their IM sessions recorded as well as which type of IM sessions (internal and/or external) will be archived. Internal IM sessions are sessions where all the participants are authenticated users who have Active Directory accounts within your organization. By comparison, external IM sessions are sessions where at least one participant is an unauthenticated user who does not have an Active Directory account within your organization. You can choose to archive only internal sessions, only external sessions, or both internal and external sessions.

Archiving policies can be assigned to the global scope or to the site scope. In addition, these policies can be assigned to the per-user scope and then applied to a specific user or a specific set of users. For example, suppose your global policy only archives only internal IM sessions. In that case, you might create a second policy, one that archives both internal and external sessions and apply that policy only to your sales staff. Because per-user policies take precedence over global and site policies, members of the sales staff will have all their IM sessions archived. Other users (users who are not part of the sales department and are not affected by the sales policy) will have only their internal IM sessions archived.

The Grant-CsArchivingPolicy cmdlet is used to assign per-user archiving policies to a user or specified set of users.

Who can run this cmdlet: By default, members of the following groups are authorized to run the Grant-CsArchivingPolicy cmdlet locally: RTCUniversalUserAdmins. To return a list of all the role-based access control (RBAC) roles this cmdlet has been assigned to (including any custom RBAC roles you have created yourself), run the following command from the Windows PowerShell prompt:

Get-CsAdminRole | Where-Object {$_.Cmdlets –match "Grant-CsArchivingPolicy"}

Parameters

Input Types

String value or Microsoft.Rtc.Management.ADConnect.Schema.ADUser object. Grant-CsArchivingPolicy accepts pipelined input of string values representing the Identity of a user account. The cmdlet also accepts pipelined input of user objects.

Return Types

Grant-CsArchivingPolicy does not return a value or object. Instead, the cmdlet assigns instances of the Microsoft.Rtc.Management.WritableConfig.Policy.IM.ImArchivingPolicy object to users or groups of users. However, if you include the PassThru parameter, the cmdlet will return instances of the Microsoft.Rtc.Management.ADConnect.Schema.OCSUserOrAppContact.

Example

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

Grant-CsArchivingPolicy -Identity "Ken Myer" -PolicyName RedmondArchivingPolicy

In Example 1, the archiving policy RedmondArchivingPolicy is assigned to the user with the display name "Ken Myer". Note that, with Grant-CsArchivingPolicy, the Identity property refers to the Identity of the user, not the Identity of the archiving policy. Instead, the policy to be assigned is specified by using the PolicyName parameter; the parameter value is the policy Identity (minus the "tag:" prefix).

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

Get-CsUser -OU "OU=Redmond,dc=litwareinc,dc=com" | Grant-CsArchivingPolicy -PolicyName RedmondArchivingPolicy

In the preceding command, all of the users with accounts in the Redmond organizational unit (OU) are assigned the archiving policy RedmondArchivingPolicy. To do this, Get-CsUser and the OU parameter are used to return a collection of all the users who have accounts in the OU with the distinguished name "OU=Redmond,dc=litwareinc,dc=com". This collection is then piped to Grant-CsArchivingPolicy, which assigns the policy RedmondArchivingPolicy to each user in the collection.

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

Get-CsUser -LdapFilter "l=Redmond" | Grant-CsArchivingPolicy -PolicyName RedmondArchivingPolicy

The command shown in Example 3 assigns the policy RedmondArchivingPolicy to all the users who work in Redmond. To carry out this task, Get-CsUser is called along with the LdapFilter parameter; the LDAP filter value "l=Redmond" returns a collection of all the users who work in the city of Redmond. (In the LDAP query language, l, a lowercase L, is short for "locality", or city.) This collection is then piped to Grant-CsArchivingPolicy, which assigns the RedmondArchivingPolicy policy to each user in the collection.

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

Get-CsUser -Filter {RegistrarPool -eq "atl-cs-001.litwareinc.com"} | Grant-CsArchivingPolicy -PolicyName RedmondArchivingPolicy

In Example 4 all the users homed on the Registrar pool atl-cs-001.litwareinc.com are assigned the policy RedmondArchivingPolicy. To do this, Get-CsUser is first used to return all the users who have been enabled for Lync Server. This collection is then piped to the Where-Object cmdlet, which selects only those users who have a RegistrarPool that is equal to atl-cs-001-litwareinc.com. This filtered collection is then piped to Grant-CsArchivingPolicy, which assigns the policy RedmondArchivingPolicy to each user in the collection.

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

Get-CsUser -Filter {ArchivingPolicy -eq "RedmondArchivingPolicy"} | Grant-CsArchivingPolicy -PolicyName "NorthAmericaArchivingPolicy"

Example 5 locates all the users who have been assigned the policy RedmondArchivingPolicy and then assigns each of these users a different policy: NorthAmericaArchivingPolicy. To perform this task, Get-CsUser is used to return a collection of all the users who have been enabled for Lync Server; the Filter parameter and the filter value {ArchivingPolicy -eq "RedmondArchivingPolicy"} limit the returned data to accounts where the ArchivingPolicy is equal to "RedmondArchivingPolicy". The filtered collection is then piped to Grant-CsArchivingPolicy, which assigns the policy NorthAmericaArchivingPolicy to each user in the collection.

-------------------------- Example 6 ------------------------

Get-CsUser -Filter {ArchivingPolicy -eq "RedmondArchivingPolicy"} | Grant-CsArchivingPolicy -PolicyName $Null

Example 6 is a variation of Example 5. This time, however, the policy RedmondArchivingPolicy is unassigned from all the users who were previously assigned that policy: calling Grant-CsArchivingPolicy with a PolicyName equal to $Null removes any previously assigned per-user policies.

See Also

Other Resources

Get-CsArchivingPolicy
New-CsArchivingPolicy
Remove-CsArchivingPolicy
Set-CsArchivingPolicy