Teams Migration Best Practices - Original Endpoint

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.


Best Practices

Items listed under Best Practices are things to be aware of for the migration process and may include steps that are recommended to be performed before, during, or after a migration for the best possible outcome. This document is for the original Teams endpoint.

Important:  MigrationWiz does not migrate Teams private channels by default. Private channels can be migrated adding the Support Option TeamsMigratePrivateChannel=1 to the Advanced Options of the MigrationWiz project.
Note: Members of Teams private channels will not be migrated. Members will need to be manually added to the Teams private channel in the destination after migration is complete.

Before a Migration

  • Ensure that the users are all set up and licensed on the destination (MigrationWiz does not create or license the users). We recommend setting up the users several hours prior to the migration, as Microsoft can take up to 24 hours to complete user setup in a tenant.
  • The administrator account on the destination must be set up without a federated account.
  • Assessments are required for Collaboration migrations. They cannot be skipped.
  • If Teams is already set up on the destination and has Groups with the same names as Groups on the source, it is possible to use a Support Option to avoid merging Groups. For specific instructions and more information about the process, see Adjusting Teams email addresses (MailNickName) during migration.
  • 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 “”, we match the “name” portion. If there are multiple people with the same prefix at the destination (e.g. and, or the prefix of a particular user is changed in the destination (e.g. →, it will be necessary to use the advanced option UserMapping=">" to set the new or correct name for each user. For instructions on adding this option, see How do I add support options to a project or to a single item?
    Note: 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.

Important: During a Teams migration, permissions for the teams channel files are inherited from the parent team by default. Some source files may have custom permissions due to cross-team or external-partner sharing. Migrating these custom permissions happens at the file level, requiring more API calls to the source and destination SharePoint CSOM API, which increases the likelihood of the migration being throttled. To avoid this, we recommend de-selecting Document Permissions in the item selection window when starting your migration and informing users that custom permissions will need to be re-added post migration.

Additionally, to prevent users from updating or using specific Teams while the migration is ongoing, it is possible to archive the team on the source for the duration of the migration. This will prevent changes to the Team and its channels.


During a Migration

  • MigrationWiz is not an updating tool. Once a Collaboration project has been started, we recommend that you do not rename any Channels at the source. If Channels need to be renamed, they should be renamed before an initial assessment is run, or after all teams have been successfully migrated to the destination tenant. If a Channel is renamed between when the initial assessment is run and the final migration has completed, some files may end up in incorrect destination locations.
  • Conversations that are migrated, then updated on the source, will not be updated on the destination when the migration is run again. Because of this, it is best to plan to do this migration in a single migration pass, generally over a weekend or a planned down time.
  • If conversations are updated during the course of the migration, the migrated files will need to be deleted from the destination tenant. The project will need to be reset from the Action menu, the assessment will be run again, and then you can migrate the files again.
  • Alternatively, it is possible to delete only the updated conversation from the destination, adding a filter to the project to migrate only that specific conversation. After the project has been reset, run the migration again. To add a filter, use the instructions in the article How do I filter a Folder? The team name will be used for the filter. For example, if the specific team is called Team_Alpha and the specific channel is called Project_ChitChat, then the filter used to migrate only this channel would be ^(?!Team_Alpha/Project_ChitChat)

Note: To add filters or mapping to a project, click Edit Project and select Advanced Options.


After a Migration

  • 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.
Was this article helpful?
1 out of 3 found this helpful