Troubleshoot public folder batch migrations

Applies to: Exchange Server 2013

Summary: This article contains steps you can take to troubleshoot a batch migration of Exchange public folders.

During batch migrations of public folders from older versions of Exchange to Exchange 2013 or Office 365, some common issues may arise. The information in this article is intended to help you identify and troubleshoot those issues, in order to clear the way for a successful batch migration.

The following areas are discussed and, where applicable, basic steps are outlined to verify or correct the issue:

• Find the information you need to begin troubleshooting a batch migration

• Failure to mail-enable public folders

• Finalization of the migration process

• Mailboxes serving hierarchy after migration

• Running more jobs in parallel

• Analyzing bad items

What do you need to now before you begin?

• Estimated time to complete this task: Varies, depending on type of migration issues

• You need to be assigned permissions before you can perform this procedure or procedures. To see what permissions you need, see the "Public folders" entry in the Sharing and collaboration permissions topic.

• For information about keyboard shortcuts that may apply to the procedures in this topic, see Keyboard shortcuts in the Exchange admin center.

What do you want to do?

Find the information you need to begin troubleshooting a batch migration

Batch migration data is distributed across different places, making it harder to collect and diagnose issues than the old centralized serial migration. When a batch migration request is created, all information is stored in messages that are created under the organization (migration) mailbox. The information about batch migrations that is displayed in the EAC comes from the migration mailbox. You can find the database the mailbox is located in by running:

Get-Mailbox -Arbitration -Organization $org Mig* | fl Name,Database

Next, you can run Get-MailboxDatabaseCopyStatus to determine the server in which that mailbox database is mounted.

The migration service runs under MSExchangeServiceHost on the server in question and is responsible for creating, resuming, suspending, and removing MRS jobs that are part of the batch migration request.

When the batch migration request begins with New-PublicFolderMailboxMigrationRequest cmdlet, it creates the job items and their underlying MRS jobs. Each MRS job is stored in the System mailbox of the database hosting the target mailbox for that job. Like any other MRS job, their data are available via Get-*Request and Get-*RequestStatistics cmdlets.

From the migration mailbox, you can gather information about:

• Endpoints, or connectivity settings for the batch request.

• Batch metadata, including information from the .csv file generated by the batch migration scripts, limits for bad items and large items, as well as a summary of the batch request health and its current status.

• Job item information. There is a 1:1 mapping between a job item and an MRS job. Job items are constantly updated based on snapshots you take by running New-PublicFolderMailboxMigrationRequest.

• Reports, which emails sent out about the different phases of a batch migration.

Run the following commands to find the migration user and the corresponding MRS job targeting the primary mailbox:

$primaryMailboxGuid = (Get-OrganizationConfig $org).RootPublicFolderMailbox.HierarchyMailboxGuid

$primaryMailboxUser = $users | ?{$_.MailboxGuid -eq $primaryMailboxGuid}

$primaryMailboxJob = Get-PublicFolderMailboxMigrationRequest "$org\$($primaryMailboxUser.RequestGuid)"

Run the following commands to get high-level details of job status:

$primaryMailboxUserStats = $primaryMailboxUser | Get-MigrationUserStatistics -Organization $org

$primaryMailboxUserStats | fl Status,Error

You can get even more information by using Get-*Statistics.

For detailed syntax and parameter information, see the following topics:

• Get-Mailbox

• Get-PublicFolderDatabase

• Get-PublicFolderMailboxMigrationRequest

• Get-PublicFolderMigrationRequestStatistics

Troubleshoot failure to main-enable public folders

A failure to mail-enable public folders during a migration usually indicates one of two things.

• Active Directory objects are not correctly synchronized between the on-premises environment and Office 365.

• After initial synchronisation, some of the public folders in Active Directory in Office 365 aren't linked to any storage folders.

In both cases the recovery method is to run the Sync-MailPublicFolders script.

Troubleshoot finalization of the migration process

Before finalization, the state of the batch migration should be Synced. If it is SyncedWithErrors, you should run the Start-MigrationBatch command before proceeding. Start-MigrationBatch will only resume, or retry, the jobs that failed, while the Complete-MigrationBatch command will resume all jobs. Start-MigrationBatch gives you the opportunity to fix the failed jobs, and verify if the fix was effective, before proceeding with finalization. Proceeding to finalization without trying to fix the errors isn't recommended, as those same errors could abort the entire migration.

The following diagram illustrates the transition order of batch migration status during a successful finalization.

And this is how the status of individual job items should flow:

Similarly, on the MRS side, this job status should transition this way:

If any individual job fails during one of the green phases in the above two illustrations, the migration process will retry a couple of times. If the failures continue, a report will be emailed to the administrator and the batch migration process will return to the SyncedWithErrors state.

When you begin finalization of the batch migration, the migration service will resume all jobs, which includes ensuring that each one performs one successful incremental synchronization. This is done after the source is locked in order to prevent data loss. If all MRS jobs reach the AutoSuspended state again, it means they were successful and finalization will continue. The Exchange Online/Office 365 public folder deployment is unlocked. Then, all jobs will be resumed one last time, so that they can perform cleanup tasks until they finally reach a Completed state. Once all individual jobs are in the Completed state, the status for the entire batch migration will also change to Completed.

Troubleshoot mailboxes serving hierarchy after migration

...

....the only situation the customer would need to set IsExcludedFromServingHierarchy=true is when they want to make that one mailbox a content only mailbox (i.e. not serve the hierarchy to any user). Also, during migration, we expect to have PublicFoldersEnabled=Remote, which will prevent AutoD from assigning local PF mailboxes to serve the hierarchy to users on O365. In fact, in this case, AutoD would be directing these users to the on-premises PF databases. However, during finalization, the source is locked, which means a downtime for those users. The only exception for this rule is manually assigning a local PF mailbox to a O365 user, which the procedure recommended to test if the migration was successful (step 8.1), before switching to PublicFoldersEnabled=Local.

.....

Increase the number of jobs that can run in parallel

You can run the following command to increase the default concurrency settings for a batch migration:

Set-MigrationEndpoint PublicFolderEndpoint -MaxConcurrentMigrations 88 -MaxConcurrentIncrementalSyncs 88

The above example is setting the default number to 88. Next, by entering Run Start-MigrationBatch, will resume all 88 jobs in parallel.

Analyze corrupted items

Corrupted, or "bad," items prevent successful migrations.

Here is how you find the underlying migration user and corresponding MRS job targeting the primary mailbox:

$primaryMailboxGuid = (Get-OrganizationConfig $org).RootPublicFolderMailbox.HierarchyMailboxGuid

$primaryMailboxUser = $users | ?{$_.MailboxGuid -eq $primaryMailboxGuid}

$primaryMailboxJob = Get-PublicFolderMailboxMigrationRequest "$org\$($primaryMailboxUser.RequestGuid)"

The above example will return some information about the user or job in question. It is possible to get more granular details by using the Get-*Statistics cmdlet, like in the following example:

$primaryMailboxUserStats = $primaryMailboxUser | Get-MigrationUserStatistics -Organization $org

$primaryMailboxUserStats | fl Status,Error

Common issues

MigrationPermanentException. Error: This mailbox exceeded the maximum number of corrupted items that were specified for this move request

This error indicates that public folders were mail-enabled successfully, but the job failed because of too many corrupted items. You can analyze the corrupted items with a report from the MRS job, or by running Get-MigrationUserStatistics.