Microsoft Teams to Microsoft Teams Migration Guide

Teams original endpoints and license (per User) will be deprecated on Jan 25

The original Microsoft Teams (Source) and Microsoft Teams (Destination) endpoints will be deprecated on Jan 25, 2021. All new Teams to Teams migrations will require the new MigrationWiz-Collaboration (per Team) license and must utilize Teams Parallel endpoints.

Existing projects, created prior to Jan. 25, will not be impacted.

Please contact Sales via the form on the website for license conversion if you have any remaining MigrationWiz-Collaboration licenses.

Teams Private Chats 

Teams Private Chats now migrate. Follow the steps in the new guide to migrate private chats and linked files.

Teams to Teams Migration (New endpoint)

This document is an end-to-end migration guide that demonstrates how to perform an Office 365 Teams to Teams (New) migration using MigrationWiz. MigrationWiz supports the migration of teams, channels, conversations, permissions, and files.  

The original Teams to Teams (Original) migration guide is below. If you have a Teams to Teams migration in progress, use the links to the right of the document to navigate down to the Teams to Teams (Original) guide and follow those steps. If you are just beginning your Teams migration process, we suggest utilizing the Teams to Teams (New) guide and parallel endpoints. 

We are not able to support migrations with two-factor or multifactor authentication. 

Licenses

There are two types of Collaboration license, currently. For the original Teams to Teams migration, use the Collaboration License. For the new Teams (Parallel) endpoint, purchase MigrationWiz-Collaboration (per Team) licenses. 

  • Each license allows up to 100GB 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. 

Prerequisites 

Ensure consent has been given for the Teams application permission.

  • Use Teams-FullControlApp for both the source and destination. To learn more about what these permissions mean, view the article Application Permissions for Teams Migrations.
  • For the New Teams migration endpoint (Parallel), the advanced option UseApplicationPermission=1 does not need to be used. For Original migration scenarios, this option must be enabled during the Advanced Option phase. 

If you have not done so already, log in to your account on MigrationWiz or create a new account.

Create a New 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 the source endpoint by selecting Microsoft Teams Parallel (Source) from the drop down. Ensure Parallel is selected, the migration will fail if the Microsoft Teams endpoint is selected. 
           parallel3.png
  6. Provide your Office 365 credentials (these will be the same Office 365 username and password      you use for the MigrationWiz security group), then click Add.
  7. Next, create a destination endpoint by choosing an Endpoint Name and selecting Microsoft Teams Parallel (Destination) from the endpoint-type drop down. Ensure Microsoft Teams Parallel is selected, the migration will fail if the Microsoft Teams endpoint is selected. 
      parallel4.png
  8. Enter your Office 365 credentials. These will be the same username and password you used for the MigrationWiz security group. Once your credentials are selected, click Add.
  9. One of the two Azure Storage options listed is required to create the endpoint. For migrations of less than 5GB, you may use the Microsoft Provided Azure storage. For anything over 5GB, we recommend using Custom Azure Storage. The following steps will help you set up the custom storage:
    1. Prepare Azure Environment. If using Microsoft-provided Azure storage, you can skip this section.
    2. Estimate Azure storage costs. This step is optional but is useful in order 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 very small migration. 
    4. See How do I Create an Azure Storage Account? to create your storage account. You will need to set up a STORAGE (General Purpose v1 or 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 that 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 that is needed are these: 
    6. -accesskey – This is the Storage account name for the Blob – example “accountname 
    7. -secretkey - This is the access key for the Storage account – example “W1RrDfkPNkfYfdVqizMNJjn5mXchwMP5uYBY8MsMqWTA7EubG911+4fZlki0Gag==” 
  10. Once complete, click Save and Go to Summary.
  11. Verify that both the source and destination are Teams (Parallel) to Teams (Parallel). Variable endpoints are not supported.
  12. For the following step, credentials are mandatory. Ensure all the mandatory fields are filled to activate the Update button. Click this once all steps above are completed.

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 moving, 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.

Autodiscover 

  1. On the MigrationWiz project page, click the Add dropdown, then click Autodiscover Items.
  2. Click Start Autodiscover.
  3. Click Discover ItemsMigrationWiz will now discover teams at the source. If the authentication/credentials verification is successful, discovery status will show as Completed however, if the authentication/ credentials verification fails, error messages will be shown.
  4. To download a CSV, click the Download CSV icon. This will generate a CSV file that includes all the teams discovered at the Source. This file can be uploaded via Bulk Add during that stage.
  5. Click Import Items. The discovered Teams at the Source will be populated as line items. By default, destination mail nickname will be set to the same as Source mail nickname.

Quick Add

This option is generally used for small migrations, proof of concept migrations, and other tests. It allows you to migrate specific teams without the full CSV management.

  1. Click Add.
  2. Select Quick Add Item.

You may now add a specific team to be migrated, based on the Team Mail Nickname at the source, e.g. TeamAwesome. You will be able to select the mapping at the destination, including renaming teams if desired. For example, TeamAwesome may be mapped to TeamAwesome at the destination, or to TeamFantastic. 

If TeamFantastic exists at the Destination, the contents from TeamAwesome will be merged to the existing TeamFantastic. If TeamFantastic does not exist at the Destination, it will be created with the data from TeamAwesome.

Bulk Add

You also have the option to use Bulk Add via the CSV template file to manage adding your teams. This is a good option if you are mapping a large number of teams to new destinations, or simply have a large migration. Previously, this had to be done manually, but with the Parallel update, this is now all done within the user interface.

  1. In your project dashboard, click Add.
  2. Select Bulk Add. 
  3. The interface will now walk you through the steps up upload the CSV found through the Autodiscover process. You may edit the columns after upload to change team names or mapping. 

Start Migration

Use the checkbox to select the team(s) you will be migrating.

You will need to run a single verify credentials pass before migrating multiple items.

starimig1.png

    1. Click the Start dropdown and select Full Migration. This will bring up a new window to select what data you want to migrate in this pass. 
    2. Select Setting Up Teams, then Teams Creation if it is not selected by default. 
      mceclip0.png
    3. Click Start Migration. This pass will create the teams at the destination. Once the teams creation process has been successfully completed, wait a few hours to allow the data to finalize.  
      Important: Due to an API limitation, the channels may not be fully provisioned until they are used.

TeamsMigratePrivateChannel=1

Important: If using the "TeamsMigratePrivateChannel=1" Advanced Option, Private Channels will not be created during the scaffolding run in order to improve the success rate for their SharePoint site provision. Tests have shown that if private channels are created before the parent team SharePoint sites are ready, the private channel SharePoint site will not be created automatically.

This script must be run with either Teams Admin or Global Admin credentials or it will fail.

The csv file will be exported to the location from which the script was run. If the script was run from a different location than where it is stored, the csv will be found in the location from which the script was run, not from where it was stored.

If there are no private channels in the source tenant, then no csv file will be exported.

  1. You will now repeat the full migration process for the data. Repeat step 1, but select Migrate Data this time. Perform the following data migration steps as best practice:
    1. Migrate conversations and documents first.
    2. Migrate OneNote tabs.
    3. Migrate Teams permissions .
  2. Check the Status column for each team migration progress to ensure your teams are migrating correctly. If teams are not migrating correctly, check the credentials and run another full pass if necessary.startmig3.png
  3. 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 there are multiple people with the same prefix at the destination (e.g. name@domain1.com and name@domain2.com, or the prefix of a particular user is changed in the destination (e.g. name@source.com → name.full@destination.com), it is necessary to use the advanced option UserMapping="name@source.com->full.name@destination.com" to set the new or correct name for each user.
  4.  The User Mapping command goes in 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. 

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 Office 365 Admin portal, going to the migrated group (Team), and viewing the members 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 Office 365 user account created for the migration, as well as the MigrationWiz Security Group. 

You will also need to remove the Azure app:

  1. Once the migration has finished, remove the Office 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 Office 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 Channel Conversations

MigrationWiz will migrate 60 messages per team by default.

A Conversation History tab will be created for each corresponding channel at the destination. Each team will show the most recent 60 messages, while all older messages may be downloaded as an HTML file 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.
    E.g. TeamsMaxConversationPostPerTeam=1000 would load 1000 messages per team.

    This may slow your migration, so plan accordingly if this option is used

Migrating Private Channels

To migrate teams with private channels:

  1. Identify the teams with private channels in the source tenant via the MWTeamsPrivateChannelMembers.ps1 script attached at the end of this page.
  2. Add the Advanced Option TeamsMigratePrivateChannel=1 into the project.
  3. Do a scaffolding run ONLY first:
    1. Select “Teams Creation” in the Start Full Migration flyout.
    2. If there are any errors encountered during the scaffolding run, wait a few hours, then re-run.
    3. Important: Private Channels will not be created during the scaffolding run in order to improve the success rate for their SharePoint site provision. Tests have shown that if private channels are created before the parent team SharePoint sites are ready, the private channel SharePoint site will not be created automatically.
  4. Wait 24 hours for the Teams sites to provision. 
  5. Private channels will then be created during any content migration (Documents and OneNote, Conversations, Teams Permissions) but we strongly advise you to also follow the next steps to ensure a successful migration.
  6. First, carry out Documents and OneNote During this step we create the private channels.
    1. Frequently, private channel’s SharePoint site alone may still not get provisioned, a typical error might be as follows: Failed to get SharePoint site URL for private channel. <mailnickname:privatechannelname>. If the private channel was recently created, retry migration after 5 minutes.
    2. In this case, the user needs to manually click on the Files tab of the associated private channel, which triggers the provisioning of the private channel SharePoint site.
    3. Optionally, the user can confirm the provisioning by uploading a small document to the private channel’s SharePoint site.
  7. Once the provisioning is successful, reset errors only and re-run the Documents and OneNote migration.
  8. In this second pass of the Document and OneNote migration, the content will be migrated for private channels too.
  9. Next, carry out a conversation migration.
  10. Then carry out the OneNote tabs migrations if necessary. (Wait for at least 4 hours between Documents and OneNote migration and OneNote tabs migration to avoid any sync issues.)
  11. Finally, you can migrate the Teams permissions.
    1. Private channel permissions (membership) can only be migrated using the PS script MWTeamsPrivateChannelMembers.ps1
  12. After the migration is completed, delete the migration admin user from both source and destination to remove the user from all teams and private channel.

Private Channel Permissions

Private channel permissions are not automatically migrated, and require the use of a PowerShell script. If you are migrating private channels, follow the steps listed in the collapsible section below.

Migrating Private Channels via PowerShell

Prerequisites

  1. Latest PowerShellGet is loaded
    The PowerShellGet module can be updated by running the command below.

    • Install-Module PowerShellGet -Repository PSGallery -Force -AllowClobber

    After the update is done, close and reopen an elevated PowerShell session to ensure that the latest PowerShellGet is loaded.

  2. Teams PowerShell module is version 1.1.3-preview
    If the Teams PS module version is lower or higher than 1.1.3-preview, MigrationWiz will prompt to allow uninstall and install the required version.

Steps

  1. Run the attached script: MWTeamsPrivateChannelMembership.ps1
  2. If you run into any errors, likely due to a TLS issue, run the below command first; then re-run MigratePrivateChannelUsers.ps1.

  3. [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

  4. If prompted to update Teams PowerShell module, approve the update.
  5. Press 1 to get a list of source teams with private channels.
  6. Enter source credentials.
  7. If invalid credentials were entered, it is easiest to close the PowerShell window, start a new window, and rerun the MigratePrivateChannelUsers.ps1 script.
  8. Once credentials are verified, a CSV file will be generated. This CSV will be titled ListOfTeamsWithPrivateChannels.csv
  9. User may modify the CSV now and remove any team mailNickName entries for teams whose private channels will not be migrated to the destination tenant. 
  10. Save the CSV.
  11. Run the MWPrivateChannelOwnershipMigration.ps script again. 
  12. Press 2 to retrieve all owners and members of private channels for the respective teams as specified in the CSV file.
  13. This will generate a CSV file named OwnersAndMembersOfPrivateChanels.csv
  14. In the User column, change the user's domain from source domain to destination domain.
  15. If user mapping or teams mapping was done, ensure that these are also updated in the User and TeamMailNickName columns. 
  16. Save the CSV file.
  17. Run the script again. 
  18. Press 3 to add owners and members into the proper private channels of the corresponding teams at the destination tenant. 
  19. Enter destination credentials.
  20. If the credentials are successfully verified, you will now be able to see if the user was successfully added.

OneNote Tabs migration 

OneNote Tabs can now be migrated as part of a Teams to Teams migration under the new Teams Parallel endpoint. This item can be added in the Start Migration flyout window. 

ON1.png

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

blobid1.png 

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

blobid2.png 

All  emailed project statistics will now also include the OneNote tabs data. 

OneNote tabs cannot be migrated independently without migrating Documents.  

Migrated Items 

The following items will only be migrated in a Teams Parallel migration, and only if the OneNote Tabs item type is selected. 

OneNote Documents/Notebooks 

  • The existing/default OneNote notebook for each migrated team (both public and private teams). 
  • New OneNote notebook. This notebook will automatically be stored in a particular folder associated with each channel (inside the SharePoint site). 
  • Password-protected notebooks will be migrated as well. 
  • Only OneNote documents relevant to the team/line items in the project will be migrated. 

OneNote Tabs  

Only migrated if the "OneNote tabs" item type is selected.

  • OneNote tabs will be migrated and created at the destination tenant. This is for both public and private channels. 
  • For private channels, if the OneNote document is originally created/added in the destination private channel itself, the contents are migrated, but tabs cannot be created. However, if the OneNote tab was originally created/added in a parent Team and thereafter added as a link into the private channel of that team, the OneNote contents gets migrated into the OneNote tab created. 

OneNote Contents 

  • OneNote permissions will be migrated if the document permissions type is checked to enable document permissions. 
  • All the OneNote content structure/formatting will also be migrated - including section, pages, title, tables. 

Scenarios/Use Cases: Where was the OneNote tab added from?  

OneNote Notebook migrated? 

OneNote Tabs created?  

Default/existing OneNote notebook per source team 

Yes 

Yes 

New OneNote notebook created in the source team 

Yes 

Yes 

OneNote notebook that was originally created/added in a parent source team and thereafter added as a link into the private channel of that team  

Yes 

Yes 

OneNote notebook that was originally created/added in the private channel at the source 

Yes 

No 

OneNote notebook present in another team’s SharePoint site 

Yes; only if this other team is already migrated in MigrationWiz 

No 

Personal OneNote (stored in personal OneDrive at source) 

No 

No 

If there are failures during OneNote tab migrations, do a "Reset Items" pass to reset errors before resubmitting the migration. Otherwise, all OneNote notebooks and tabs will be recreated.  

Items Not Migrated 

  • A OneNote document present in an individual user’s OneDrive account. 
  • This type of item will be migrated via standard MigrationWiz document project. A warning message will be shown.

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 from 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. 

Notebooks 

  • If the source team name and destination team name are different, and the destination team notebook is already provisioned, default mapping will apply. This means that contents in the source notebook will be automatically migrated to the destination notebook even though the team names are different. 
  • If the source team display name and the destination display name are different, and the destination team notebook was not provisioned due to Microsoft limitations, the source notebook will be migrated as-is.  
  • Source default notebook content will be migrated but will not show as the default if the destination notebook has not been provisioned. 

Migrating OneNote 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. 

  1. Ensure the MigrationWiz User has already consented to either Teams-ReadOnlyApp or Teams-FullControlApp.
  2. Log in to MigrationWiz.
  3. Create a Teams Collaboration project. 
    • Required endpoints: Teams Parallel (Source) and Teams Parallel (Destination). 
  4. Start adding Teams via Autodiscover, Quick Add, or Bulk Add. Steps for these processes are included in the Teams Parallel migration guide below. 
  5. Select which teams to migrate.
  6. Click Start Migration for a ‘Teams Creation’ pass first.
  7. Wait 24 hours for the Teams to provision. 
  8. Migrate Data without OneNote tabs.
    1. Select teams to migrate.
    2. Click Start Migration with ‘Documents and OneNote’ with any other item types but do not select OneNote Tabs.
    3. Wait approximately 4 hours for the OneNote documents to be discovered by the OneNote service.  
  9. Migrate data with OneNote tabs. 
    1. Select ‘OneNote tabs’ and any other item types which still need to be migrated. 
    2. Documents and OneNote can be selected again to bring over any newly created documents since the last migration.  

Migrating Teams with Special Characters in the Name 

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: 

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

Migrating Teams EDU templates

MigrationWiz will only migrate teams, channels, documents, and messages for Teams EDU Classroom templates. For more information, contact Support. 

Migrating using U.S. Government Tenants 

Migrating to or from a U.S. Government tenant requires specialized commands for MigrationWiz to connect. Failing to use these options will result in login errors. 

  1. Click Edit Project. 
  2. Click Advanced Options. 
  3. Under Support Options, add the following options below, depending on the specific migration scenario. 
  • If migrating from a U.S. Government Tenant, add: OneDriveProExportEnvironment=AzureUSGovernment 
  • If migrating to a U.S. Government Tenant, add: OneDriveProImportEnvironment=AzureUSGovernment 
  • As U.S. Government Tenant does not support Application Permission, make sure that the migrating accounts are Global Admin, add: UseDelegatePermission=1

 Government-Specific Limitations

  • Conversation History will not be migrated to a tab in the destination. Instead, a message will be posted in the channel with a link to the conversation history HTML file.
  • Due to limitations in the Microsoft system, images will not be migrated as part of the conversation(s). They will still appear in the conversation history HTML file. 

Teams Support Options

Support Options Description
TeamsMaxConversationMessage=XXX Limit 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 . Default will be 60 if this option is not added.

*Setting a higher limit will have adverse effect on migration time, as each message post takes 0.5 seconds to post

TeamsMigratePrivateChannel=1 Private channels will be migrated as private channels with conversations and documents. Users will not be migrated; users at the destination must be added manually or via PS script. Refer to section on Migrating Private Channels 

 


*Teams to Teams (Original) Migrations*

A Teams to Teams migration is complex and requires several prerequisites to be met. Read the Collaboration Best Practices article before you begin this migration.

Due to limitations on connections allowed by GoDaddy, we do not support migrating to or from GoDaddy using this migration type.

Private Channels Script Requirements

Important: MigrationWiz does not migrate private channels by default. If you have private channels you want to migrate, do so by adding the line TeamsMigratePrivateChannel=1 to the support section of the project's Advanced Options. Please note, users will not be added to the private channel on the destination. This needs to be done manually after the private channel migrates.

This script must be run with either Teams Admin or Global Admin credentials or it will fail.

The csv file will be exported to the location from which the script was run. If the script was run from a different location than where it is stored, the csv will be found in the location from which the script was run, not from where it was stored.

If there are no private channels in the source tenant, then no csv file will be exported.

Due to Microsoft limitations, private channels are not migrated for GCC High Tenants. 

To discover what other items are moved with MigrationWiz in this scenario, and which items will not be moved, see Moved Items. These items will vary by source and destination so check the proper environment listings carefully.

MigrationWiz is a migration tool, not 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 we cannot handle scenarios such as conflict resolution without user interaction.

License Type

This endpoint requires MigrationWiz Collaboration licenses. 

Prepare the Source

  1. Create a new, fully licensed, cloud only, Global Administrator account in Office 365 to be used for migration or use the existing Global Administrator account for the tenant. If using the existing Global Administrator account, it must be fully licensed and must not configured with multi-factored authentication (MFA) or AFDS. 
  2. ADFS and Multi-Factor Authentication must be turned off for the administrator accounts on both the source and destination before starting a Collaboration migration.
  3. Add the Administrator account as an owner to the teams on the source. Do this at least 24 hours before migration testing to avoid delays in permission setting. Do not add the admin to any private channels.
  4. Set up the app-based authentication in the Office 365 tenant by following the steps below in the Enable App-Based Authentication section of this document.

Prepare the Destination

  1. Create a new, fully licensed, cloud only, Global Administrator account in Office 365 to be used for migration or use the existing Global Administrator account for the tenant. If using the existing Global Administrator account, it must be fully licensed and must not configured with multi-factored authentication (MFA) or AFDS.
  2. ADFS and Multi-Factor Authentication must be turned off for the administrator accounts on both the source and destination before starting a Collaboration migration.
  3. Create user accounts and assign Office 365 licenses. The Office 365 licenses must include Teams access. For more information on which licenses can be used, refer to Office 365 Licensing for Teams. Note, free or Kiosk licenses are not supported.
  4. Set up the app-based authentication in the Office 365 tenant by following the steps below in the Enable App-Based Authentication section of this document.
  5. Prepare Azure Environment. If using Microsoft-provided Azure storage, you can skip this section.
    1. Estimate Azure storage costs. This step is optional but is useful in order to provide the customer with upfront storage costs ahead of time. For more information, see Estimate Azure Storage costs for migrations.
    2. Buy an Azure subscription (or use the free one-month trial and be aware that this option is only viable if you are performing a very small migration). For more information, see Create Azure Storage Account.
    3. See How do I create an Azure Storage Account? to create your storage account. You will need to set up a STORAGE (General Purpose v1 or 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 that 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.
      The access key information:
      1. -accesskey – This is the Storage account name for the Blob – example “accountname”
      2. -secretkey - This is the access key for the Storage account – example “W1RrDfkPNkfYfdVqizMNJjn5mXchwMP5uYBY8MsMqWTA7EubG911+4fZlki0Gag==”

Enable App-Based Authentication

Set up the app-based authentication in the Office 365 tenant. BitTitan uses app-based authentication for SharePoint, OneDrive for Business, Office 365 Groups (Documents) migrations, and Teams migrations. This provides greater security and reduces the potential of Microsoft throttling. It replaces the previous Office 365 authentication, which has been subject to increased throttling by Microsoft. This app-based authentication method is specific for Office 365 tenants.


Important: This app must be added in both .microsoftonline.com tenants (source and destination) to reduce the throttling and failures due to Microsoft throttling policy changes.

If this app is not added on both tenants, MigrationWiz will attempt to create a temporary substitute app in the tenants to be used for authentication. We do not recommend relying on this substitute app creation, as this behavior will only be a temporary transitional behavior within MigrationWiz. To avoid potential interruptions or failures in migrations, it is strongly recommended to set the app up in the tenants.

Add the App to the tenant

1. Visit the following URL and sign in as the administrator user:

For Teams migrations: https://login.microsoftonline.com/common/adminconsent?client_id=e541adb0-93aa-4053-a1e3-04692035881d&state=12345

For SharePoint or OneDrive migrations: https://login.microsoftonline.com/common/adminconsent?client_id=e7c20566-14a7-4722-acd1-396f7268ea1a&state=12345

Do this for both source and destination tenants.

2. Authorize the App for both source and destination tenants.

3. Click the Accept button.

Steps to remove these permissions are provided below in the Post-Migration section.  

Run Migration

Create a Collaboration migration project

  1. Sign in to your MigrationWiz account.
  2. Click Go To My Projects.
  3. Click Create Project.
  4. Select a Collaboration migration type. Collaboration projects are used to migrate a Microsoft Teams instance from one Microsoft tenant to another. Collaboration migrations migrate all Teams, Channels, files, and permissions.
  5. Click Next Step.
  6. Enter a Project name and select a Customer.
  7. Click Next Step.
  8. Select a Source Endpoint from the Endpoint dropdown menu. If an Endpoint has not been created, click New and provide the requested information in the Endpoint creation flyout.
  9. Select a Destination Endpoint from the Endpoint dropdown menu. If an Endpoint has not been created, click New and provide the requested information in the Endpoint creation flyout. The endpoints will automatically default to the type “Teams”. This is normal and cannot be changed.
  10. Click Save and Go to Summary.
  11. Click Start Assessment to add items to the Collaboration project.
    • During Assessment, the Admin/Service account will be automatically added as an owner to all teams in the Source tenant. This is required to be able to discover all teams, channels, users, conversations and files in both tenants before the migration can proceed.
    • When the Assessment completes, MigrationWiz will display information such as the number of teams, total file size, total number of users, the number and type of licenses needed, and the number of licenses currently available to be used.
    • Guest users will not be included as part of the assessed license requirement. Conversations that guest users participate in will be migrated as part of the migration process.
    • If enough licenses were already purchased and seen by the Assessment, skip steps 12 and 13.
  12. Purchase MigrationWiz-Collaboration licenses. The total number of licenses is shown on the completed Assessment page.
  13. Once the licenses have been purchased, refresh the browser page showing the Assessment results.
  14. Username changes: 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 there are multiple people with the same prefix at the destination (e.g. name@domain1.com and name@domain2.com, or the prefix of a particular user is changed in the destination (e.g. name@source.com → name.full@destination.com), it will be necessary to use the advanced option UserMapping="name@source.com->full.name@destination.com" to set the new or correct name for each user. The UserMapping command goes in 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.
  15. Once the assessment shows the message “You have sufficient licenses. You can start your migration”, you will be able to click the Start Full Migration. To migrate only some Teams from the Source, it is possible to use a CSV to select the specific teams to migrate. Follow the steps below to migrate from a CSV.

Migration Customization Options

The following options are not required, and will only apply to some migrations. Follow the steps outlined for scenarios that apply to your migration. Once these steps have been followed, continue to the Post Migration section below.

Migrate Teams via CSV

After running an Assessment, it is possible to use a MigrationWiz-generated CSV to select which teams are included in the migration. To use this functionality, follow the steps below.

  1. Open the Collaboration project that needs specific teams selected.
  2. If an Assessment has not already been completed, run an Assessment.
  3. After the Assessment completes, click the Actions button and click Select Teams.
  4. From the flyout, click Assessment Summary CSV File.
  5. When the file finishes downloading, open the file and edit only the first column, titled Selection (true/false).
    1. All teams with “TRUE” in the Selection column will be included in the migration. To exclude a team from the migration, change “TRUE” to “FALSE”. A blank cell will be treated as a “FALSE”.
    2. Do not change any other information in the CSV file. Changing other fields will cause the team selection to fail.
  6. Save the modified CSV. Note, the file must remain in .csv format and cannot exceed 5MB.
  7. The new CSV will be uploaded to the project in the same flyout menu that it was downloaded from. The upload entry field is shown at the bottom of the flyout menu.
  8. Click Select File.
  9. Find the modified CSV on your computer and select it.
  10. Click Import. The Assessment results for the project will be updated to reflect only the teams now selected for migration.
  11. When ready, click Start Migration.
  12. After the migration completes, verify on the Destination tenant that only the specified teams have been migrated.
  • After uploading the CSV file, a new option will show under the Actions menu.
  • Clear All Selections: This option will clear the updated CSV list, resetting the migration back to the default. This means all teams will be selected for migration.
  • Selecting Run Full Assessment after uploading a modified CSV will also clear the updated CSV list and reset the migration back to the default of all teams being selected for migration.

Migrating Teams with Special Characters in the Name

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:

  1. Open Excel.
  2. 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 correct language character identifier).
  5. Change the Delimiter to comma.
  6. Select where to import to and Finish. While these steps should work for most versions of Excel, some versions may still not be able to open the CSV.
  7. Click the Start Full Migration.
  8. When the migration is complete, verify that the users are able to see their teams and channels in the Destination tenant.
  9. Click the bar chart icon in the MigrationWiz dashboard to request an email containing the project migration statistics.

Migrating Teams while adjusting Team names during migration

If Teams already exist on the destination tenant with the same MailNickName as Teams on the source tenant, the Teams can be migrated using the steps below to avoid merging the Teams or causing the migration to run into errors.
This Advanced Option will change the MailNickNames of all Teams migrated while the option is in place. To only rename specific Teams, it would be necessary to use a filter to specify which teams to migrate. For more information on using filters, see Collaboration Migration: Adding a Filter.

Depending on the preferred renaming format, choose one of the Support Options listed below.

To add text before the Team MailNickName: PrependRootFolderName="text"

Add text after the Team MailNickName: AppendRootFolderName="text"

  • Replace “text” with the desired text to be added before or after the team name. For example, if using PrependRootFolderName=“Migrated” and migrating a Team named “Product”, after migration, the team name will be “MigratedProduct”. Using AppendRootFolderName in the same example would rename the team “ProductMigrated”.
  • The Group Name will not appear differently on the Destination after the migration. The change is only for the MailNickName. If a team with the same name already exists on the Destination, there will be two instances of that team name on the destination after the migration.

It is recommended you use a prefix or suffix to identify the original Channel for ease of group management after the migration completes.

Migrating using US Government Tenants

Migrating to or from a US Government tenant requires specialized commands to all MigrationWiz to connect. Failing to use these options will result in login errors.

  1. Click Edit Project.
  2. Click Advanced Options.
  3. Under Support Options, add one or both of the commands below, depending on the specific migration scenario:
    1. If migrating from a US Government Tenant, add:
      OneDriveProExportEnvironment=AzureUSGovernment
    2. If migrating to a US Government Tenant, add:
      OneDriveProImportEnvironment=AzureUSGovernment
  • Conversation History will not be migrated to a tab in the destination. Instead, a message will be posted in the channel with a link to the conversation history HTML file.
  • Due to limitations in the Microsoft system, images will not be migrated as part of the conversation(s). They will still appear in the conversation history HTML file. 
Was this article helpful?
4 out of 11 found this helpful