#Chat Migration Assist Tool

Refer to the following steps to prepare and run the Assist Tool:

1. Access the to download the ChatMigrationAssistTool.zip file, and extract the ZIP file.

2. In the extracted tool folder, open the ChatMigrationAssistTool.exe.config file with Notepad.

3. Configure the accounts in the following nodes of the CONFIG file.

   

   • <add key="ServiceAccount" value=" "/> – Configure the user principal name of the destination service account or consent user as the value=" " parameter value.

   • – Configure the user principal name of the placeholder account as the value=" " parameter value.

   • – If your machine where the tool will be run has a network connection, you can skip this node. Otherwise, configure a proxy as the value=" " parameter value in the format of IP:\Port. Then, configure the username in the node to log in to the proxy server, and configure the password in the node to access the proxy server.

   • <add key="AppId" value=" " /> – By default, Fly will retrieve and use the build-in app of the tenant for connection. If you want to use a custom app, configure the custom app ID as the value=" " parameter value.

     *Note: Make sure you have configured a client secret or certificate for the custom app to encrypt the app. If you choose to use a certificate to encrypt the custom app, store the certificate in the same directory as the ChatMigrationAssistTool.exe file. Then, continue configuring the following nodes:

   • – Enter the certificate file name as the value=" " parameter value.

   • – Enter the certificate’s password as the value=" " parameter value.

4. Steps from 1 to 2 apply to all functions. To use any function, make sure you have configured the <add key="ServiceAccount" value=" "/> and nodes in the CONFIG file.

5. To use Function 2, Function 3, or Function 5, ignore this step and proceed directly to step 5.

   To use other functions, complete the following setup steps first.

   • Function 1 – Prepare a CSV file, and configure the chat ID of the chats where the chat members you want to remove, as shown in the screenshot below.

     

   • Function 4 – Prepare a CSV file, and configure the chat ID of the chats where the chat members you want to remove, as shown in the screenshot below.

     

   • Function 6– Create a CSV file, and enter the ID of chats you want to delete in each row.

     

   • Function 7:

     1. Create a custom app in destination tenant and add the following permissions to the app.

6. Right-click the ChatMigrationAssistTool.exe file and select Run as administrator.

7. Enter 0, 1, 2, 3, 4, 5, 6, 7, 8, or 9 to indicate the function depending on whether the destination service account (or consent user of the destination delegated app profile) is a Microsoft 365 Global Administrator.

   • If the destination service account or consent user is a Microsoft 365 Global Administrator, enter 1, 2, 3, 4, 5, 6, 7, 8, or 9 to execute the corresponding function directly, and press Enter on the keyboard.

     

     On the Microsoft sign in page, use the destination service account or consent user to sign in to the destination tenant, and select the Consent on behalf of your organization option.

   • If the destination service account or consent user is not a Microsoft 365 Global Administrator, you need to consent permissions to the service account or consent user first by entering 0. Press Enter on the keyboard.

     On the Microsoft sign in page, use the Microsoft 365 Global Administrator to sign in to the destination tenant, and select the Consent on behalf of your organization option on the authentication page.

     Then, right-click the ChatMigrationAssistTool.exe file again and select Run as administrator. Enter 1, 2, 3, 4, 5, 6, 7, 8, or 9 to execute the corresponding function, and press Enter on the keyboard. On the Microsoft sign in page, use the destination service account or consent user to sign in to the destination tenant.

   *Note: The following functions also requires additional input:

   • Function 1 – After entering 1, enter the full path of the CSV file containing the chat IDs configured in step 4 for this function, and press Enter on the keyboard.

   • 

   • Function 3 – After entering 3, enter the user principal name of the user you want to remove, and press Enter on the keyboard.

   • 

   • Function 4 – After entering 4, enter the full path of the CSV file containing the chat IDs configured in step 4 for this function, and press Enter on the keyboard.

   • 

   • Function 6– After entering 6, enter the full path of the CSV file containing the chat IDs configured in step 4 for this function, and press Enter on the keyboard.

   • 

   • Function 7 – After entering 7, enter the full path of the CSV file containing the chat IDs configured in step 4 for this function, and press Enter on the keyboard.

   • 

   • Function 8 – After entering 8, enter the full path of the CSV file containing the usernames configured in step 4 for this function, and press Enter on the keyboard.

   • 

   The process will be started. After the process finishes, a CSV file will be generated to report the results.

   *Note: If you enter 1, 2, or 4 in step 6 to remove the service account or consent user, and want to recreate the chats in the destination, you can add the CreateNewChatIfServiceAccountIsLeave=true feature string in the Customized feature section in the Microsoft Teams Chat migration policy, and rerun the full migration job. Make sure you configure correct user mappings for source chat users.

   *Note: If you enter 9 to replace links in migrated chat messages, pay attention to the following results:

   • If the destination service account or consent user does not exist in a chat, the whole chat will be skipped in the job.

   • If a migrated message’s sender is not the destination service account, the message will be skipped in the job.

   • If links in a chat or message have been replaced in the last job, the chat or message will be skipped in the current job. In this situation, if you want to update the URL with the final domain to another one in the UrlMapping.csv file and replace the links to the new URL, you need to delete the Cache folder from the extracted tool folder before running another job.

   • Only the links sent in original messages and replies can be replaced. Links in replied messages as the screenshot below will be skipped in the job.