2 ways to migrate Microsoft Teams from one tenant to another

Trying to migrate Teams resources from one tenant to another? We explain two ways to tackle your Microsoft Teams migration—ensuring users have everything they need to succeed in their new Teams environment.

Thinking about migrating SharePoint sites? Check out how the ShareGate SharePoint Migration tool compares to Microsoft’s SPMT

Microsoft Teams has become central to the Microsoft 365 user experience—with new and improved features, an easy-to-use interface, and seamless integration with other Microsoft tools.

With the content created in Teams now more valuable than ever, the ability to migrate this data as needed is no longer a nice-to-have; in the context of a merger or acquisition, it’s a critical process to ensure our workflows also transition with us seamlessly.

Here at ShareGate, we’re well-known for our SharePoint migration tool. And since Teams lives in the same Microsoft 365 ecosystem, we’ve gotten a lot of questions from our customers about how to migrate their Teams environment to a new tenant, as well.

We’ve done a lot of research in the process of developing a Microsoft Teams migration feature as part of ShareGate Migrate, so we decided to share what we learned with you! When it comes to migrating your Teams environment from one tenant to another, you have two basic options.

Microsoft Teams migration: Why it’s a challenge

The crux of the problem stems from the fact that most Teams data isn’t stored in Teams; it’s actually stored in the following locations:

• SharePoint team site: Files and folders stored in the team document library or shared in a channel, external emails sent to the team, the team’s wiki page, and each channel’s OneNote assets.
• Exchange team mailbox: Group chat and channel chat conversation history, team mail, and contacts.
• Exchange mailboxes of individual users: Private (1:1) chat conversation history, voicemails, and calendar meetings.
• OneDrive for Business of individual users: Files attached to private chat sessions, or a chat during a meeting or call, are uploaded and stored in the OneDrive account of the user who shared the files.
• OneDrive organizational document library: Users’ personal OneNotes.
• Azure (using Blob storage): Images and media (except for GIFs) shared in chats.
• Stream: Meeting recordings.
• Third-party storage provider: If your organization allows users to store files with a third-party storage provider, either through tabs or other partner apps, that information is stored directly in the system used by the partner.

This data sprawl, paired with a lack of publicly available APIs from Microsoft, make it impossible to migrate Teams automatically using Microsoft’s out-of-the-box solutions.

Related event: Put your M365 migration in full throttle

Option #1: Migrate Microsoft Teams from one tenant to another manually

Migrating Microsoft Teams data to another tenant manually involves multiple steps and a ton of heavy lifting on the part of IT.

Technically, there’s no easy, out-of-the-box way to migrate Microsoft Teams between Microsoft 365 tenants. But you can move some of the underlying components, such as the files stored on the associated team SharePoint site and group chat and channel conversation history stored in the team’s Exchange mailbox.

While there are a few different ways you can go about doing this, we’re going to walk you through one of the most straightforward methods that doesn’t involve any third-party tools.

To migrate your Microsoft Teams to another tenant manually, you need to:

1. Re-create the teams you want to migrate at the destination
2. Add all of the correct users and permissions to each team
3. Download the contents of the associated SharePoint team sites and upload at the destination
4. Export conversations from the team’s Exchange mailbox, then import them at the destination as a document

Step #1: Re-create the teams you want to migrate at the destination

Before you copy any Teams content, you need to create teams in your new Teams environment so that content has a destination.

Essentially, this means re-creating the structure of your source Teams—including the channels and tabs within each team. Sound time consuming? That’s because it is. But you’re only getting started.

Step #2: Add all of the correct users and permissions to each team

Once you have the scaffolding set up in your new Teams environment, you need to populate it properly. That means adding all of the correct users and permissions to each team.

Assuming you followed migration best practice, you should already have all your users added at the destination Azure Active Directory. So what you’re really doing in this step is inviting users to join the same teams they were members of in the old Teams environment.

To invite bulk users to a Microsoft Teams team, you need to:

1. Extract users/permissions to a CSV file
2. Modify the domains associated with each user
3. Add users to the destination teams from the CSV file
4. Modify permissions within each team

Extract users/permissions to a CSV file

The first thing you need to do is generate a list of details about your existing Microsoft Teams. There’s no way to do this using Microsoft tools, so hopefully you’re comfortable with scripting!

To export details about all of the teams in your source tenant, you can run a slightly modified version of this PowerShell script.

When we ran the script as is, it didn’t return any of the channel information. But we found that it worked perfectly if you simply change “Groups” to “teams” in line 22 (between “beta/” and “/$id):

$team = Invoke-RestMethod -Headers @{Authorization = "Bearer $accesstoken"} -Uri https://graph.microsoft.com/beta/teams/$id/channels -Method Get

When prompted, be sure to sign in with your source tenant credentials.

Run the modified script in PowerShell.

The resulting CSV file includes the following information for each team:

• Team name
• Team type
• Number of channels
• Channel names
• Team owner
• Team member count
• Team members

The resulting CSV file should look something like this.

Modify the domains associated with each user

Now it’s time to get creative! In order to map your existing team membership at the destination tenant, we need to change the old domain name to the new domain name in the CSV file.

Using the Find and Replace features in Excel (or whatever app you’re using to view the CSV file), change the old domain name that appears after each username to the destination domain name.

Replace the domain name in all of the user email addresses.

Add users to the destination Teams from the CSV file

Now that you have your modified CSV file, you’re going to use PowerShell (again) to upload/invite those users to your newly created teams.

Running the PowerShell script outlined in this blog post will allow you to add multiple users from a CSV file to a Microsoft Teams team.

First you need to connect to your destination Microsoft Teams so that you can run the commands to add users. You can do so by running the following command:

Connect-MicrosoftTeams

Sign in with your credentials (email and password) associated with your new Microsoft Teams environment.

Once connected, run the following command to generate a list of all your teams and their associated group IDs:

Get-Team

Note the GroupID next to the name of each team.

This method only allows you to add users in bulk to one team at a time. So now you need to go back to your modified CSV file and:

1. Copy the user emails from the “Members” column for an individual team.
2. Create a new CSV file and input the user emails in one email column, with one user email per line. Save as a CSV file.
3. Repeat for every team.

New CSV file with members of the HR team.

Back in PowerShell, run the following command to invite all of the users in a CSV file to the new team. (Input the team’s group ID where it says YOUR_TEAM_ID in the script, and replace YOUR_FILE_PATH with the file path to the CSV file with that team’s list of users.)

Import-Csv -Path "YOUR_FILE_PATH" | foreach{Add-TeamUser -GroupId YOUR_TEAM_ID -user $_.email}

If all goes well and the users are added correctly, you shouldn’t see any messaging after running the script. Continue with running the script again for each of your new teams.

When you’re finished, you should see all of the users you added in the corresponding teams in the Teams app and the Microsoft Teams admin center:

Members added to teams at the destination Teams admin center.

Modify permissions within each team

If everything has gone smoothly up until this point, congratulations! You can move onto the last step (of this step): manually promoting the correct members to owners within each team.

Your modified CSV file—that one that includes the details of all your teams and has multiple columns—has an “Owners” column. Use the user emails in that column to manually identify and add the same owners to all of your new teams.

Restored permissions visible in Microsoft Teams app.

Step #3: Download the contents of the associated SharePoint team sites and upload at the destination

With the structure and membership of your teams successfully copied, the next step is to copy the contents of those teams—all of the content mentioned above that’s actually stored in a team’s associated SharePoint site.

Because we’re performing a tenant to tenant migration, you can’t simply reorganize that content with SharePoint’s built-in “Copy” and “Move” features—that would only work if you were trying to move content to another team site within the same tenant.

To move SharePoint content from one tenant to another manually, you’re going to have to download it from the source tenant and upload it at the destination.

At the very least, you should do this with the contents of each team’s “General” folder in SharePoint. This folder stores the contents of the “Files” tab visible in Microsoft Teams—in order to get users up and running in their new Teams environment as quickly as possible, you definitely want to move this content as part of your initial Teams migration.

Simply navigate to each team’s SharePoint site, select the contents of the “General” folder, and click the Download button at the top of the user interface.

Download the files from the source team site…

When you created your new teams at the destination Teams, an associated SharePoint team site was automatically provisioned for each team. Once you’ve downloaded the documents from the source tenant, navigate to the corresponding team site at the destination tenant and upload that content to the “General” folder there.

…and upload at the corresponding destination site.

Not only is this method time-consuming, but it will only work for the files and folders within a SharePoint team site’s document library; you won’t be able to download/upload entire SharePoint pages or lists.

It’s also worth noting that you’ll also lose all of the metadata associated with those files along the way. And if your library uses versioning, you’ll only get the latest version—none of your previous versions will be moved over.

Related: Learn how to use SharePoint Online, avoid common issues & best practices with Microsoft MVPs

Step #4: Export/import Teams chat history

As mentioned above, group chat and channel chat conversation history lives in each team’s Exchange mailbox. To access this data you’re going to have to turn to PowerShell (again!).

Verify the GroupMailbox and TeamChat contents with PowerShell

In PowerShell, connect to your source Teams tenant and run the following command to generate a list of all the group mailboxes:

Get-mailbox -GroupMailbox | select Displayname, WindowsEmailAddress

To view the details of the mailbox folders for a specific team, use the corresponding WindowsEmailAddress and run this command:

Get-mailbox -groupmailbox Team@mycompany.com | Get-
MailboxFolderStatistics | select Foldertype,ItemsInFolder

You should be able to view the item size of the TeamChat folder from the output. Repeat this step for every team you want to migrate to verify each team’s contents.

Export each team’s TeamChat data

Now head over to your source tenant’s Security and Compliance center and run a search for the contents of one of the teams you want to migrate.

• Navigate to the Content search page and create a Guided search. Input a name for your search, something like “HR conversation history”.

• Choose the related Teams group as the location and add a condition of Type > Equals any of and select E-mail messages and Instant messages, then save and run your query.

• When your query has finished running, in the More drop-down menu click on Export report.
• Choose one of the All items export options, then click on Download report.

• Once the report has been exported, open it in a compatible client to view and save the team’s chat history. To make the conversation history viewable for team members, save it as a document and upload it to the “General” folder in the team’s associated SharePoint site (that way it will be visible in the team’s “File” tab in Microsoft Teams).
• Repeat for every team you want to migrate.

While this manual migration method lets you bulk-add members to the destination teams and move over a team’s group chat and channel conversation history, it’s extremely time-consuming—involving multiple steps, some of which need to be repeated for each team.

Obviously, trying to migrate Microsoft Teams manually is not an ideal situation for an organization’s IT team.

Option #2: ShareGate’s migration tool for Teams and SharePoint

Migrating existing Teams resources and data is more crucial than ever, especially in the context of a merger or acquisition. But all of that scripting and all of those steps make manual Teams migration a painful and tedious process!

Instead of jumping through all those hoops to get users up and running in their new Teams environment, why not use a third-party tool to simplify the migration process? During our keynote event Put your M365 migration in full throttle, you’ll see exactly how ShareGate can accelerate your migration.

Migrate Microsoft Teams to another tenant—the ShareGate way

As you can see by now, with no easy option available to efficiently migrate Microsoft Teams to a new tenant, our engineers put a lot of thought and effort into creating an easier, faster way to ensure users have everything they need to succeed in their new Teams environment.

With ShareGate’s dedicated Microsoft Teams migration feature you can migrate teams to another tenant—or copy teams within the same tenant—without the need to script.

We also automatically map users at the destination. That way, you’re sure the right people have access to the right teams with the right set of permissions.

With ShareGate’s migration tool, you can bring along:

• Team settings and description
• Membership (owners and members)
• Permissions
• Conversation history (including sender, threaded messages, links, and timestamps)
• Public channels
• Lists
• Files (along with their history and metadata)
• Tabs
• Apps and bots (those that are available in the App Store)
• SharePoint site customizations
• Default wiki pages
• OneNotes

Here’s how it works:

1. Start at the Copy screen. Navigate to the reimagined Copy screen and select the Copy teams option.

2. Choose which teams (and channels) to migrate. Simply connect to the tenant you want to migrate from and ShareGate generates a list of all your existing teams along with information about each team’s ownership and privacy settings. Select the teams you want to move, then click on Continue to destination.

3. Configure custom copy options. Next, select the destination you’d like to copy to…

…then, choose whether you want to copy to a new team at your destination or copy into an existing team.

ShareGate’s migration tool also flags potential issues, like duplicate team and channel names, and prompts you to modify names by adding a prefix or suffix—or changing the name completely—before your migration process takes place.

Finally, select Schedule copy to choose a time for the migration process to take place that’s convenient for you. When you’re ready, click on Start copy. That’s it!

4. Find and fix problems faster with our robust migration report. Once your migration is complete, ShareGate provides you with a summary so you can see how it went. If anything unexpected did pop up, we’ll provide you with the information you need to fix it fast.

And if you ever need additional assistance, our world-class support team is always available to help.

Ready to start your Microsoft Teams migration project? Here’s a walk-through of how to get started with copying Teams and their channels to easily reorganize and restructure your organization.