This article is an end-to-end migration guide that helps you to perform a Microsoft 365 Teams to Teams migration using MigrationWiz. In this guide, you will find the step-by-step process for migrating teams, channels, conversations, permissions, and files.

MigrationWiz now supports migration for GCCH projects. For more information, please check the Microsoft Teams to Microsoft Teams Migration Guide for GCC High Migration guide.

MigrationWiz

MigrationWiz is a migration tool, rather than a syncing tool. If changes are made at the source after migration, they will not sync to the destination, nor will changes made at the destination sync to the source.
We do not have “live” monitoring of changes (as with a sync agent) and scenarios such as conflict resolution without user interaction are not supported. However, if versions and metadata are being migrated (see below for more details) the new versions of documents will be migrated with subsequent migration passes after the first.

First time?

We have created a guide on scoping, planning, and managing the migration process for your use. If this is your first migration, we recommend reading this guide carefully before beginning your migration process.

Prerequisites

When using MigrationWiz, it is important to understand the migration requirements for both the source and destination endpoints. Please ensure to meet them all:

• The migration service accounts for the source and destination endpoints must have a Global Admin role and be a member of the MigrationWiz security group.
• Use either Teams-ReadOnlyApp or MigrationWiz-Teams-FullControl for the Source and MigrationWiz-Teams-FullControl for the destination.

Licensing

This migration type requires the MigrationWiz-Collaboration (per Team) license type.

• Each license allows up to 100 GB of data to be migrated per license per team.
• If more than 100GB of data per team is being migrated, purchase enough licenses to cover the total amount of data being migrated. For example, if you have six teams and two of them have 200GB of data, you will need to purchase 8 licenses.
• Each license is applied to a single team and expires 12 months after its purchase date.

Limitations

Check the information below before performing this type of migration. 

• We are not able to support migrations with two-factor or multifactor authentication.
• App password usage, MFA/2FA, and ADFS are not supported for the migration admin account/service account being used by this endpoint.
• The maximum file size for migration through MigrationWiz varies by migration type and environment, but may never exceed 60GB.
• The Teams-ReadOnlyApp does not support migrating document permissions.
• Image and managed metadata migration is not supported.

For more information on special case migrations, frequently asked questions, and other information, see Microsoft Teams Migration FAQs and Teams Troubleshooting & Error Lookup.

Migrating Teams for Education Templates

MigrationWiz can assist with Microsoft Teams for Education migration (Classroom template only, including Classroom Notebook). We currently do not support the migration of Notebooks for Teams based on PLC or Staff templates.

Planner

MigrationWiz allows you to migrate the planner content, check out our Planner guide for more information and limitations about this migration. Steps to migrate Planner are included below.

Versions & Metadata

Migrationwiz supports up to 25 migrated versions (including both minor and major versions), including the current version. Before starting the migration, configure the appropriate number of versions to be migrated in the advanced options, please see more information below. 

For more information regarding this topic refer to the Versions and Metadata Migration for Microsoft Teams, SharePoint, and OneDrive article.

Migrated Items

Please click the bars below to check the migrated and non-migrated items. We are constantly working to create a better migration experience for you, so these items may change over time.

Prepare your Source and Destination Environments

Verify to grant the requested permissions mentioned below.

• Consent app access at the Source by using Teams-ReadOnlyApp or MigrationWiz-Teams-FullControl permission level.
• Consent app access at the destination by using MigrationWiz-Teams-FullControl permission level.
  Tip
  If you are migrating 'Document Permissions', you must use MigrationWiz-Teams-FullControl for both Source and Destination tenants.
• When creating the endpoints, enter the new user credentials.

Perform the steps 1 to 3 for both Source and Destination:

1. Create a new Security Group named MigrationWiz on the Office 365 Admin Portal. If you have not created a security group before, follow Microsoft's instructions.
2. Create a new user. This user must have an active Teams license applied and must be on a cloud-only account.

   Important

   On-premises and hybrid user account types are not supported.

3. Add the new (or existing) user to the previously created security group as a Member (Adding as an Owner will not work here).

   Important

   ADFS and MFA must be turned off for this user.

MigrationWiz Steps

Create a Collaboration Project

1. Go to Projects.
2. Click Create Project.
3. Select Collaboration Project.
4. Update the project information: add a Project Name, select a Customer from the drop-down, then click Next Step.
5. Create your endpoints.

Endpoints

The steps in this section outline how to create the endpoints in MigrationWiz. Consider only ten endpoints will be shown when selecting an existing endpoint. If you have more than ten, you may need to search it in the search box.

Endpoint search is case and character-specific. For example, Cust0mer will not show up if the search is customer. We recommend keeping a list of endpoints you have created with any unique spellings or capitalization you may have used.

Create your Endpoints

Please review the following tabs to create your destination and source endpoints.

Verify that both, the source and destination endpoints, are Microsoft Teams. Variable endpoints are not supported.

For the following step, credentials are mandatory. Ensure all the mandatory fields are filled to activate the Update button. Click this once all the steps above are completed.

Region of Destination Tenant

The Region of Destination Tenant feature optimizes the migration performance and speed by choosing the region closest to the destination tenant. MigrationWiz displays a dropdown that allows you to select the destination region when configuring your destination endpoint. 

Using a Custom Azure Storage

If you want to use your own Azure storage, please follow the steps below:

1. Prepare Azure Environment.
2. Estimate Azure storage costs. This step is optional but is useful to provide the customer with upfront storage costs ahead of time. For more information, see Estimate Azure Storage costs for migrations.
3. Buy an Azure subscription. You can also use the free one-month trial but be aware that this option is only viable if you are performing a small migration.
4. See How to create Azure StorageV2 storage for destination endpoints to create your storage account.
   You will need to set up a STORAGE (General Purpose v2) account rather than a storage blob. Take note of the storage account name and the primary access key. (In Azure, from the storage screen, click Manage Access Keys at the bottom of the screen.) These need to be entered into the MigrationWiz migration project when specifying the destination settings.
   We recommend you create your Azure storage account in the same Microsoft data center as the destination Office 365 tenant. There is no need to create any Azure containers for this migration.
5. The access key information is the following:
   • accesskey – This is the Storage account name for the Blob – example “accountname”
   • -secretkey - This is the access key for the Storage account – example “W1RrDfkPNkfYfdVqizMNJjn5mXchwMP5uYBY8MsMqWTA7EubG911+4fZlki0Gag==”

UPN Prefix Changes

User mapping: By default, we match users from the source to the destination based on the prefix in their User Principle Name (UPN). For example, if the user UPN is “name@domain.com”, we match the “name” portion.

If you are facing one of the next two scenarios:

• There are multiple people with the same prefix at the destination (e.g. name@domain1.com and name@domain2.com)
• The prefix of a particular user is changed in the destination (e.g. name@source.com → name.full@destination.com)

You must use the advanced option UserMapping="name@source.com->full.name@destination.com" to set the new or correct name for each user.

The User Mapping command goes into the Support Options section and will require one line per user that needs mapping. Click the + to add additional lines. Replace the UPN addresses in the example with the actual UPN addresses.

Add Teams

There are three ways to add teams to the migration. Either of these may be used, or both. Read through each of the options before beginning your process.

Follow the Autodiscover process to find all the teams you are migrating, and then select either Quick Add or Bulk Add.

Generally, Quick Add will be used for small migrations, proof of concept migrations, and other tests, while Bulk Add will be used for large migrations and full migration passes. The Team names added to the project use the mail nickname only.

Advanced Options

Support Tab

• ForceSharePointOnlineEnvironment=1 By default, the Teams endpoint for SharePoint documents will migrate to tenant.sharepoint.com. However, the files will not migrate properly if you have a custom SharePoint domain. By setting this advanced option, MigrationWiz will be notified that you are using SharePoint Online, even though the actual domain does not include sharepoint.com in the name.
• TeamsMaxConversationMessage=XXX Limits the number of conversations to load in the source tenant. E.g. TeamsMaxConversationMessage=1000 would only load 1000 messages
• TeamsMaxConversationPostPerTeam=XXX Increase the number of conversation threads that will be posted to the channel. Minimum of 0 and maximum 1000. By default, the number of conversations will be 60.

  Important

  Setting a higher limit will harm the migration time, as each message post takes 0.5 seconds to post.

Source/Destination Tab

In case you want to migrate file versions, it is mandatory to set the Document versions to migrate (including the current version) text box, you can migrate up to 25 versions.

Keep in mind that the number of document versions to migrate cannot be changed after performing a migration, so please configure it during the project creation.

Start Migration

Recommended Migration Steps

For each batch of up to 200 teams, the migration process consists of four passes:

1. Initial 'Scaffolding' Pass to create the Teams and public channels in the destination tenant.
2. Data Migration Pass to copy the SharePoint data from the source Teams to the destination Teams. Private channels are created in this pass.
3. Channel Tabs Migration Pass to copy tabs data into the various Teams Channels.
4. Teams and Channel Membership, Planner, and Conversations Migration Pass to copy the Teams and Channel memberships. Planner and Teams Channel conversations are recommended to be migrated in this pass as well

Perform the four tasks in that order allowing about an hour between each one (after the Teams Creation pass) to ensure that the migration has 'settled' and is ready for future data ingestion.

Pass One: Initial 'Scaffolding' Pass

When starting the migration select the 'Teams Creation' as shown here.

Pass Two: Data Migration Pass

Start the migration using the options shown here.

Pass Three: Channel Tabs Migration Pass

After at least one round of data migration has been performed, this pass will migrate the data inside the various Channel Tabs that are in the Teams. Select these options.

Pass Four: Teams and Channel Membership, Planner, and Conversations Migration Pass

The final pass is to add the users into the Teams and Channels along with the Conversations and Planner data. Select the options below to complete the final step.

Teams and channel membership migrations are performed at last to prevent users from receiving excessive email notifications about Teams migration events during a multi-pass migration. This step also includes the Conversations migration, as this pass is a 'run once', meaning subsequent migration passes will not sync updates to previously migrated Conversations. It is recommended to run the Conversations migration as the final pass, to ensure they appear correctly in the target Teams.

Resolve Errors

Errors vary widely, so if you encounter migration errors, refer to the Collaboration error list and follow the steps listed under Resolution.

If a migration completes successfully but not all members show on the Teams destination, the users may be taking extra time to sync.

This can happen when a Team has a large number of users. It is possible to verify that all the users were migrated by logging into the Microsoft 365 Admin portal, going to the migrated group (Team), and viewing the member's list to verify that the expected number of members were migrated. This should be synced to the Teams interface within the next few hours.

Post Migration

Once the migration has finished, remove the Microsoft 365 user account created for the migration, as well as the MigrationWiz Security Group

Once the migration has finished, remove the Microsoft 365 user account created for the migration, as well as the MigrationWiz Security Group You will also need to remove the Azure app using these steps:

1. Launch PowerShell.
2. Connect PowerShell to Microsoft 365.
3. Enter the command: Connect-AzureAD
4. Enter the admin credential in the prompt.
5. Enter the command: Get-AzureADServicePrincipal -SearchString Migration
6. Look for the ObjectId of the app you want to remove and enter the following command: Remove-AzureADServicePrincipal -objectId <the object id>

Special Circumstances

Migrating to Another Team in the Same Tenant

It is recommended to create the destination Teams manually. If you choose MigrationWiz to create the Team, they will have the same display name as the source Team, regardless of the mail nickname entered for the destination Team in the project, which will create duplicate Team display names in the tenant.

Then, you must add the support option AllowInternalMigration=1 to the advanced option of the project. Without this support option, the migration may fail with the following error:

Cannot migrate to a destination mailbox equal to the source mailbox.

Migrating Channel Conversations

MigrationWiz migrates 60 messages (60 root messages + all replies) per team by default.

Besides, MigrationWiz gathers the total number of channels in each team and then grabs the most recent 60 threads in each team. The conversations will be distributed across those channels. For example, if you have six channels in a team, you will have ten message threads per channel.

The entire channel conversation history can also be downloaded as HTML in the ‘Conversation History’ tab.

The total number of messages to be migrated can be increased via this Advanced Option:

• TeamsMaxConversationPostPerTeam=XX Replace XX with the number of messages you wish to migrate.
  For example, TeamsMaxConversationPostPerTeam=1000 would load 1000 messages per team.
  This may slow your migration, so plan when using this function.

Channel Tabs migration

MigrationWiz supports the migration of some channel tabs as part of a Teams to Teams migration. No Government (GCC High) tenant tabs are migrated. This includes tabs in public channels, private channels, 1:1 chats, group chats, and meeting chats.

This item can be selected in the Start Migration flyout window:

1. Go to Start Migration.
2. Select Migrate Data.
3. Select Channel tabs item type.

The following tabs will be migrated by default if the Channel tabs option is selected:

• OneNote
• Microsoft Word
• Excel
• PowerPoint
• PDF
• Websites (Links for the site will only work in the Teams app and not Teams on the web. This is a Microsoft limitation)

Tabs migration is an additional pass after a migration pass for Documents has been successfully completed first, following the same behavior as the previous OneNote tab migration option.

Once the migration is successful, all tabs should be fully rehydrated at Teams destination tenant and all links should be correctly remapped (only for Channels).

Migrated tabs will also be reflected in the Folder Summary section under the relevant team/channel.

Migrated Items will also show the total number of tabs migrated:

All emailed project statistics will now also include the tab data.

Important

Channel tabs cannot be migrated independently without migrating Documents.

Limitations

Tabs

• If the OneNote associated with the tab is not stored in the specified team, the OneNote tab will not be created at the destination. A warning message will be shown. This may be due to a changed personal OneDrive URL or a lack of visibility into other teams and their migration status.
• After migration, the OneNote tab will show the first page of the section by default.

• Tabs for EDU and Govt tenants are not yet supported. This includes public channels, private channels, 1:1 chats, group chats, and meeting chats.

• Public channel tabs linking to any location outside the team's main document library will not be migrated.

• Private channel tabs linking to any location outside the private channel or the team's main document library will not be migrated.

• Website tabs are not supported for Teams on the web/browser. Only supported on Teams desktop application. (This is a Microsoft limitation)

Notebooks

Three scenarios may apply during the migration of a team’s default OneNote notebook (present in the SiteAssets document library of the team’s SP site) while migrating teams:

• Scenario 1: Migrating to a new team that does not exist in the destination
  The source team’s default notebook is migrated as it is and appears as the default notebook in the destination after the migration is complete.
• Scenario 2 - Migrating to an existing team with the same display name as the source (note that mailNickname is not in question here since the default notebook’s display name does not follow the mailNickname)
  The source team’s default notebook is migrated into the already existing default notebook in the destination.
  However, if for some reason the destination team’s default notebook was not provisioned (or does not exist at all) due to some Microsoft limitation, the source team’s default notebook will still be migrated and the migrated notebook will appear as a default notebook in the destination.
• Scenario 3 - Migrating to an existing team with a different display name as the source (note that mailNickname is not in question here since the default notebook’s display name does not follow the mailNickname)
  The source team’s default notebook and the destination team’s default notebook will be auto-mapped. This means that contents in the source team’s default notebook will be automatically migrated to the destination team’s default notebook even though their names are different without the need for any manual mapping from the user. (The reason for the difference in the names of the default notebooks is that the naming convention for the team’s default notebook follows the display name of the team).
  However, when the destination team’s default notebook has not been provisioned (or does not exist for some reason) due to some Microsoft limitations, the source notebook will be migrated as-is without any mapping and the migrated notebook will not appear as a default notebook in the destination.

Migrated Items

In the following tabs, you can check the migrated and non-migrated items when selecting the Channel Tabs checkbox.

Migrating Tabs

This should be done as part of the migration process. It is included separately as it is not a required part of a Teams migration.

Warning
Word, Excel, and PowerPoint tabs are currently unable to be migrated due to Microsoft Graph API calls update

MigrationWiz Steps

1. Ensure the MigrationWiz User has already consented to either Teams-ReadOnlyApp or MigrationWiz-Teams-FullControl.
2. Log in to MigrationWiz.
3. Create a Teams Collaboration project.
4. Required endpoints: Microsoft Teams (Source) and Microsoft Teams (Destination).
5. Start adding Teams via Autodiscover, Quick Add, or Bulk Add.
6. Select which teams to migrate.
7. Click Start Migration for a ‘Teams Creation’ pass first.
8. Wait 24 hours for the Teams to provision.

Advanced Options

TeamsMigrateChannelTabs=1
This Advanced Option is only required for projects that are created before October 6, 2021, to enable migration of Microsoft Word, Excel, PowerPoint, PDF, and Website tabs.

Migrating Teams with Special Characters in the Name

This section is specific to migrations utilizing Autodiscover. If any team names have special characters, such as emoji icons, Excel may not be able to open the generated CSV file. The steps below may allow the CSV file to be imported with these special characters.

Once Autodiscover has been completed:

1. Download the CSV generated by the Autodiscover process.
2. Open Excel and import the data using Data--> Import External Data--> Import Data.
3. Select the file type csv and browse to your file.
4. In the Excel import wizard, change the File_Origin to 65001 UTF (or choose the correct language character identifier).
5. Change the delimiter to a comma.
6. Select the location to import to CSV and click Finish.
   • While these steps should work for most versions of Excel, some versions may still not be able to open the CSV.
7. Navigate back to MigrationWiz.
8. Upload the edited CSV via the Bulk Add function.
9. Click Start Full Migration.
10. When the migration is complete, verify that the users can see their teams and channels in the Destination tenant.
11. Click the bar chart icon in the MigrationWiz dashboard to request an email that contains the project migration statistics.

Related Topics

For more information regarding this topic, you can check the following pages:

• Versions and Metadata Migration for Microsoft Teams, SharePoint, and OneDrive
• Teams to Teams Migrations - Migrating Planner Content
• Microsoft Teams Migration - Document Versions and Metadata FAQs
• Microsoft Teams Migration - Tabs FAQs
• Teams Troubleshooting & Error Lookup