Topic Last Modified: 2011-02-01

Creates a new set of instant messaging (IM) archiving settings. These settings can be used to enable or disable the automatic saving of IM sessions; these settings also enable you to block any instant messages that cannot be archived.


New-CsArchivingConfiguration -Identity <XdsIdentity> [-ArchiveDuplicateMessages <$true | $false>] [-BlockOnArchiveFailure <$true | $false>] [-CachePurgingInterval <UInt32>] [-Confirm [<SwitchParameter>]] [-EnableArchiving <None | ImOnly | ImAndWebConf>] [-EnablePurging <$true | $false>] [-Force <SwitchParameter>] [-InMemory <SwitchParameter>] [-KeepArchivingDataForDays <UInt32>] [-PurgeExportedArchivesOnly <$true | $false>] [-PurgeHourOfDay <UInt32>] [-WhatIf [<SwitchParameter>]]


Parameter Required Type Description



Xds Identity

Unique identifier to be assigned to the new collection of archiving configuration settings. Because you can only create new collections at the site scope, the Identity will always be the prefix "site:" followed by the site name; for example "site:Redmond".




Specifies how cross-pool instant messages should be archived. For example, Ken Myer (with an account in Pool 1) sends an instant message to Pilar Ackerman (who has an account in Pool 2). Pilar, in turn, sends a reply to Ken’s instant message. If ArchiveDuplicateMessages is set to False, then (based on a built-in algorithm) the session transcript will be logged in either Pool 1 or Pool 2, but not both. If ArchiveDuplicateMessages is set to True (the default value), the transcript will be logged in both pools.




If True, then the IM service will be suspended any time your instant message sessions cannot be archived. If set to False (the default value), instant messaging will continue even if sessions cannot be archived.




Indicates how often (in hours) the system is purged of transcripts where none of the participants have been enabled for archiving. By design, all group IM sessions and conferencing sessions are recorded when they take place. At the specified interval, the system will determine whether any of the participants in these sessions have been enabled for archiving. If the system finds a session where none of the participants have been enabled for archiving, then that transcript will be deleted from the database.

The CachePurgeInterval property can be set to any integer value between 4 and 168, inclusive. The default value is 24.




Indicates which items (if any) are saved to the archiving database. Valid values are:

None. No items are archived to the database. This is the default value.

ImOnly. IM sessions are archived to the database.

ImAndWebConf. Both IM and web conferencing sessions are archived to the database.




If True, archived instant messages will periodically be removed from the database, provided that these instant messages: 1) are older than the value specified in the KeepArchivingDataForDays property; or, 2) have been exported and marked for deletion.

If False, instant messages will not be automatically deleted from the database.




Number of days (between 1 and 2562) that archived instant messages are kept in the database before being automatically deleted. The default value is 14.

This property takes effect only if EnablePurging has been set to True.




If True, then the system will only purge instant messages that have been exported (and, as a result, have been marked for deletion). Instant messages that have not been exported will remain in the database, even if those messages are older than the value specified by the KeepArchivingDataForDays property.




Indicates the time of day when expired records are deleted from the archiving database. The time of day is specified using a 24-hour clock, with 0 representing midnight (12:00 AM) and 23 representing 11:00 PM. Note that you can only specify the hour of the day. This means that you can schedule purging to take place at 4:00 AM, but you cannot schedule it to take place at, for instance, 4:30 AM or 4:15 AM. The default value is 2 (2:00 AM).

Database purging takes place only if the EnablePurging property is set to True.




Suppresses the display of any non-fatal error message that might arise when running the command.




Creates an object reference without actually committing the object as a permanent change. If you assign the output of this cmdlet called with this parameter to a variable, you can make changes to the properties of the object reference and then commit those changes by calling this cmdlet’s matching Set- cmdlet.




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




Prompts you for confirmation before executing the command.

Detailed Description

Many organizations find it useful to keep a transcript of all the IM sessions carried out by their users. For other organizations, it’s mandatory to keep such transcripts; for example, many organizations in the financial world are required by law to keep copies of all their electronic communications.

Microsoft Lync Server 2010 gives you flexibility when it comes to archiving IM and web conferencing sessions. If you have deployed Archiving Server, you can use the various CsArchivingConfiguration cmdlets to enable and disable IM session archiving and to manage your archiving database. You can also suspend IM should archiving fail; this helps to ensure that you keep a record of all your electronic communications.

When you install Lync Server 2010, a collection of global archiving settings will be created for you; by default, these settings will apply to your entire organization. Alternatively, you can use the New-CsArchivingConfiguration cmdlet to create custom configuration settings on a site-by-site basis.

Who can run this cmdlet: By default, members of the following groups are authorized to run the New-CsArchivingConfiguration cmdlet locally: RTCUniversalServerAdmins. 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 "New-CsArchivingConfiguration"}

Input Types

None. New-CsArchivingConfiguration does not accept pipelined input.

Return Types

New-CsArchivingConfiguration creates new instances of the Microsoft.Rtc.Management.WritableConfig.Settings.Archiving.ArchivingSettings object.


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

Copy Code
New-CsArchivingConfiguration -Identity site:Redmond -EnableArchiving "ImOnly"

The command shown in Example 1 creates a new collection of archiving configuration settings and applies these settings to the Redmond site. By adding the EnableArchiving parameter and setting the parameter value to "ImOnly", the command also enables IM session archiving (but not web conference archiving) for the Redmond site.

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

Copy Code
$x = New-CsArchivingConfiguration -Identity site:Redmond -InMemory
$x.EnableArchiving = "ImOnly"
Set-CsArchivingConfiguration -Instance $x

The preceding example demonstrates the use of the InMemory parameter to create a collection of archiving configuration settings that initially exist only in memory. To do this, the example creates a new collection of settings (with the Identity site:Redmond) and stores this collection in a variable named $x. Note that, after this first command runs, the collection exists only in memory; if you run the command Get-CsArchivingConfiguration you will not see an entry for site:Redmond.

In the second command, the EnableArchiving property for this virtual collection of settings is set to "ImOnly", which enables IM session archiving. Finally, the last command uses Set-CsArchivingConfiguration to transform the virtual archiving settings into an actual collection of settings applied to the Redmond site. If you do not call Set-CsArchivingConfiguration, these settings will remain in memory only and will disappear when your Windows PowerShell session is terminated or the variable $x is deleted.

See Also