Cross-Forest Mailbox Moves in Powershell

I was recently working on a cross-forest migration from Exchange 2003 to Exchange 2007, and was looking for a way to move the mailboxes across the forests. There didn’t seem to be a single reference that was simple to follow and well explained, so I came up with something that worked for me, and thought it would be useful to share with others. Before you start moving mailboxes willy-nilly, be sure to understand what you’re doing. J Also, for this project, we are using ADMT v3 to migrate user accounts prior to migrating any mailboxes. The idea is that we’ll migrate all of the accounts first and then migrate the mailboxes in one fell swoop – this alleviates the need to worry about long term co-existence scenarios and details such as GAL synchronization.

Preparation information:

The users.csv file contains one sample line to show you what it should look like. Just add the names and OUs of the users that you want to move as shown in the file, save it (I suggest you save these in batches, and change the name of the csv file each time so you can track what has been done - you'll need to change the c:\users.csv reference in the script to reflect the name of the csv file you're referencing).

Users.csv should look like this (it can be more complex and contain more information - this is a simple one that worked for me – you can just use notepad to create the csv file, or Excel if you prefer, but do not that if you use Excel you can only have one worksheet in the file or the csv file won’t open properly for any other applications):

alias,OU
JDoe,domain\users

Put the users.csv file somewhere where it’s easily accessible – I tend to use the root of the c:\ drive, or sometimes c:\temp. You can get wild and create a separate directory to hold the csv file if that suits you.

Once you have your csv file in place (let’s say it’s at c:\users.csv for the purposes of this exercise), open the Exchange Management Shell and type the following:

$creds=get-credential

This command will bring up a dialog box asking for credentials - I used the administrator account because it’s a simple test environment. The account you use will require Exchange Recipient Administrator and Exchange Server Administrator rights in the source forest, and also requires local admin rights on the Exchange Servers in the source forest.

Next is the bulk of the command (major blogger problem alert - apparently the pipe character doesn't show up in posts, which is insanely aggravating. I've used the ^ character in place of the pipe - anyone who doesn't know what a pipe is should read the Unix section of this):

import-csv "c:\users.csv" ^ ForEach-Object -process {move-mailbox -identity $_.alias -TargetDatabase "Mailbox Database" -SourceForestGlobalCatalog ..com -SourceForestCredential $creds -NTAccountOU "CN=Users,DC=,DC=com"}

Note that I have put < > around the items that you will need to customize for your environment – take those out and type in the right things. Also note that the .com may not work in your environment – you may need a .net or a .local or a .somethingelse.

Let me break it down for you:

import-csv "c:\users.csv"

This is referencing the users.csv file I talked about above. It's feeding the information contained in that file into powershell (i.e. the Exchange Management Shell)

^

The above is a (pretend) pipe (darn blogger) - (remember to read the Unix section of this if you don't know what a pipe is or what it looks like) - it says "take the information I just gave you (i.e. the csv file) and do things to it.

Now it gets tricky:

ForEach-Object -process {move-mailbox -identity $_.alias -TargetDatabase "Mailbox Database" -SourceForestGlobalCatalog ..com -SourceForestCredential $creds -NTAccountOU "CN=Users,DC=,DC=com"}

So, for each object named in the csv file, move the mailbox. Breaking that down further:

-identity $_.alias

-identity is used to identify a unique object. The variable $_.alias is found in the csv file - it is the user's alias (JDoe is the alias in the sample csv file). So we're identifying the mailboxes to be moved based upon each alias.

-TargetDatabase "Mailbox Database"

The TargetDatabase is the database to which we're moving the mailboxes. Your target database may be named something other than “Mailbox Database”. Remember to use the quotes if there is a space in the database name.

-SourceForestGlobalCatalog ..com

This tells us that the GC to reference in the source forest is (it can be any GC in the domain - just pick one).

-SourceForestCredential $creds

This references the $creds variable that was created earlier - the administrator account that you typed into the dialog box that popped up early in this exercise.

-NTAccountOU "CN=Users,DC=,DC=com"

This simply tells the script where to look for the user object (or, if the user object doesn't exist, where to create it - because we're migrating the accounts with ADMT first, it is to link the accounts, not to create a new account).

So there you have it - test it first to make sure it will work in your environment - do it at your own risk! (I honestly don't think it's risky, but do pretend there's a disclaimer here similar to the "don't mess with the registry" disclaimer we all love and fear so much.)