Four score and many moons ago, I was working on one of my first projects in Microsoft Consulting Services. This particular customer (a university) shared their Active Directory infrastructure with a hospital. During the course of their business, employees would frequently move between organizations. They maintained two mailboxes (one university mailbox, one hospital mailbox), and as users moved between organizations, would configure one mailbox to forward to the other.
In legacy versions of Exchange, it was only possible to forward mailboxes to a mail-enabled recipient in the Global Address list. This value was stored as an Exchange recipient object in the ForwardingAddress attribute of a user. In Exchange 2010, we included the ability to configure forwarding to an SMTP address, which meant the recipient no longer had to be in the GAL. In an exercise of true creativity, we stored this forwarding recipient SMTP address in an attribute called ... [wait for it] ... ForwardingSmtpAddress. You can learn about it on docs.microsoft.com.
In a corollary conversation, when synchronizing identity to Office 365, neither ForwardingAddress nor ForwardingSmtpAddress. So, when it comes to migrating mailboxes, if that mailbox is configured to forward, we aren't capturing that information.
And thus, this tool was born. The basic premise is that you run it in your Exchange on-premises environment prior to mailbox migrations to capture all of your forwarding address values (in either ForwardingAddress or ForwardingSmtpAddress) and stores them in a CSV. If the value is extracted from ForwardingSmtpAddress, the script resolves the SMTP address and stores that value.
Then, post migration, you can re-run the script in Office 365 and apply the forwarding values back to the mailboxes. Problem solved.
I've revisited this script in an attempt to speed it up, using a server side filter for ForwardingAddress and ForwardingSmtpAddress.
To export, run:
.ExportImport-ForwardingAddress.ps1 -Mode Export -Filename <filename.csv>
To import, run:
.ExportImport-ForwardingAddress.ps1 -Mode Import -Filename <filename.csv>
You can get the updated script at https://gallery.technet.microsoft.com/Forwarding-Address-Import-5b3ead8e.