Doc version: v2.0.0

• Microsoft Teams & Chat Migration Planning: Full support for scanning and projecting migration timelines for Microsoft Teams, Channels, and Private Chats alongside Exchange Online.
• Process-Level Decoupling Architecture: Architectural refactoring that decouples the launcher (migration_planner.py) and individual workload planners (migration_planner_exchange.py and migration_planner_chat.py) into isolated OS subprocesses to prevent runtime contention, memory corruption, or GIL clashes during highly concurrent MS Graph API scanning.
• Bidirectional Navigation: Addition of a top navigation bar featuring a ← Back to Selector button for seamless transitions between workload planners.
• In-place Archives: Support for getting the count of emails in the in-place archive (alternatively known as online archive) of users is added.
• Group Mailboxes: Support for getting the thread and mail (also called posts) count for each group provided / present in a tenant is added.

• When starting the estimations, the first progress bar now would display the text Scanning Entities instead of Scanning Users to indicate that we are scanning for both users and groups. Also the count subtext would now show the split of number of users and group mailboxes.
• When using the CSV based flow, script users should specify a new column in the CSV called Type to distinguish users from group mailboxes. Note that this is not needed if group mailbox estimations are not required or if the Full scan mode is being used. Compatible values for this column are User and Group Mailbox.

• While the concurrency numbers set in the Advanced Settings is still linearly proportional to the number of actual active threads, it won't represent the EXACT number of threads being spawned for estimating resources like In-Place Archives and Group Mailboxes. This is by design and is done to balance latency with resource usage.

• The estimations provided by this tool are calculated projections intended for preliminary planning only. Actual migration timelines (ETAs) and batch execution may vary based on real-time network conditions, source/target throttling policies, migration configurations, and the volume of delta migrations. The estimations do not constitute a performance guarantee or a binding service level agreement (SLA).
• Please note that this release is an experimental feature with limited and evolving functionality.
• Partners and/or Customers should NOT use this product for production projects where business outcomes rely on the product functionality or timelines.
• Partners and/or Customers should NOT commit hard migration timelines based on this product.
• By using this tool, you acknowledge that log files generated by this script contain personally identifiable information and that you are solely responsible for securing your local environment and these files.
• Use of this tool is governed by the Apache 2.0 license.

• This tool only provides migration time estimates for the new Data Migration Service with specific enhancements for large scale migrations. It does not cover Google Workspace Migrate, or any other data migration tool.
• Microsoft Exchange Online and Microsoft Teams / Private Chat scan and migration planning is supported. ETAs are based on Email and Chat/Channel corpus projections.
• This tool only provides a guesstimate, and migration timelines should in no way be taken as guarantee or SLA.

• Introduction
• Prerequisites & Installation
  • 1. Python Version
  • 2. Installation Steps
    • Windows
    • macOS
    • Linux (Ubuntu/Debian)
  • 3. Setting up a Virtual Environment (Optional / Corp Policy)
• Setting up Microsoft Azure
  • 1. Register the App
  • 2. Grant Permissions
  • 3. Get Credentials
• Running the Tool & Process Decoupling
• Tool Configuration & Scanning
  • Workflow A: Exchange Online Planner
  • Workflow B: Microsoft Teams & Chat Planner
• Understanding the Results
  • Workflow A: Exchange Online Planner
  • Workflow B: Microsoft Teams & Chat Planner
• Outputs & Artifacts
  • Workflow A: Exchange Online Planner
  • Workflow B: Microsoft Teams & Chat Planner
• Terms & Disclaimer

The Migration Planner is a desktop application designed to help deployment partners and IT administrators assess a Microsoft 365 tenant before migration. Through its process-decoupled architecture, administrators can independently assess Exchange Online (Emails, Contacts, Calendars, In-Place Archives, Group Mails) or Microsoft Teams (Channels, Private Chats) to provide accurate volume metrics and generate optimized Migration Batch Plans with estimated completion times (ETAs).

Please ensure you have Python 3.10 or newer installed on your system.

1. Download Python: Visit python.org/downloads and download the latest installer.
   • Important: Ensure the checkbox "tcl/tk and IDLE" is selected during installation (it is usually selected by default). This installs the necessary GUI components.
   • Important: Check the box "Add Python to PATH" during installation.
2. Verify Installation: Open Command Prompt (cmd) or PowerShell and make sure the following commands run successfully and return you the version ids of python and pip:

   python --version
   pip --version

3. Install Dependencies: Run the following command:

   pip install customtkinter requests pandas psutil Pillow urllib3 aiohttp certifi

1. Download Python: Visit python.org/downloads and download the macOS installer. Alternatively, use Homebrew from the terminal (brew install python).
2. Install Tkinter: If you are using Homebrew or encounter GUI errors, you may need to explicitly install the Tkinter library:

   brew install python-tk

3. Verify Installation: Open Command Prompt (cmd) or PowerShell and make sure the following commands run successfully and return you the version ids of python and pip:

   python3 --version
   pip3 --version

4. Install Dependencies:

   pip3 install customtkinter requests pandas psutil Pillow urllib3 aiohttp certifi

1. Install Python: Python is usually pre-installed. If not, run:

   sudo apt-get update
   sudo apt-get install python3 python3-pip

2. Install Tkinter: Linux often requires the separate Tkinter package:

   sudo apt-get install python3-tk

3. Install Dependencies:

   pip3 install customtkinter requests pandas psutil Pillow urllib3 aiohttp certifi

If your organization restricts installing packages globally, use a virtual environment:

1. Create the environment:

   # Windows
   python -m venv venv
   
   # Mac/Linux
   python3 -m venv venv

2. Activate the environment:
   • Windows: .\venv\Scripts\activate
   • Mac/Linux: source venv/bin/activate
3. Install packages as shown above inside this environment.

To scan your tenant, you need to register an app in the Microsoft Entra ID (formerly Azure AD) portal.

1. Go to portal.azure.com.
2. Navigate to Microsoft Entra ID > App registrations > New registration.
3. Name the app (e.g., "Migration Planner Tool").
4. Select "Accounts in this organizational directory only" (Single Tenant).
5. Click Register.

In your new app, go to API permissions > Add a permission > Microsoft Graph > Application permissions (NOT Delegated), and assign permissions based on the workloads you plan to scan:

• User.Read.All (To list users and enumerate rosters)
• Group.Read.All (To get M365 group and team structures)

• Mail.Read (To count emails)
• Contacts.Read (To count contacts)
• Calendars.Read (To count calendar events)
• MailboxFolder.Read.All (To count emails in in-place archives)
• MailboxSettings.Read (To distinguish user and shared mailboxes)

• Reports.Read.All (To fetch automated M365 activity reports for heuristics estimation)
• Chat.Read.All (To scan private chats and chat memberships)
• ChannelMessage.Read.All (To estimate channel messages across teams)
• ChannelSettings.Read.All (To list channels)
• TeamsActivity.Read.All (To read Teams activity analytics)
• TeamMember.Read.All (To read team memberships)
• Group.Read.All (To list teams)

4. Click Add permissions.
5. Crucial Step: Click "Grant admin consent for [Your Organization]" and confirm "Yes". All status icons should turn green.

You will need three values for the tool:

1. Tenant ID: Found on the app's Overview page ("Directory (tenant) ID").
2. Client ID: Found on the app's Overview page ("Application (client) ID").
3. Client Secret:
   • Go to Certificates & secrets > New client secret.
   • Add a description and click Add.
   • Copy the "Value" immediately (you won't see it again).

1. Open your terminal or command prompt.
2. Navigate to the folder containing the script:

   cd path/to/migration_planner

3. Run the script:
   • Windows: python migration_planner.py
   • Mac/Linux: python3 migration_planner.py (Ensure you are in your virtual environment if you created one).

The launcher window (migration_planner.py) acts as a lightweight CustomTkinter SelectorApp. Clicking either "Launch Exchange Planner" or "Launch Chat Planner" spawns the respective standalone planner (migration_planner_exchange.py or migration_planner_chat.py) as an isolated OS process while the launcher immediately destroys itself.

Both workload planners feature a top navigation bar with a ← Back to Selector button. Clicking this cleanly terminates the active planner process and respawns a fresh migration_planner.py selector session.

• Connect with Microsoft: Enter your Tenant ID, Client ID, and Client Secret.
• User Source:
  • Scan All Users: Automatically fetches every user in your tenant.
  • Upload CSV: Allows you to scan a specific subset of users or pre-load existing counts.
  • CSV Format: Must contain a header Email Id (e.g., user@domain.com). Also if Group Mailbox estimation is required then a column called "Type" is needed to segregate group mailbox IDs from user mailbox IDs. The correct values for Type column are "User", "Group Mailbox".
  • Smart Delta Scan: If your CSV already contains columns like Email Count, Contact Count, Calendar Count, Calendar Event Count, In-Place Archive Count or Group Mail Count, Group Thread Count, the tool will skip scanning those specific items and use your provided numbers, speeding up the process significantly.

Click "Show Advanced Settings" to tune the performance:

• Sources: Check/Uncheck Emails, Contacts, Calendars, In-Place Archives and Group Mails to define what you want to scan.
• Concurrency: Controls how many parallel threads the tool runs.
  • Recommendation: For a standard machine (8 Core, 16GB+ RAM), set this to 30. Setting it too high may cause more frequent throttling errors from Microsoft and consume more resources from your system.
• Max Batches: Defines the upper cap for the number of batches to be generated by the migration plan. In case of very large corpuses, it might not be possible to adhere to this number.

Click "Get Migration Estimates".

• A disclaimer will appear noting that results are estimates. Click OK to proceed.
• The tool will verify your credentials and permissions before starting.

Once started, you will see a real-time progress screen:

• Spinners: Indicate active scanning phases.
• Progress Bars:
  • Show percentage completion for Users, Emails, Contacts, Calendars, In-Place Archives and Group Mails.
  • Each spinner and progress bar should correspond to one of the sources selected for the scan. If a user did not select a certain source, the spinner and progress bar for that source should not be visible.
  • Specifically for In-Place archives the progress bar would also display the number of users for which partial failures were observed.
• Live Counts: Updates in real-time as items are discovered.

• Connect with Microsoft: Enter your Tenant ID, Client ID, and Client Secret.
• User Source:
  • Scan all teams and users: Automatically fetches every team and user in your tenant.
  • Upload CSV: Allows you to scan a specific subset of users/teams or pre-load existing counts.

Click "Show Advanced Settings" to tune the performance and select your estimation mode:

• Estimation Modes:
  • Last 6 Months (Heuristics): Leverages automated M365 activity reports (Reports.Read.All) for instant, high-level tenant estimations without deep scanning. Note: Sizing projections are computed using statistical multipliers based on standard enterprise averages. For precise customer-specific densities, use Deep Scan mode.
  • Deep Scan (Sampling): Performs deep multi-threaded scanning across a customizable percentage of users and teams (e.g., 0.01% to 100%). Statistical Note: Sampling users rather than individual messages may miss high-activity outlier accounts. To capture these outliers, we recommend using a higher sampling rate or uploading a targeted CSV containing known high-volume rosters (such as helpdesks or executive assistants).
• Scan Options: Check or uncheck Private Chats to control scan boundaries.
• Concurrency: Sets async thread limits for channel message extrapolation.

Click "Get Migration Estimates".

• A disclaimer will appear noting that results are estimates. Click OK to proceed.
• The tool will verify your credentials and permissions before starting.

Once started, you will see a real-time progress screen:

• Spinners: Indicate active scanning phases.
• Progress Bars: Show percentage completion for Private Chats and Channels.
• Live Counts: Updates in real-time as items are discovered.

The top cards display the total scope of the Exchange migration:

• Users: Total distinct users identified/scanned.
• Emails / Events / Contacts / In-Place Archives / Group Mailboxes: The aggregate sum of items across all users.

The tool calculates an Estimated Completion Time (ETA) based on the email corpus using a heuristic based logic:

• User Ordering: Users are sorted in Ascending Order (Lightest users -> Heaviest users). The lightest users are packed into Batch 1, while the heaviest users usually end up in the final batches.
• Max(Emails , (Calendar Events + Contacts), In-Place Archives, Group Mails) determines the sorting logic.
• Batch ETAs: Calculated based on the regular emails, in-place archived emails and group mails corpus present in the batch.
• Bucketing: Batches are distributed into Parallel Buckets.
  • Example: If you selected 4 parallel batches, the tool creates 4 "lanes". As soon as Batch 1 finishes in Lane 1, Batch 5 immediately starts in that same lane.
• Total ETA = The duration of the single longest bucket(lane).

The top cards display the total scope of the Chat/Teams migration:

• Users & Private Chats: Total distinct Users, Private Chats, and Private Chat Messages.
• Teams & Channels: Total distinct Teams, Channels, and Channel Messages.

• User & Team Ordering: Entities are sorted in Ascending Order (Lightest entities -> Heaviest entities) to optimize packing.
• Pagination Controls: The results Gantt chart and batch tables include interactive pagination dropdowns supporting 50, 100, 200, or All items per view.
• Total ETA = The duration of the single longest bucket (lane).

Once the scan completes, the tool creates a folder in the /outputs directory named with the current timestamp (e.g., /outputs/20240520_143000/).

It contains:

1. User Report (user_report.csv): A master list of all users, their item counts, and their suggested Batch (e.g., "Batch 1").
2. Batch Files (suggested batches/): Individual CSV files (Batch1.csv, Batch2.csv) ready for use in migration tool. Headers are formatted as Source Exchange Email.
3. Logs (logs.log): Detailed execution logs, including system performance (CPU/RAM) and any API errors encountered.

You can also download just the log file via the "Export logs" button or the user report via the "Export full report" button and save them in a custom location on your system.

Once the scan completes, the tool creates a folder in the /outputs directory named with the current timestamp.

It contains:

1. Teams Report (teams_report_<timestamp>.csv): Master list of analyzed Teams, IDs, channel counts, and assigned migration batch.
2. Batch Files (suggested teams batches/): Individual CSV batch files formatted with the header Source MicrosoftTeamsID.
3. Logs (logs_<timestamp>.log): Detailed execution logs, including system performance (CPU/RAM) and any API errors encountered.

You can also download just the log file via the "Export logs" button or the full report via the "Export full report" button and save them in a custom location on your system.

• Estimates Only: The estimations provided by this tool are calculated projections intended for preliminary planning only. Actual migration timelines (ETAs) and batch execution may vary based on network latencies, Microsoft/Google throttling policies, migration configurations, data complexity (e.g., large attachments) and the volume of delta migrations. These figures do not constitute a performance guarantee or a binding service level agreement (SLA).
• Security: This tool runs locally. No credentials or user data are sent to any external server other than the direct Microsoft Graph API calls required to fetch the counts. Log files generated by this script contain personally identifiable information and that you are solely responsible for securing your local environment and these files.
• Local Database & Storage: To enable scan progress persistence and delta tracking, the tool creates and maintains local SQLite databases in the data/ directory (data/chat_migration_v2.db and data/scan_progress.db). These databases store metadata, estimated item counts, and progress checkpoints entirely locally. No actual chat message contents or emails are stored. The data/ directory can be safely deleted or purged at any time after your estimations are completed to reclaim local disk space.
• License & Additional Terms: Use of this tool is governed by the Apache 2.0 license.
• This is not an officially supported Google product. This project is not eligible for the Google Open Source Software Vulnerability Rewards Program.