How to prevent ADMT from breaking Exchange migrations

When you’re asked to perform an inter-forest mailbox migration, it’s likely that users are to be migrated to a new AD forest as well. There are multiple approaches into achieving this, but looking at Microsoft’s Exchange 2010 Cross-Forest Migration Step by Step Guide, it basically boils down to two methods:

Migration scenarios according to Microsoft
Migration scenarios according to Microsoft

Since my target is a green-field forest with just an Exchange (2013) installation, I opt for method 1, meaning my process will look as follows:

a. Run Prepare-MoveRequest.ps1 script
b. ADMT user object
c. Create a new mailbox move request using the New-MoveRequest cmdlet

Process Break-down

a. Run Prepare-MoveRequest.ps1 script
Why would you use this?
When moving users to a new AD(/Exchange) forest, you will move them to a ‘new world’. In this new world, there are some technical relations to the old world, but these two maintain no shared knowledge of each other. Simply put: there is no shared Global Address List (GAL), so when a user and its mailbox is migrated to the new world, it disappears from the old world. Users may still be able to exchange e-mail messages to one another, in some situations, but they would have to know their e-mail addresses since the GALs would be separate. The new world GAL only contains entries of users who have been migrated, the old world GAL would contain only users that are yet to be migrated.

The prepare-moverequest script will create a mail-enabled user (MEU) in the target forest. This is a new user object with merely some of the required msExch as a placeholder MEU to create consistent GALs across forests. In addition, this MEU has an X500 address for with reference to the mailbox location in the old Exchange forest. This is required for a user to be able to find his/her mailbox.

How to use it?
The prepare-moverequest.ps1 PowerShell script comes with Exchange 2010 SP2 and up. This script is to be executed from the Exchange Management Shell on an Exchange server. The script is located in:
\Scripts (by-default on Exchange 2010: C:\Program Files\Microsoft\Exchange Server\V14\Scripts).

For the Exchange 2010 edition of the script reference page, please refer to:

Running this script (on either version) creates a mail-enabled user in the target forest. This is a regular (yet disabled) AD user account with only the following Exchange attributes:

  • mail
  • mailNickname
  • msExchBlockedSendersHash
  • msExchMailboxGuid
  • msExchPoliciesExcluded
  • msExchRecipientDisplayType
  • msExchRecipientTypeDetails
  • msExchSafeSendersHash
  • msExchUDMtmfMAP
  • msExchUserCulture
  • msExchVersion
  • proxyAddresses

By running the prepare-moverequest.ps1 script, these fields are populated with data from the source forest. This is required to:

  1. maintain a consistent GAL across forests
  2. maintain interorg mail flow
  3. maintain mailbox access once the mailbox is moved to the target forest

b. ADMT user object

The Active Directory Migration Toolkit (ADMT) set is used to migrate all types of AD resources, such as users, computers and groups. Upon launching the ADMT user migration part, it will throw a lot of wizard pages at you, one being the ‘excluded attributes’. This is particularly tricky as – by default – ADMT reads the AD schema to determine available user attributes. If there is a schema mismatch and thus fails to migrate certain attributes, it will tell you in the log after user migration. In addition, ADMT will – again, by default – not exclude any attributes. The aforementioned ‘prepare-moverequest.ps1’-generated attributes aren’t excluded either. As a result, running ADMT with default settings will overwrite all ‘prepare-moverequest.ps1’-generated attributes.

One attribute in particular that is really effective at breaking your migration process is the ‘msExchRecipientTypeDetails’-attribute. When this is overwritten by ADMT it will reset the attribute from 128 (mail enabled user) to 1 (user mailbox). When this happens, you won’t directly notice the issue in this step, nor are users bothered by it. However, you will not be able to continue migration.

As a matter of fact, the prepare-moverequest.ps1 script and new-moverequest cmdlet are the only tools that are intended to write mail-related attributes to user objects. ADMT should never be used for mail attribute migration. Additionally, ADMT may be used for all non-mail related attributes.

When running the user migration wizard, be sure to check the ‘exclude attributes’ checkbox and select all mail-related attributes (mail, proxyaddresses and msExch…) attributes for exclusion.

c. Create a new mailbox move request using the New-MoveRequest cmdlet
As stated in the part above, when ADMT is used to migrate all user attributes, including mail-related attributes, this is the part where the migration will effectively fail with the following error:

The target recipient must be a mail-enabled user
The target recipient must be a mail-enabled user

To prevent this, make sure all mail-enabled attributes are excluded from the ADMT migration portion. By doing so, you’ll be able to successfully migrate mailboxes and clean-up your source forest.

Happy migrating!

  1. This is exactly what is happening to me, but I cannot seem to get past it. I am running ADMT 3.2 on Windows 2012, cross forest moving from Exchange 2013 to 2013. I have excluded all msExch named attributes, plus mailNickname, but I still get the same error. Any ideas?

    1. Hi Leo,

      Basically you need to exclude all the Exchange attributes. So in addition to excluding all the obvious Exchange attributes, please also exclude:
      – ProxyAddresses
      – HomeMBD
      – HomeMTA

      For a list of all attributes:
      Let me know if it helped!

      – Office365Man

Leave a reply

Your email address will not be published. Required fields are marked *