Migration Planner Tool

Doc version: v0.5.1

DISCLAIMER

• The estimations provided by this tool are calculated projections intended for preliminary planning only. Actual migration timelines (ETAs) and wave 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.

Functionality Limitations

• 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.
• Only Microsoft Exchange Online scan and migration planning is supported. And ETAs are based on Email corpus only.
• This tool only provides a guesstimate, and migration timelines should in no way be taken as guarantee or SLA.

---

Table of Contents

• 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
• Tool Configuration & Scanning
  • 1. Connect & Source Selection
  • 2. Advanced Settings
  • 3. Starting the Scan
  • 4. The Scan Page
• Understanding the Results
  • 1. Top Level Metrics
  • 2. Timeline Estimates & Parallel Waves
• Outputs & Artifacts
• Terms & Disclaimer

---

Introduction

The Migration Planner is a desktop application designed to help deployment partners and IT administrators assess a Microsoft Exchange Online tenant before migration. It scans source data (Emails, Contacts, Calendars) to provide accurate volume metrics and generates an optimized Migration Wave Plan with estimated completion times (ETAs).

---

Prerequisites & Installation

1. Python Version

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

2. Installation Steps

Windows

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

macOS

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

Linux (Ubuntu/Debian)

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

3. Setting up a Virtual Environment (Optional / Corp Policy)

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.

---

Setting up Microsoft Azure

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

1. Register the App

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.

2. Grant Permissions

1. In your new app, go to API permissions > Add a permission > Microsoft Graph.
2. Select Application permissions (NOT Delegated).
3. Search for and select these four permissions:
   • User.Read.All (To list users)
   • Mail.Read (To count emails)
   • Contacts.Read (To count contacts)
   • Calendars.Read (To count calendar events)
4. Click Add permissions.
5. Crucial Step: Click "Grant admin consent for [Your Organization]" and confirm "Yes". All status icons should turn green.

3. Get Credentials

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

---

Running the Tool

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

---

Tool Configuration & Scanning

1. Connect & Source Selection

• 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).
  • Smart Delta Scan: If your CSV already contains columns like Email Count, Contact Count or Calendar Count and Calendar Event Count, the tool will skip scanning those specific items and use your provided numbers, speeding up the process significantly.

2. Advanced Settings

Click "Show Advanced Settings" to tune the performance:

• Sources: Check/Uncheck Emails, Contacts, or Calendars 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 Waves: Defines the upper cap for the number of waves to be generated by the migration plan. In case of very large corpuses, it might not be possible to adhere to this number.

3. Starting the Scan

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.

4. The Scan Page

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

• Spinners: Indicate active scanning phases.
• Progress Bars: Show percentage completion for Users, Emails, Contacts, and Calendars.
• Live Counts: Updates in real-time as items are discovered.

---

Understanding the Results

1. Top Level Metrics

The top cards display the total scope of the migration:

• Users: Total distinct users identified/scanned.
• Emails / Events / Contacts: The aggregate sum of items across all users.

2. Timeline Estimates & Parallel Waves

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 Wave 1, while the heaviest users usually end up in the final waves.
• Max(Emails , (Calendar Events + Contacts)) determines the sorting logic.
• Wave ETAs: Calculated based on the email corpus present in the wave.
• Bucketing: Waves are distributed into Parallel Buckets.
  • Example: If you selected 4 parallel waves, the tool creates 4 "lanes". As soon as Wave 1 finishes in Lane 1, Wave 5 immediately starts in that same lane.
• Total ETA = The duration of the single longest bucket(lane).

---

Outputs & Artifacts

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 Wave (e.g., "Wave 1").
2. Wave Files (suggested waves/): Individual CSV files (Wave1.csv, Wave2.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.

---

Terms & Disclaimer

• Estimates Only: The estimations provided by this tool are calculated projections intended for preliminary planning only. Actual migration timelines (ETAs) and wave 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.
• License & Addtional 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.