Prepare Mailboxes for Cross-Forest Moves Using the Prepare-MoveRequest.ps1 script in the Shell

[This topic is in progress.]

Microsoft Exchange Server 2010 supports an online mailbox move using the New-MoveRequest cmdlet. You can move a mailbox from a source Microsoft Exchange forest to a target Exchange Server 2010 forest.

To run New-MoveRequest, a mail user must exist in the target Exchange forest and the mail user must have a minimum set of required Active Directory attributes.

The sample Windows PowerShell script described in this topic supports this task by synchronizing mailbox users from an Exchange 2010, Exchange 2007, or Exchange 2003 source forest to Exchange 2010 target forests as mail-enabled users. The script copies the Active Directory attributes of the mailbox users in the source forest to the target forest and then uses the Update-Recipient cmdlet to turn the target objects into mail-enabled users.

For more information about using and writing scripts, see Scripting with the Exchange Management Shell. For more information about preparing for cross-forest moves, see Prepare Mailboxes for Cross-Forest Move Requests.

Prerequisites

• Download the sample Windows PowerShell script from the Prepare for Online Mailbox Move page in the Microsoft Download Center.
• To run this sample script, you need the following:
  • A source forest running Exchange 2003, Exchange 2007 or Exchange 2010, where the mailbox currently resides.
  • A target forest with Exchange 2010 installed, where the mailbox will be moved to.

Use the PrepareMoveRequest.psi script

Run the script from the Exchange Management Shell on an Exchange 2010 server role in the target Exchange 2010 forest. The script copies the mailbox attributes from the source forest.

To assign a specific authentication credential for the remote forest domain controller, you must first run the Windows PowerShell Get-Credential command and store the user input in a temporary variable. When you run the Get-Credential command, the command asks for the user name and password of the account used during authentication with the remote forest domain controller. You can then use the temporary variable in the Prepare-MoveRequest script. For more information about the Get-Credential command, see Get-Credential.

First, run the following command.

$LocalCredentials = Get-Credential
$RemoteCredentials = Get-Credential

Then, run this command.

Prepare-MoveRequest.ps1 -Identity JohnSmith@Fabrikan.com -RemoteForestDomainController DC001.Fabrikam.com -RemoteForestCredential $RemoteCredentials -LocalForestDomainController DC001.Contoso.com -LocalForestCredential $LocalCredentials

The following table descibes the parameter set for the script.

Parameter set of the Prepare-MoveRequest script

Parameter	Required	Description
Identity	Required	The Identity parameter uniquely identifies a mailbox in the source forest. Identity can be any of the following: Cn Alias ProxyAddress objectGuid displayname
RemoteForestCredential	Required	The RemoteForestCredential parameter specifies the administrator who has permissions to copy data from the Active Directory of the source forest.
RemoteForestDomainController	Required	The RemoteForestDomainController parameter specifies a domain controller in the source forest where the mailbox resides.
DisableEmailAddressPolicy	Optional	The DisableEmailAddressPolicy parameter specifies whether the Extensible Authentication Protocol (EAP) should be disabled when creating a new MailUser in the target forest. When you specify this parameter, the EAP in the target forest will not be applied. Note: When you specify this parameter, the MailUser will not have e-mail address mapping in the local forest domain stamped. This is usually stamped by EAP.
LinkedMailUser	Optional	Add the LinkedMailUser switch parameter to create a linked mail user in the local forest for the mailbox user in the remote forest. If the parameter is provided, the script creates a target MailUser that is linked to the source mailbox. If the parameter is omitted, the script creates a regular target MailUser. For more information, see Create a Linked Mailbox.
LocalForestCredential	Optional	The LocalForestCrendiatial parameter specifies the administrator with permissions to write data to the Active Directory of the target forest. We recommend that you explicitly specify this parameter to avoid Active Directory permission issues. If the remote forest and the local forest have a trusted relationship configured, don't use a user account from the remote forest as the local forest credential, even though the remote user account may have permission to modify Active Directory in the local forest.
LocalForestDomainController	Optional	The LocalForestDomainController parameter specifies a domain controller in the target forest where the mail-enabled user will be created. We recommend that you specify this parameter to avoid possible domain controller replication delay issues in the local forest that could occur if a random domain controller is selected.
MailboxDeliveryDomain	Optional	The MailboxDeliveryDomain parameter specifies an authoritative domain of the target forest so that the script can select the correct source mailbox user’s proxyAddress as the target mail enabled user’s targetAddress. By default, the primary SMTP address of the source mailbox user is set as the targetAddress of the target mail-enabled user.
TargetMailUserOU	Optional	The TargetMailUserOU parameter specifies the Organizational Unit under which the target mail-enabled user will be created.
UseLocalObject	Optional	If the script detects an object in the local forest that conflicts with the to-be-created mail-enabled user, you can use the UseLocalObject parameter to convert the existing local object to the required target mail mail-enabled user.

Examples

EXAMPLE 1

This example provisions a single linked mail-enabled user in the local forest, when there is forest trust between the remote forest and local forest.

First, run the following commands.

$LocalCredentials = Get-Credential
$RemoteCredentials = Get-Credential

Then, run the following command.

Prepare-MoveRequest.ps1 -Identity RobertJames@Contoso.com -RemoteForestDomainController DC001.Fabrikam.com -RemoteForestCredential $RemoteCredentials -LocalForestDomainController DC001.Contoso.com -LocalForestCredential $LocalCredentials -LinkedMailUser 

EXAMPLE 2

The script supports pipelining if you supply a list of mailbox identities.

First, run the following command.

$UserCredentials = Get-Credential

Then, run the following command.

"IanB@Contoso.com", "JoeSm@Contoso.com" | Prepare-MoveRequest.ps1 -RemoteForestDomainController DC001.Fabrikam.com -RemoteForestCredential $UserCredentials

EXAMPLE 3

You can generate a CSV file containing a list of mailbox identities from the source forest, which allows you to pipe the content of this file into the script to bulk create the target mail-enabled users.

For example, the content of the CSV file can be:

Identity:

Ian@contoso.com

John@contoso.com

Rachel@contoso.com

This example calls a CSV file to bulk create the target mail-enabled users.

First, run the following command.

$UserCredentials = Get-Credential

Then, run the following command.

Import-Csv Test.csv | Prepare-MoveRequest.ps1 -RemoteForestDomainController DC001.Fabrikam.com -RemoteForestCredential $UserCredentials

Script Behavior per Target Object

This section describes how the script performs in relation to the following scenarios for target objects:

• Duplicate target mail-enabled object
• Mail-enabled user
• Mail-enabled contact
• LegacyExchangeDN

Duplicate Target Mail-Enabled Object

When the script attempts to create a target mail-enabled user from the source mailbox user, and it detects a duplicate local mail-enabled object, it uses the following logic:

• If source mailbox user’s masterAccountSid equals any target object’s objectSid or masterAccountSid, then:
  • If the target object is not mail-enabled, the script returns an error because the script doesn’t support converting a non-mail-enabled object to a mail- enabled user.
  • If the target object is mail-enabled, the target object is a duplicate.
• Or, if an address in the source mailbox user’s proxyAddresses (smtp/x500 only) equals an address in a target object’s proxyAddresses (smtp/x500 only), then the target object is a duplicate.

The script prompts the user about the duplicate objects.

If the target mail-enabled object is a mail-enabled user or contact, which is most likely created by a cross-forest (Identity Lifecycle Management 2007 Service Pack 1 based) GALSync deployment, then the user can run the script again with the UseLocalObject parameter to use the target mail-enabled object for mailbox migration.

Mail-Enabled User

If the target object is a mail-enabled user, the script copies the following attributes from the source mailbox user to the target mail-enabled user:

• msExchMailboxGUID
• msExchArchiveGUID
• msExchArchiveName

If the LinkedMailUser parameter is set, the script copies the source objectSid/masterAccountSid.

Mail-Enabled Contact

If the target object is a mail-enabled contact, the script deletes the existing contact and copies all its attributes to a new mail-enabled user. The script also copies the following attributes from the source mailbox user:

• msExchMailboxGUID
• msExchArchiveGUID
• msExchArchiveName
• sAMAccountName
• userAccountControl (set to 514 //equivalent to 0x202, ACCOUNTDISABLE | NORMAL_ACCOUNT)
• userPrincipalName

If the LinkedMailUser parameter is set, the script copies the source objectSid/masterAccountSid.

LegacyExchangeDN

When the Update-Recipient cmdlet is called to convert the target object into a mail-enabled user, a new LegacyExchangeDN is generated for the target mail-enabled user. The script copies the LegacyExchangeDN of the target mail-enabled user as an x500 address to the proxyAddresses of the source mailbox user. This action ensures the correct resolution of recipients when messages are sent between the source and target forests.