Use batch migration process to migrate Exchange on-premises public folders to Microsoft 365 Groups

  • Article

Through a process known as batch migration, you can move some or all of your Exchange on-premises public folders to Microsoft 365 Groups. Groups offer certain advantages over public folders. For more information about Microsoft 365 Groups, see Migrate your public folders to Microsoft 365 Groups.

This article contains the step-by-step procedures for migrating your Exchange on-premises public folders to Microsoft 365 Groups.

What do you need to know before you begin?

Verify that you meet all of the following conditions as you prepare your migration:

  • We recommend that you read this article in its entirety, as downtime is required for some steps.

  • Public folders must be hosted on:

    Exchange Version Minimum CU/Service pack
    Exchange Server 2013 CU15 or later
    Exchange Server 2016 CU4 or later
    Exchange Server 2019 RTM or later

  • In Exchange Online, you need to be a member of the Organization Management role group. This role group is different from the permissions that are assigned to you when you subscribe to Microsoft 365, Office 365, or Exchange Online. For more information about how to enable the Organization Management role group, see Manage role groups.

  • In Exchange on-premises, you need to be a member of the Organization Management or Server Management RBAC role groups. For more information, see Add Members to a Role Group.

  • We recommend that you move user mailboxes to Microsoft 365 or Office 365 for those users who need access to Microsoft 365 Groups.

  • For Exchange Server 2013 or later versions: MRS Proxy needs to be enabled on at least one Exchange server, and that server must also host public folder mailboxes. For more information, see Enable the MRS Proxy endpoint for remote moves.

  • You can't use the Exchange admin center (EAC) to do the procedures in this article. On Exchange server, you need to use the Exchange Management Shell. In Exchange Online, you need to use Exchange Online PowerShell. For more information, see Connect to Exchange Online PowerShell.

  • You can only migrate Calendar public folders and Mail public folders to Microsoft 365 Groups. Migrating other types of public folders isn't supported. Also, the target Groups need to exist in Microsoft 365 or Office 365 before the migration.

  • The batch migration process copies only messages and calendar items from public folders to Microsoft 365 Groups. It doesn't copy other properties that are associated with the public folder (for example, policies, rules, and permissions).

  • Microsoft 365 Groups come with a 50-GB mailbox. Verify that public folder data to be migrated is less than 50 GB. Leave extra storage space for future content. The maximum size that we recommend for public folder migration is 25 GB.

  • This migration isn't "all or nothing." You can pick and choose specific public folders to migrate. Subfolders of public folders aren't automatically included in the migration. You need to explicitly include any subfolders that you want to migrate. The migration allows you to map a maximum of two subfolders to a single Microsoft 365 Group mailbox.

  • During the migration, existing public folders aren't modified or otherwise affected by the migration. After you do the steps in the Step 6: Lock the public folders (downtime required) section, users must use the target Microsoft 365 Groups instead of the original public folders that were migrated.

  • You can create multiple migration batches to migrate public folders to groups.

  • If you're using Microsoft Entra Connect (Microsoft Entra Connect) to synchronize your on-premises directories with Microsoft Entra ID, you need to perform the following steps (if you aren't using Microsoft Entra Connect, you can skip this step):

    • On an on-premises computer, open Microsoft Entra Connect, and then select Configure.
    • On the Additional tasks screen, select Customize synchronization options, and then select Next.
    • On the Connect to Microsoft Entra ID screen, enter the appropriate credentials, and then select Next. Once connected, keep selecting Next until you're on the Optional Features screen.
    • Ensure that Exchange Mail Public Folders isn't selected. If it isn't selected, you can continue to the next section, Prerequisite steps in Exchange Online. If it's selected, then select to clear the check box, and then select Next.

    Note

    If you don't see Exchange Mail Public Folders as an option on the Optional Features screen, you can exit Microsoft Entra Connect and proceed to the next section, Prerequisite steps in Exchange Online.

    • After you've cleared the Exchange Mail Public Folders selection, keep selecting Next until you're on the Ready to configure screen, and then select Configure.

Step 1: Get the scripts

The batch migration to Microsoft 365 groups requires running many scripts at different points in the migration. Download the scripts and their supporting files from this location. After you download all of the scripts and files, save them to the same location, that is, c:\PFtoGroups\Scripts.

Before you proceed, verify that you downloaded and saved the following scripts and files:

Note

Be sure to save all scripts and files to the same location.

  • AddMembersToGroups.ps1: Adds members and owners to Microsoft 365 Groups based on permissions on the source public folders.

  • AddMembersToGroups.strings.psd1: A support file used by the AddMembersToGroups.ps1 script.

  • LockAndSavePublicFolderProperties.ps1. Makes public folders read-only to prevent modifications during the migration. Transfers the mail-related public folder properties, and redirects mail sent to migrated mail-enabled public folders to the target Groups. Backs up the permission entries and the mail properties before modifying them.

  • LockAndSavePublicFolderProperties.strings.psd1: A support file used by the LockAndSavePublicFolderProperties.ps1 script.

  • UnlockAndRestorePublicFolderProperties.ps1: Restores access rights and mail properties of the public folders using backup files that are created by LockandSavePublicFolderProperties.ps1.

  • UnlockAndRestorePublicFolderProperties.strings.psd1: A support file used by the UnlockAndRestorePublicFolderProperties.ps1 script.

  • WriteLog.ps1: Enables the preceding three scripts to write logs.

  • RetryScriptBlock.ps1. Enables the AddMembersToGroups, LockAndSavePublicFolderProperties, and UnlockAndRestorePublicFolderProperties scripts to retry certain actions if there are transient errors.

For details about AddMembersToGroups.ps1, LockAndSavePublicFolderProperties.ps1, and UnlockAndRestorePublicFolderProperties.ps1, see Migration scripts later in this article.

Step 2: Prepare for the migration

The following steps are required to prepare your organization for the migration:

  1. Make a list of Mail public folders and Calender public folders that you want to migrate to Microsoft 365 Groups.

  2. Make a list of the target Microsoft 365 Groups for each migrated public folder. You can create new Groups or use existing Groups.

    If the permission of the public folder is set to Author or above, the target Microsoft 365 Group should have the Public privacy setting. However, users will still need to join the Group to see the public group under the Groups node in Outlook.

    For more information, see Learn about Microsoft 365 Groups.

  3. Rename any public folders that contain a backslash (\) in the name. Otherwise, those public folders may not get migrated correctly.

  4. The migration feature named PAW must be enabled for your Microsoft 365 or Office 365 organization. To verify that PAW is enabled, run the following command in Exchange Online PowerShell:

    Get-MigrationConfig

    If the output of the Features property contains the value PAW, the feature is enabled, and you can continue to Step 3: Create the .csv file.

    Existing public folder migration batches or user migration batches in any state will prevent PAW from being enabled. Complete and remove any existing migration batches until no results are returned by the Get-MigrationBatch cmdlet. The removal of existing migrations isn't immediately reflected in the output of Get-MigrationConfig cmdlet.

    After you remove all existing batches, PAW should automatically enable itself.

    After you complete this step, you can create new user migration batches.

Step 3: Create the .csv file

Create a .csv file that will provide input for one of the migration scripts.

The .csv file needs the following columns:

  • FolderPath: Path of the public folder to be migrated.

  • TargetGroupMailbox: SMTP address of the target Microsoft 365 Group. You can run the following command to see the primary SMTP address.

    Get-UnifiedGroup -Identity <alias of the group> | Format-Table PrimarySmtpAddress

An example .csv contains the following information:

"FolderPath","TargetGroupMailbox"
"\Sales","sales@contoso.onmicrosoft.com"
"\Sales\APAC","apacsales@contoso.onmicrosoft.com"
"\Sales\EMEA","emeasales@contoso.onmicrosoft.com"

You can merge a Mail public folder and a Calendar public folder into the same Microsoft 365 Group. Otherwise, a single migration batch doesn't support any other scenarios for merging multiple public folders into the same Group. Run multiple migration batches one after another to map multiple public folders to the same Microsoft 365 Group. You can have up to 500 entries in each migration batch.

Step 4: Start the migration request

In this step, you gather information from your Exchange environment, and then you use that information in Exchange Online PowerShell to create a migration batch. After that, you start the migration.

  1. On the Exchange server, find the MRS proxy server endpoint. You'll need this information later when you run the migration request.

  2. In Exchange Online PowerShell, use the information from the previous step to run the following commands. The variables in these commands will be the values from the previous step.

    • Store the credentials of an on-premises Exchange administrator in the variable named $Source_Credential.

      $Source_Credential = Get-Credential

      Enter the username in the format: <source_domain>\<Account>.

    • Use the MRS proxy server information from your Exchange Server environment as described in the previous step, and save that value to the variable named $Source_RemoteServer.

      $Source_RemoteServer = "<MRS proxy endpoint>"

  3. In Exchange Online PowerShell, run the following command to create a migration endpoint:

    $PfEndpoint = New-MigrationEndpoint -PublicFolderToUnifiedGroup -Name PFToGroupEndpoint -RemoteServer $Source_RemoteServer -Credentials $Source_Credential

  4. Run the following command to create a new public folder to Microsoft 365 Group migration batch:

    New-MigrationBatch -Name PublicFolderToGroupMigration -CSVData ([System.IO.File]::ReadAllBytes('<path to .csv file>')) -PublicFolderToUnifiedGroup -SourceEndpoint  $PfEndpoint.Identity [-NotificationEmails <email addresses for migration notifications>] [-AutoStart]
    • CSVData: The .csv file previously created in Step 3: Create the .csv file. Ensure you use the full path to this file. If you moved the file, ensure you use the new location.
    • NotificationEmails: An optional parameter that sets the email addresses for notifications about the status and progress of the migration.
    • AutoStart: An optional switch that starts the migration batch as soon as you create it.
    • PublicFolderToUnifiedGroup: Indicates a public folder to Microsoft 365 Groups migration.

  5. This step is required only if you didn't use the AutoStart switch in the previous command.

    Start the migration by running the following command in Exchange Online PowerShell:

    Start-MigrationBatch PublicFolderToGroupMigration

Although you create the migration in Exchange Online PowerShell, you can view and manage the migration in the Exchange admin center (EAC) in Exchange Online on the Migration page.

In Exchange Online PowerShell, you view the progress of the migration with the Get-MigrationBatch and Get-MigrationUser cmdlets.

To view the Migration page in the EAC, do the following steps:

  1. In the EAC at https://admin.exchange.microsoft.com, go the Recipients > Migration.

  2. Select the migration request.

  3. In the Details pane, select View Details.

When the batch status is Completed, you can continue to Step 5: Add members to Microsoft 365 groups from public folders.

Step 5: Add members to Microsoft 365 groups from public folders

Add members to the target Microsoft 365 Group. To add members to the group based on the public folder's permission entries, you need to run the AddMembersToGroups.ps1 script on the Exchange server as described in this section.

You need to synchronize user mailboxes to Exchange Online to add members to the Microsoft 365 group based on permission entries. To see which public folder permissions are eligible, see the Migration scripts section later in this article.

.\AddMembersToGroups.ps1 -MappingCsv <path to .csv file> -BackupDir "<path to backup directory>" -ArePublicFoldersOnPremises $true

Note

Provide your Microsoft 365 tenant administrator credentials when prompted for.

  • MappingCsv: The .csv file that you created in Step 3: Create the .csv file. Ensure you provide the full path to this file. If you moved the file, ensure you use the new location.
  • BackupDir: The folder where the migration log files are stored.
  • ArePublicFoldersOnPremises: Indicates whether public folders are located in Exchange server or in Exchange Online.
  • Credential: The Exchange Online username and password.

After you add users to a Microsoft 365 Group, they can use it.

Step 6: Lock the public folders (downtime required)

After you've migrated most of the public folder data to Microsoft 365 Groups, you can run the LockAndSavePublicFolderProperties.ps1 script on the Exchange server. This step ensures that no new data is added to public folders before the migration has completed.

Note

For mail-enabled pubic folders, the script copies some properties to the target Microsoft 365 Groups (for example, email addresses) and then mail-disables the mail-enabled public folders. After you run the script, mail that is sent to those public folders is redirected to the target Microsoft 365 Groups. For more information, see the Migration scripts section later in this article.

.\LockAndSavePublicFolderProperties.ps1 -MappingCsv <path to .csv file> -BackupDir "<path to backup directory>" -ArePublicFoldersOnPremises $true

Note

Provide your Microsoft 365 tenant administrator credentials when prompted for.

  • MappingCsv: The .csv file that you created in Step 3: Create the .csv file. Ensure you provide the full path to this file. If you moved the file, ensure you use the new location.
  • BackupDir: The folder where the backup files for permission entries, mail-enabled public folder properties, and migration log files are stored. You can use these backup files if you need to roll back to public folders.
  • ArePublicFoldersOnPremises: Indicates whether public folders are located in Exchange server or in Exchange Online.
  • Credential: The Exchange Online username and password.

Step 7: Finalize the public folder to Microsoft 365 Groups migration

After you've made your public folders read-only, you need to perform the migration again. This step is required for a final incremental copy of your data.

  1. Before you run the migration again, you need to remove the existing batch migration by running the following command:

    Remove-MigrationBatch -Identity "<name of migration batch>"

  2. Create a new batch with the same .csv file by running the following command:

    New-MigrationBatch -Name PublicFolderToGroupMigration -CSVData ([System.IO.File]::ReadAllBytes('<path to .csv file>')) -PublicFolderToUnifiedGroup -SourceEndpoint $PfEndpoint.Identity [-NotificationEmails <email addresses for migration notifications>] [-AutoStart]
    • CSVData: The .csv file that you created in Step 3: Create the .csv file. Ensure to provide the full path to this file. If you moved the file, ensure to use the new location.
    • NotificationEmails: An optional parameter that sets the email addresses for notifications about the status and progress of the migration.
    • AutoStart: An optional switch that starts the migration batch as soon as you create it.

  3. This step is required only if you didn't use the AutoStart switch in the previous command.

    Start the migration by running the following command in Exchange Online PowerShell:

    Start-MigrationBatch PublicFolderToGroupMigration

When the status value of the migration batch is Completed, verify that all data has been copied to Microsoft 365 Groups. At that point, if you're satisfied with the Microsoft 365 Groups experience, you can begin deleting the migrated public folders from your Exchange Server environment.

Important

While there are supported procedures for rolling back your migration and returning to public folders, roll-back isn't possible after you delete the source public folders. For more information, see the How do I roll back to public folders from Microsoft 365 Groups? section in this article.

Known issues

The following known issues can occur during a typical public folder to Microsoft 365 Groups migration:

  • The script that transfers email addresses from mail-enabled public folders to Microsoft 365 Groups adds the primary email address of the public folder as secondary email address on the Microsoft 365 group. Exchange Online Protection (EOP) or Centralized Mail Flow might have issues sending email to the secondary email address of Microsoft 365 Groups after the migration.

  • If the public folder path entry in the .csv mapping file is invalid, no more data is copied after the invalid entry, but the status of the migration batch will be Completed.

Migration scripts

For your reference, this section provides in-depth descriptions for three of the migration scripts and the tasks they execute in your Exchange environment. You can download all scripts and supporting files from this location.

AddMembersToGroups.ps1

The AddMembersToGroups.ps1 script reads the permissions of public folders and adds members and owners to Microsoft 365 groups as described in the following list:

  • Users with the following permission roles on the public folder are added as members to the Microsoft 365 Group:

    Owner, PublishingEditor, Editor, PublishingAuthor, Author

  • Users with the following minimum access rights on the public folder are also to be added as members of the Microsoft 365 Group:

    ReadItems, CreateItems, FolderVisible, EditOwnedItems, DeleteOwnedItems

  • Users with access right "Owner" on the public folder are added as owners of the Microsoft 365 Group. Users with other eligible access rights are added as members.

  • You can't add security groups as members of Microsoft 365 Groups. Instead, the group membership list is expanded, and the individual users are added as members or owners on the Microsoft 365 Groups based on their access rights as previously described.

  • If a user has access rights on a public folder from both individual permission assignment and security group membership, the individual permissions are given preference.

    For example, the security group named "SG1" has members User1 and User2. The public folder named "PF1" has the following permission entries:

    • SG1: Author on PF1
    • User1: Owner on PF1

    In this example, User1 is added as an owner to the Microsoft 365 Group.

  • When the default permission of a public folder is 'Author' or above, the script suggests the value 'Public' for the privacy setting of the target Microsoft 365 Group'.

  • If you already ran the LockAndSavePublicFolderProperties.ps1 script, you can still run the AddMembersToGroups.ps1 script by using the parameter and value -ArePublicFoldersLocked $true. In this scenario, the script reads the permissions from the backup file that was created during lockdown.

LockAndSavePublicFolderProperties.ps1

The LockAndSavePublicFolderProperties.ps1 script takes the following actions:

  1. Migrated mail-enabled public folders are mail-disabled, and their email addresses are added to the corresponding Microsoft 365 groups.

  2. Permission entries on the migrated public folders are modified to make them read-only.

  3. Mail properties of mail-enabled public folders and the permission entries of all the public folders are copied before any modifications are made.

If there are multiple migration batches, you should use a separate backup directory with each mapping .csv file.

The following mail properties are stored for mail-enabled public folders and their corresponding Microsoft 365 groups:

  • PrimarySMTPAddress
  • EmailAddresses
  • ExternalEmailAddress
  • EmailAddressPolicyEnabled
  • GrantSendOnBehalfTo
  • SendAs Trustee list

These mail properties are stored in a .csv file, which you can use if you want to roll back the migration as described in the How do I roll back to public folders from Microsoft 365 Groups? section later in this topic.

A snapshot of mail-enabled public folder properties is also stored in a file named PfMailProperties.csv. This file isn't necessary for rollback, but you can use it for reference.

The following mail properties are migrated from public folders to Microsoft 365 groups by the LockAndSavePublicFolderProperties.ps1 script:

  • PrimarySMTPAddress
  • EmailAddresses
  • SendAs Trustee list
  • GrantSendOnBehalfTo

The script ensures that the PrimarySMTPAddress and EmailAddresses values of mail-enabled public folders are added as secondary email addresses on the corresponding Microsoft 365 Groups. Also, SendAs and SendOnBehalfTo permissions of users on mail-enabled public folders are given equivalent permissions in the corresponding target Groups.

If you get the following error when running LockAndSavePublicFolderProperties.ps1 script, follow the steps specified in Proxy address conflict when adding an email address in Exchange Online:

The smtp address is being used by another group in your organization. Please try a different smtp address.

Access rights allowed

Only the following access rights are allowed for users. This change ensures that public folders are read-only for all users:

  • ReadItems
  • CreateSubfolders
  • FolderContact
  • FolderVisible

These access rights are stored in the ListOfAccessRightsAllowed property. Permission entries are modified as described in the following table:

Before lockdown After lockdown
None None
AvailabilityOnly AvailabilityOnly
LimitedDetails LimitedDetails
Contributor FolderVisible
Reviewer ReadItems, FolderVisible
NonEditingAuthor ReadItems, FolderVisible
Author ReadItems, FolderVisible
Editor ReadItems, FolderVisible
PublishingAuthor ReadItems, CreateSubfolders, FolderVisible
PublishingEditor ReadItems, CreateSubfolders, FolderVisible
Owner ReadItems, CreateSubfolders, FolderContact, FolderVisible

  • Access rights for users without read permissions are untouched, and they'll continue to be blocked from read rights.

  • For users with custom roles, any access rights that aren't specified in ListOfAccessRightsAllowed will be removed. Users who have only access rights that aren't specified in ListOfAccessRightsAllowed after filtering will have their access rights set to the value None.

There might be an interruption in sending an email to mail-enabled public folders during the time when the folders are mail-disabled and the email addresses are added to Microsoft 365 Groups.

UnlockAndRestorePublicFolderProperties.ps1

The UnlockAndRestorePublicFolderProperties.ps1 script reassigns permissions back to public folders based on the backup that you took during the public folder lockdown. The script also mail-enables public folders that were mail-disabled. This action happens after the email addresses are removed from the corresponding Microsoft 365 Groups. There might be a slight downtime during this process.

How do I roll back to public folders from Microsoft 365 Groups?

If you change your mind and want to return to using public folders, you can roll back the migration, as long as the following conditions are met:

  • The backup files still exist.
  • You didn't delete the public folders after the migration.

On your Exchange server, run the following command to restore your environment to the pre-migration state:

.\UnlockAndRestorePublicFolderProperties.ps1 -BackupDir <path to backup directory> -ArePublicFoldersOnPremises $true -Credential (Get-Credential)

Note

Provide your Microsoft 365 tenant administrator credentials when prompted for.

  • BackupDir: The directory where the backup files for permission entries, mail-enabled public folder properties, and migration log files are stored. Confirm that this directory is the same location from Step 6: Lock the public folders (downtime required).
  • ArePublicFoldersOnPremises: Indicates whether public folders are located on-premises or in Exchange Online.

Any added items or edit operations to the Microsoft 365 Groups aren't copied back to public folders. In these scenarios, there will be data loss.

You can't restore a subset of public folders. All migrated public folders will be restored.

The corresponding Microsoft 365 Groups aren't deleted as part of the rollback process. You need to remove these Groups manually.