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

Parameters

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

IM archiving policies (created using the New-CsArchivingPolicy cmdlet) can be assigned to the global site or to the site scope. In addition, these policies can be assigned to the per-user scope; that means that a policy can be created and then applied to a specific user or a set group of users. For example, you might have a global policy that archives internal IM sessions for all your users. In addition, you might create a second policy, one that archives both internal and external sessions. You could then choose to apply that policy only to your sales staff. Because per-user policies take precedence over global and site policies, members of the sale staff will have all their IM sessions archived. Other users (that is, users who are not part of the sales department and thus are not affected by the sales policy) will have only their internal IM sessions archived.

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

Grant-CsArchivingPolicy does not return a value or object. Instead, the cmdlet assigns instances of the Microsoft.Rtc.Management.WriteableConfig.Policy.IM.IMArchivingPolicy object to users or groups of users.

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

	Copy Code
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). Thus the policy tag:RedmondArchivingPolicy is denoted as RedmondArchivingPolicy.

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

	Copy Code
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 RedmondArchivingPolicy to each user in the collection.

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

	Copy Code
Get-CsUser -LDAPFilter "l=Redmond" | Grant-CsArchivingPolicy -PolicyName RedmondArchivingPolicy

The command shown in Example 3 assigns 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 world, l is short for "locality", or city.) This collection is then piped to Grant-CsArchivingPolicy, which, assigns RedmondArchivingPolicy to each of the users in the collection.

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

	Copy Code
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 homed on the registrar pool atl-cs-001.litwareinc.com. This is accomplished by using the Filter parameter and the filter value {RegistrarPool -eq "atl-cs-001-litwareinc.com"}. After the users have been returned, the entire collection is piped to Grant-CsArchivingPolicy, which assigns RedmondArchivingPolicy to each person in the collection.

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

	Copy Code
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 Communications Server; the Filter parameter and the filter value {ArchivingPolicy -eq "RedmondArchivingPolicy"} limit the returned data to accounts where the ArchivingPolicy is equal to (-eq) "RedmondArchivingPolicy". The filtered collection is then piped to Grant-CsArchivingPolicy, which assigns the policy NorthAmericaArchivingPolicy to each user in the collection.

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

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

Example 6 is a variation of Example 5; this time around, however, users who were previously assigned the policy RedmondArchivingPolicy is “unassigned” from users. Calling Grant-CsArchivingPolicy with a PolicyName equal to $Null removes any previously assigned per-user policies. Without a per-user policy assigned to them, users automatically inherit the site archiving policy if one exists. If a site policy doesn’t exist, users inherit the global policy.