Appendix R – Tools for Microsoft Teams Chat / Slack

Direct Messages Migration

Chat Migration Assist Tool
The Assist Tool can help you remove the destination service account or
consent user of the destination delegated app profile and placeholder
account from all destination chats that are newly created by Fly Server.

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

1. Access the storage location of tool package 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.
 <add key="PlaceHolderUser" value=" " /> – Configure the
user principal name of the placeholder account as the value=" "
parameter value.
 <add key="ProxyURL" 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 <add key="ProxyUserName" value=" " /> node to log in
to the proxy server, and configure the password in the <add
key="ProxyPassword" value=" " /> 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:

o <add key="CertificateFileName" value=" " /> – Enter

the certificate file name as the value=" " parameter
value.
o <add key="CertificatePassword" value=" " /> –
Enter the certificate’s password as the value=" "
parameter value.
4. Right-click the ChatMigrationAssistTool.exe file and select Run as
administrator.
*Note: Enter 0 or 2 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 2 to directly remove the service
account or consent user and placeholder account, and press
Enter on the keyboard to start the job.

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 2 to remove the
service account or consent user and placeholder account, and
press Enter on the keyboard to start the job. On the Microsoft
sign in page, use the destination service account or consent
user to sign in to the destination tenant.

The process of removing members will be started. After the

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

Use Other Functions

You can also perform other actions by entering the corresponding
function number according to your requirements. The steps from 1 to
4 are the same to all functions, but you need to pay additional notes
under specific action.

 1 – Keep the placeholder account, and remove other chat

members (including the service account or consent user) from
specific destination chats.
*Note: Before step 4, you need to 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.

Then after entering 1, enter the full path of the CSV file, and
press Enter on the keyboard.

 3 – Remove specific internal user from all destination chats.

*Note: After entering 3, enter the user principal name of the
user you want to remove, and press Enter on the keyboard.

 4 – Remove the service account or consent user and placeholder

account from specific chats.
*Note: Before step 4, you need to 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.
 Then after entering 4, enter the full path of the CSV file, and
press Enter on the keyboard.

 5 – Remove all external users from all destination chats.

 6 – Delete specific chats from all destination chat users.
*Note: Before step 4, make the following preparations:

i. Create a custom app in source tenant and add the

following permissions to the app.

API Permission Type Description

Microsof User.Read.All Application Retrieve information

t Graph of chat user profiles.

Chat.ReadBasic.All Application Retrieve chat

information.

ChatMember.Read.All Application Retrieve chat users.

Chat.ManageDeletion.Al Application Delete and recover

l deleted chats.

i.
ii. Create a CSV file, and enter the ID of chats you want to
delete in each row.

iii. Configure the custom app ID as the value=" " parameter

value in the <add key="AppId" value=" " /> node.
Then after entering 6, enter the full path of the CSV file, and
press Enter on the keyboard.

 7 – Add the service account to specific destination chats.

*Note: Before step 4, make the following preparations:
 i. Create a custom app in source tenant and add the
following permissions to the app.

API Permission Type Description

Microsoft User.Read.All Applicatio Retrieve information of

Graph n chat user profiles.

Chat.ReadWrite. Applicatio Retrieve and modified

All n chat members.

ii. Create a CSV file, and ID of chats you want to add the
service account in each row.

iii. Configure the custom app ID as the value=" " parameter

value in the <add key="AppId" value=" " /> node.
Then after entering 7, enter the full path of the CSV file, and
press Enter on the keyboard.

 8 – Scan all chats from specific users.

*Note: Before step 4, make the following preparations:

i. Create a custom app in source tenant and add the

following permissions to the app.

API Permission Type Description

Microsoft User.Read.All Application Retrieve information

Graph of chat user profiles.

Chat.ReadBasic.All Application Retrieve chat

information.

ChatMember.Read. Application Retrieve chat users.

All
 ii. Create a CSV file, and enter the username of source chat
members whose chats you want to scan in each row.

iii. Configure the custom app ID as the value=" " parameter

value in the <add key="AppId" value=" " /> node.
Then after entering 8, enter the full path of the CSV file, and
press Enter on the keyboard.

 9 – Replace links in migrated chat messages.

*Note: Before step 4, you need to configure the
UrlMapping.csv file to define destination chat users for whom
you want to replace links. Refer to Configure the UrlMapping.csv
File for preparation details.

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

Tool to Hide Chats from Users

If you have mapped your source chat members to unexpected destination
users, and do not want to those destination users see the destination chats
and chat messages, you can refer to the following steps hide the destination
chats and chat messages from specific destination users:

1. Scan the source chats to identify where the source chat members of
those destination users reside by completing the following steps:
a. Create a custom app in source tenant and add the following
permissions to the app.
API Permission Type Description

Microsoft User.Read.All Application Retrieve information

Graph of chat user profiles.

Chat.ReadBasic.All Application Retrieve chat

information.
 ChatMember.Read. Application Retrieve chat users.
All

a. Access the storage location of tool package and download the

ChatScanTool.zip file.
b. Extract the ZIP file to a location with a network connection.
c. Create a CSV file in the extracted folder, and name the file as
Users.
d. In each row of the CSV file, enter the username of source chat
members whose chats you want to scan.

e. In the extracted tool folder, locate the

ChatScanTool.exe.config configuration file and open it with
Notepad.
f. In the configuration file, configure the tenant ID, csv file path of
the user list, and the app ID and secret key of the custom app
you create in step a.
 g. Create a Reports folder in the extracted folder.
h. Double-click the ChatScanTool.exe application file to scan the
chats of the configured users.
After the scan is finished, a report file with the scanned source
chats will be generated in the Reports folder.

2. Hide the chats from those destination users by completing the

following steps:
a. Access the storage location of tool package and download the
HideChatTool.zip file.
b. Extract the ZIP file to a location with a network connection.
c. Run the Consent User.ps1 file with Windows PowerShell to
consent required permissions.
d. On the sign-in page, sign in using a Global Administrator of
the destination tenant.
e. Select the Consent on behalf of your organization option,
and click Accept to consent permissions to users of your
organization.
f. In the extracted folder, create a CSV file in the extracted folder
and name it as Chats.
g. According to the source chat IDs scanned in step 1 > i, find
the corresponding destination chat IDs in your migration job
report.

h. Copy the IDs of destination chats that you want to hide from
those destination users to the Chats.csv file.
 i. Ask those destination users for which you want to hide the
destination chats to run the TeamChatData.ps1 file with
Windows PowerShell, and sign in with their credentials.

After the job is finished, the chats will be hidden from those
destination users. A report file with the hidden results will be
generated in the tool folder.

3. To migrate the chats to desired destination chat members, update the

user mappings to map source chat members to the destination users,
and rerun the migration job.

Tool to Mark Migrated Messages as Read

After all migrations are finished, your end users (destination chat users) can
run the tool to quickly mark their message as read if necessary.

To mark chat messages as read, refer to the following steps:

1. Access the storage location of tool package and download the ZIP file
of the tool.
2. Extract the ZIP file to a location with a network connection.
3. Ask the end user to run the TeamChatMarkAsRead.ps1 file with
Windows PowerShell.
*Note: Make sure the user’s machine has been installed with the
Microsoft Graph PowerShell module. The module can be installed
by executing the Install-Module Microsoft.Graph -Scope
CurrentUser command.

4. Enter the credentials of the end user to sign in the tool.

The job to mark messages as read will be started.

5. After the job is finished, the end user can click any key on the
keyboard to exit PowerShell.
The mark results of the end user’s chats will be recorded to a CSV file
that is stored in the same folder as the TeamChatMarkAsRead.ps1
file.

Configure the UrlMapping.csv File

Refer to the following steps to configure the UrlMapping.csv file:
1. In the extracted tool folder, open the UrlMapping.csv file.
2. To replace links for specific destination chat users, configure URL
mappings using their full OneDrive site URLs with the current domain
in the Original Url column and with the final domain in the New Url
column, as the screenshot below.

To replace links for all destination chat users, you can configure only
one URL mapping using the current domain name in the Original Url
column and the final domain name in the New Url column for easy
use, as the screenshot below.

3. Save the CSV file.

After the job of replacing links in migrated chat messages finishes, a
CSV file will be generated in the Reports folder to report the link
replacement results. The following notes require your attention:

 If the destination service account 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.