Export and Import Retention Tags

  • Article

 

Applies to: Exchange Server 2010 SP3

There are several scenarios in which you may want to export or import retention tags, including:

  • Applying the same retention policies across all servers in a multi-forest Exchange organization

  • Applying the same retention policies in a hybrid deployment where some mailboxes reside in your on-premises Exchange organization and some reside in Exchange Online

  • Applying retention policies in an Exchange Online Archiving scenario, where users with on-premises Exchange 2010 mailboxes have a cloud-based archive

In these scenarios, the Managed Folder Assistant can correctly process an item that has a retention tag applied after the item or the mailbox is moved to another organization.

Note

To keep retention tags and retention policies synchronized between two organizations, every time you make changes to a retention tag or policy in the source organization, you must perform this procedure to export retention tags and policies from the source organization and import them in the destination organization.
You can’t select specific retention tags or policies to export. The Export-RetentionTags.ps1 script exports all retention tags and policies from an organization.

Looking for other management tasks related to messaging records management (MRM)? Check out Deploying Messaging Records Management.

Step 1: Export retention tags from an on-premises Exchange organization

You need to be assigned permissions before you can perform this procedure. To see what permissions you need, see the "Messaging records management" entry in the Messaging Policy and Compliance Permissions topic.

  1. Run this Exchange Management Shell command to change directory to the Scripts subdirectory in your Exchange installation path.

    Cd "<Exchange Server installation path>\Scripts"

  2. Important

    If you’re importing or exporting retention tags and retention policies to Exchange Online, you must connect your Windows PowerShell session to Exchange Online. For details, see Connect Windows PowerShell to the Service.

    Run the Export-RetentionTags.ps1 script to export retention tags to an .xml file.

      .\Export-RetentionTags.ps1 "c:\docs\ExportedRetentionTags.xml"

Step 2: Import retention tags to an on-premises Exchange organization

You need to be assigned permissions before you can perform this procedure. To see what permissions you need, see the "Messaging records management" entry in the Messaging Policy and Compliance Permissions topic.

  1. Run this Shell command to change the directory to the Scripts subdirectory in your Exchange 2010 installation path.

    Cd "<Exchange Server installation path>\Scripts"

  2. Run the Import-RetentionTags.ps1 script to import retention tags from a previously exported .xml file.

    Important

    If you’re importing or exporting retention tags and retention policies to Exchange Online, you must connect your Windows PowerShell session to Exchange Online. For details, see Connect Windows PowerShell to the Service.

    Note

    When running this script against Exchange Online, you may be prompted to confirm that you want to run software from an untrusted publisher. Verify that the name of the publisher appears as CN=Microsoft Corporation, OU=MOPR, O=Microsoft Corporation, L=Redmond, S=Washington, C=US, and then click R to allow the script to be run once or A to always run.

    .\Import-RetentionTags.ps1 "c:\docs\ExportedRetentionTags.xml"

  3. If the destination organization contains any retention tags or retention policies that aren’t found in the .xml file you’re importing, you’ll be prompted whether you want to delete them. If true synchronization of retention tags and retention policies between the source and destination organizations is desired, select the option to delete them. This makes sure both organizations contain the same retention tags and retention policies.

    Warning

    If you delete a retention policy in the destination organization that’s applied to mailbox users, you may receive additional prompts before deleting the policy. If you delete a retention policy that’s applied to mailbox users, those users will no longer have a retention policy applied. Depending on your organization’s compliance requirements, you should apply another retention policy to these users to avoid the risk of being out of compliance.

(Optional) Step 3: Import retention tags to an Exchange Online organization

If you have an Exchange hybrid organization and want to import retention tags and retention policies to Exchange Online, you have to edit the Import-RetentionTags.ps1 script. Specifically, you have to comment out the following lines in the script (by adding a '#' at the beginning of the line):

Lines 211-213

$tagExists.LabelForJournaling -eq $tag.LabelForJournaling -and
$tagExists.MessageClass -eq $tag.MessageClass -and
$tagExists.MessageFormatForJournaling -eq $tag.MessageFormatForJournaling -and

Lines 311-313

LabelForJournaling = $tag.LabelForJournaling
MessageClass = $tag.MessageClass
MessageFormatForJournaling = $tag.MessageFormatForJournaling

Here's an example of the Import-RetentionTags.ps1 script with these lines commented out.

Example of script with lines 211-213 and lines 311-313 commented out

Why do you have to comment out these lines? The Import-RetentionTags.ps1 script for Exchange 2010 calls the -MessageFormatForJournaling parameter for the New-RetentionPolicyTag cmdlet. This parameter isn't available in Exchange Online. If you don't comment out these lines, the script will fail and return a NamedParameterNotFound error.

After you edit the import script, follow the procedure in Step 2 to import the retention tags and retention policies to your Exchange Online organization.

Other Tasks

After you export and import retention tags, you may also want to:

 © 2010 Microsoft Corporation. All rights reserved.