Microsoft Exchange 2010 PowerShell Cookbook

Manage and maintain your Microsoft Exchange 2010 environment with the Exchange Management Shell and Windows PowerShell 2.0 using this book and eBook

The reader will benefit from referring two previous articles: Troubleshooting Mailboxes and Reporting on Mailbox

Performing some basic steps

To work with the code samples in this article, follow these steps to launch the Exchange Management Shell:

1. Log onto a workstation or server with the Exchange Management Tools installed.
2. Open the Exchange Management Shell by clicking on Start | All Programs | Exchange Server 2010.
3. Click on the Exchange Management Shell shortcut.

Importing and exporting mailboxes

If you have worked with Exchange for a long time, you have probably used utilities such as ExMerge or the Exchange 2007 Management Shell to import and export data between mailboxes and PST files. While these tools were useful for their time, they had some limitations. For example, ExMerge was the main import and export utility starting with Exchange 5.5 and continuing on to Exchange 2003, but it was difficult to automate. Exchange 2007 included the Import-Mailbox and Export-Mailbox cmdlets th at made it easier to automate these tasks through PowerShell scripts. Unfortunately, the Export-Mailbox cmdlet required both a 32-bit workstation running the 32-bit version of the Exchange 2007 Management tools and Microsoft Outlook 2003 SP2 or later.

With the release of Exchange 2010 SP1, we have a new set of cmdlets that can be used to manage the import and export operations for Exchange mailboxes. These new cmdlets have no dependencies on a management workstation and there is no requirement to install Outlook to perform these tasks. The Mailbox Replication Service (MRS) that runs on the Client Access Server (CAS) role introduces a new concept called mailbox import and export requests that implements this functionality as a server-side process. In this recipe, you will learn how to configure your environment and use these cmdlets to automate mailbox import and export requests.

How to do it…

1. Let’s start off by exporting a mailbox to a PST ? le. First, you need to add an RBAC role assignment for your account. Assign the Mailbox Import Export role to your account using the following command. You will need to restart the shell after running this command in order for the assigned cmdlets to be visible:

   New-ManagementRoleAssignment -Role “Mailbox Import Export” `
   -User administrator

2. Next, you will need to create a network share that can be used to store the PST file. When you create the share, make sure that the Exchange Trusted Subsystem group in Active Directory has at least read/write NTFS permissions on the folder, and also has at least modify share permissions.
3. The last step is to use the New-MailboxExportRequest cmdlet to export the data for a mailbox, using the following syntax:

   New-MailboxExportRequest -Mailbox testuser `
   -Filepath contoso-ex01exporttestuser.pst

How it works…

By default, the built-in Mailbox Import Export role is not assigned to anyone, including the administrators. This means that, out of the box, you will not be able to run the *-MailboxExportRequest cmdlets, even if you are a member of the Organization Management role group. Therefore, the ? rst step in the process is to assign your account to this role using the New-ManagementRoleAssignment cmdlet. I n the previous example, you can see that we created a direct assignment to the administrator’s user account. This can be your administrative account, or an actual role group that you are already a member of. If needed, you can specify that the role be assigned to a role group or an Active Directory security group using the -SecurityGroup parameter.

The location used for imported and exported PSTs must be a valid UNC path that the Exchange Trusted Subsystem group has access to. This is because the cmdlets that you execute are actually running under the security context of the Exchange servers in this group group. This is required to implement the new RBAC security model, and, therefore, the Share and NTFS permissions must be assigned to this group and not your user account specifically.

The syntax for the import and export commands is fairly straightforward. Looking at the command used in the previous example, you can see that we were able to easily create an export request for a specified mailbox using a specific file share on the network.

Using additional parameters, we can do other interesting things, such as only exporting specific folders of a mailbox to a PST:

New-MailboxExportRequest -Mailbox testuser `
-IncludeFolders “Sent Items” `
-FilePath contoso-ex01exporttestuser_sent.pst `
-ExcludeDumpster

As you can see from the command, we are only exporting the Sent Items folder from the testuser mailbox and we are excluding the items in the dumpster.

Here is another example that exports data from an archive mailbox:

New-MailboxExportRequest -Mailbox testuser `
-ContentFilter {Received -lt “09/01/2010”} `
-FilePath contoso-ex01exporttestuser_archive.pst `
-ExcludeDumpster `
-IsArchive

Here we are specifying that we want to only export data from the archive mailbox by using the -IsArchive switch parameter . In addition, we are limiting the amount of data exported from the mailbox using the -ContentFilter parameter . We are only including items that were received before 09/01/2010. In addition to the Received property, the -ContentFilter parameter allows you to highly customize the data that is exported.

You can create upto 10 mailbox export requests per mailbox without manually specifying a name for the export request. Once you have reached this limit, you either need to specify a unique name for the export request, or delete some of the previous export requests using the Remove-MailboxExportRequest cmdlet.

Using the -ContentFilter parameter, you can filter the recipient, types of attachments that were included in a message, text in the body, and more. For a complete list of available property names, check out the Filterable Properties for the -ContentFilter Parameter on TechNet at the following URL:

http://technet.microsoft.com/en-us/library/ff601762.aspx

There’s more…

You can use the Get-MailboxImportRequest and Get-MailboxExportRequest cmdlets to view the status of your import and export tasks. To view all requests, simply run the appropriate Get-* cmdlet . If you want to narrow your search, you can use the -Mailbox and -Status parameters:

Get-MailboxExportRequest -Mailbox testuser -Status Failed

This command will return all of the export requests made for the testuser mailbox that have a failed status. You can use the same syntax with the import version of this cmdlet to review similar information.

 

When it comes to advanced reporting of import or export requests, there are two cmdlets available that you can use. Get-MailboxExportRequestStatistics and Get-MailboxImportRequestStatistics can be used to provide detailed information about the tasks associated with a particular operation. For example, take a look at the following script:

foreach($i in Get-MailboxExportRequest) {
Get-MailboxExportRequestStatistics $i |
select-object SourceAlias,Status,PercentComplete
}

This will provide a brief report for each export request. This can be useful when you are performing multiple import or export operations and need to check the status of each one.

Importing data into mailboxes

The New-MailboxImportRequest cmdlet works similarly to the New-MailboxExportRequest cmdlet. Most of the parameters shown in the previous examples are available with both cmdlets. For example, we can import data into a specific folder in an inbox with the following command:

New-MailboxImportRequest -Mailbox sysadmin `
-IncludeFolders “Sent Items” `
-FilePath contoso-ex01exporttestuser_sent.pst

This command imports the testuser PST into the Sent Items folder of the sysadmin mailbox. In addition to exporting data from archive mailboxes, we can also import data into archive mailboxes with the -IsArchive switch parameter.

Taking it a step further

Let’s create a script that will export all of the mailboxes in your organization to individual PST files stored in a central location. Create a new file called Export.ps1 and save it in the C: drive. Using a text editor, open the file and add the following code, and then save the file:

param($Path, $BatchName)
foreach($i in Get-Mailbox -ResultSize Unlimited) {
$filepath = Join-Path -Path $Path -ChildPath “$($_.alias).pst”
New-MailboxExportRequest -Mailbox $i `
-FilePath $filepath `
-BatchName $BatchName
}

This script provides a couple of parameters used to control the behavior of the mailbox export requests. First, the -Path parameter will allow us to specify a UNC share for our exported mailboxes. Secondly, the -BatchName parameter is used to logically group the export requests using a friendly common name.

As we loop through each mailbox, we are doing a few things. We are using the value of the -Path parameter as the root directory for the PST file, and we are using the alias of the mailbox for the base filename. This will ensure that each PST file is stored centrally in the required location using a unique filename that matches the mailbox alias. To execute the preceding script, the command might look something like this:

$batch = “Export for (Get-Date).ToShortDateString()”
.Export.ps1 -Path contosoex01export -BatchName$batch

This will create each mailbox export request using a batch name such as Export for 10/26/2010. Then you can easily check the status of all the mailbox export requests that are grouped into that batch name using the following command:

Get-MailboxExportRequestStatistics |
?{$_.BatchName -eq “Export for 10/26/2010”} |
select SourceAlias,Status,PercentComplete

This one-liner will give you a brief report on each of the export requests performed in the batch created on 10/26/2010 that can be reviewed in the shell, exported to a text or CSV file, or e-mailed to another user.