Pre-Migration Checks

The checks to run before your first migration, and before Cutover, so jobs don't fail partway through.

Run through this list before your first migration, and again before Cutover.

1. Test both connections

On Workspaces, click the edit icon on your workspace. Enter each client secret again, because saved secrets aren't shown. Then click Test Connection for the Source Tenant and the Target Tenant.

Test Connection signs in as the app registration and checks the following.

Both tenants:

  • The app can sign in with the tenant ID, client ID and client secret.
  • The app can read organization information, groups and users.
  • GroupMember.Read.All and User.Read.All are granted.

Source tenant:

  • Group.Read.All and Domain.Read.All are granted.

Target tenant:

  • Group.ReadWrite.All is granted.
  • The tenant has an active Exchange Online subscription. Distribution groups can only be created where Exchange Online is set up.
  • Exchange.ManageAsApp is granted. If it's missing, you get a warning rather than an error, but distribution group migrations will fail without it.

A passing test shows Source credentials validated successfully or Target credentials validated successfully, plus the permissions that were found. If a test fails, the errors listed under it say what's missing. See Troubleshooting.

2. Check what Test Connection can't

Test Connection doesn't check these, so confirm them yourself in the Entra admin center:

  • Admin consent is granted for every permission on both apps. Each one should show Granted in the Status column.
  • Source app: Exchange.ManageAsApp is added, and the app has the Global Reader or Exchange Recipient Administrator role. Without both, owners and Exchange settings can't be read.
  • Target app: the app has the Exchange Administrator role.
  • Role assignments have had time to take effect. This can take up to an hour.
  • Client secrets won't expire during the project. If one does, create a new one and enter it on the workspace.

3. Check your licenses

On the Dashboard, the license card shows how many licenses are in use and how many remain. Make sure you have enough for the groups you plan to migrate that don't have a license yet. See Migration Planning.

4. Check user mapping

On User Mapping:

  • The unmapped count is zero, or only includes people you've decided to leave out.
  • Every Group owner is mapped.
  • The target users already exist in the target tenant.

See User Mapping.

5. Test with a few groups

Run Pre-Stage on two or three groups first. Then check in the target tenant that the groups have the right members, owners and settings, and that the job shows no Failed groups.

Before Cutover

  • Your email domain has been moved to the target tenant and verified there. Cutover fails for any group whose original domain isn't verified in the target.
  • Every group you're cutting over has been Pre-Staged.
  • You've chosen the same Target Domain you used for Pre-Stage.
  • You've rerun Pre-Stage recently, so new members are in the target groups.