#Microsoft Teams Chat Migration Process

The sections below contain the general migration process for Microsoft Teams Chat Migration. The details outlined in this document can serve as general guidelines with some minor adjustments.

• Preparation
• Migration Execution

More steps may be needed, and some steps included in the process may be optional according to your migration requirements.

#Preparation

Before the migration, you need to identify what object types they want to migrate. See the Supported and Unsupported List.

#1. Create delegated app profile and app profile with required permissions

To connect Fly to your Teams Chats, create an app profile with required permissions in AvePoint Online Services. Refer to the latest Required Permissions to check the required permissions for Microsoft Teams Chat Migration.

#2. Create users in destination tenant

Add new Microsoft 365 users or synchronize users from the local Active Directory to Microsoft 365.

• If your source domain will be moved to the destination environment:

  It is recommended that you use the user principal name with the default Microsoft 365 domain(user@contoso.onmicrosoft.com) in migration projects. Or you can use user principal names ending with an owned domain. After the domain name of your source tenant is changed to your destination tenant for go-live, if the final incremental migration is needed, use Change mapping domain in Fly to update the user principal names in projects in bulk.

• If the source domain will not be moved to the destination environment, you can just use user principal names with different domains when configuring mappings in migration projects.

• Refer to the user guide about how to prepare users.

#3. Assign licenses for users

You need to assign Microsoft Teams and SharePoint Online licenses to the destination service account (or consent user of delegated app profile) before the migration.

#4. Prepare sensitivity labels in destination (optional)

If the source tenant does not have sensitivity labels, you can ignore this step.

If the source tenant has sensitivity labels, and you want to keep the source sensitivity labels applied on chat attachment files to the destination, you need to create and publish the sensitivity labels in the destination before the migration. Refer to Create and publish sensitivity labels for details.

#5. Configure a placeholder account in the destination tenant

Source chats will be converted to group chats due to API limitations. A placeholder account is required to create a group chat and must meet the following criteria:

• The account must be an active user in the destination tenant, which does not need any licenses or admin roles.

• The account cannot be the same as the destination service account (or consent user of destination delegated app profile) or a destination chat user in the migration.

#6. Check destination retention policies

If retention policies are configured for the source data, check to make sure the destination retention policies are the same as the source retention policies. Otherwise, the destination data may be deleted due to different retention policies.

#7. Create source and destination connections

Refer to Create a Connection to connect Fly to your source and destination Teams chats.

Pay attention to the following information:

• If you only use the delegated app profile or service account in the destination connection and remove the consent user or service account from destination chats after the migration, the consent user or service account cannot be re-added to those chats in the next incremental migration job. Therefore, source newly added or edited messages cannot be migrated into those destination chats.

• If you only use the delegated app profile or service account in the destination connection and change the consent user or service account after the migration, the new consent user or service account cannot be added to those already migrated chats in the next incremental migration job since the new consent user or service account has no permission to those chats. Therefore, source newly added or edited messages cannot be migrated into those destination chats.

Based on the situations above, we recommend you also provide an app profile in the destination connection. Fly can add the service account to those destination chats and migrate source newly added or edited messages to those destination chats.

• If you only use the delegated app profile or service account in the destination connection, the consent user or service account will be shown as the creator of destination chats. If you also use an app profile in the destination connection, the app name will be shown as the creator of destination chats.

#8. Migration throughput

Generally, the average migration rate of chat messages ranges from 1000/hour/mapping to 4000/hour/mapping, depending on your tenant's performance. The number of mappings that run in parallel is automatically allocated based on your purchased subscription. The more subscriptions you purchase, the more mappings you can run in parallel.

#9. Project setup

Generally, we recommend you keep using the source chats during the migration process until you migrate all data to the destination.

#10. Prepare the user mapping file

Refer to Create User Mappings to prepare a user mapping file.

Make sure the user mappings of source and destination chat users are correct. This can ensure that your desired destination chat users can view the migrated chat messages of source chat users and continue chatting in the destination.

#11. Design the migration policy

A Microsoft Teams Chat migration policy allows you to define the migration scope of Teams chats, whether to migrate chat file attachments, the conflict resolution for chat file attachments, how to map chat users, and how to manage the sensitivity labels of chat file attachments for Microsoft Teams Chat migrations. Refer to Create a Migration Policy for details.

#12. Understand when users will receive notifications

Destination users may receive notification in the following situations.

• The chat messages will be marked as unread after being migrated to the destination. If the destination chat users have configured their Chat message notifications setting as Show in banner, they will receive notifications about the messages while using the Teams app.

• If a user is mentioned in a message in the source chat, the destination user of the mentioned user will receive a notification during the migration.

• If a message is marked as Urgent in the source chat, notifications will be sent repeatedly to the migrated chat in the destination until the chat is read.

• The owners of destination OneDrive sites will receive notifications:

  • Shared links of the Anyone with the link type are migrated to the destination.

  • Shared links of the People in [tenant] with the link or People you choose type that are shared with external users are migrated to the destination.

#13. Plan a pilot run

We recommend you do a pilot run for the following purposes:

• Get familiar with the Fly interface and understand the whole migration process.

• Discover any potential issues early and resolve them before production migration.

• Understand the throttling situation in case content size is large, and then try to resolve with source and destination.

#Migration Execution

Refer to the following sections to execute the migration.

#1. Configure projects and mappings in Fly

To configure projects and mappings, refer to the Create a Project and Create Migration Mappings sections in the User Guide for details.

#2. Perform regular full migrations

Before running the job, we recommend you verify the mappings to ensure that the mappings are available for migration. Refer to Pre-analyze Mappings for details.

Then you can run a full migration job to migrate the objects based on your configured migration policy. Refer to Run Migrations to Migrate Objects for details.

#3. Perform regular incremental migrations

Some issues may occur during a full migration job. Run an incremental migration job to handle new, updated, and failed data. Refer to Run Migrations to Migrate Objects about how to perform regular incremental migrations.

#4. Validate migration results

1. Check the mapping report. If the mapping fails or finishes with exceptions, you can check the error code and comment for the mapping in the Migration errors section. You can click the error code to view the details and recommendations of the code in the Troubleshooting Guide, which can assist you in resolving or avoiding the error.

   You can also view the migration summary of your projects within a specific time range in Report center.

2. Check the following data that are migrated to the destination tenant:

   • Chat messages and members

   • File attachment links in chat messages and OneDrive

   • HTML files that contain archived chat messages in OneDrive

   • New messages can be posted in destination chats.

   • Teams chat functions can work normally, such as posting messages, replying to messages, adding file attachments, and creating new chats.

#5. Perform the final cutover (optional)

After you change the domains of your Microsoft 365 tenants, the user principal names have been changed. Therefore, if you want to run the incremental migration job after the cutover, you need to use the Change mapping domain function in Fly to update the user principal names in migration mappings. Refer to the user guide for Change Mapping Domain for details.

#6. Perform the final incremental migration

Perform the final incremental migration job to ensure that all source data are migrated to the destination.

#7. Remove the service account (or the consent user) and placeholder account

You can delete the service account (or consent user of delegated app profile) and placeholder account from the destination Microsoft Entra ID after all migrations are finished. If you do not want to delete those users, you can use the Chat Migration Assist Tool to remove the service account (or consent user) and placeholder account from the destination chats. For details about how to use the Assist Tool, refer to Assist Tool for Microsoft Teams Chat Migration.

#8. Mark migrated messages as read

Messages migrated to destination chat users will be marked as unread by default. After all migrations are finished, destination chat users can manually mark the messages as read.