Open-Xchange provides Open-Xchange Microsoft Outlook® Uploader (short: OXUploader), a migration tool to export data from Microsoft Outlook® or from a Microsoft Exchange Server® to the Open-Xchange Server.
The OXUploader migration tool is installed on a windows system having access to the data that should be migrated. The data is then migrated from there to the Open-Xchange server. Please ensure that the following requirements are met before installing the tool:
To download the Open-Xchange Microsoft Outlook® Uploader installation packages and Release Notes, follow this link
After the download of the package, you can start the installation by double-clicking on the package. Please follow the installation steps in the wizard. The installation does not require administrative rights.
1. Choose the migration source
2a. Select a personal storage file to migrate
2b. Select a data file from a profile to migrate
2c. Select an Exchange Server mailbox to migrate
3. Please enter information about the server
4a. Configure advanced options
4b. Configure advanced options
5. Migration in process
6. Migration completed
The migration tool can be started in a special "batch mode", where no user interaction is necessary. The options for the migration can be set in the configuration files, or passed via the commandline when starting the tool, see (3). When the parameter "batchmode" is "true", the migration starts automatically. In this case, at least the following settings have to be available, either supplied via the commandline or defined in the configuration file:
For example, to migrate the .pst-file "c:\test.pst", a command could look like:
OXUploaderC.exe -batchmode true -pstfile "c:\test.pst" -serverurl "http://ox.example.invalid" -username test -password secret
Multiple instances of the tool can be run simultaneously from one or multiple client machines, more information can be found in (6).
The application's configuration settings can be adjusted in config files, both for the OXUploader.exe main application for interactive mode and for the commandline version of the tool OXUploaderC.exe (see below). The files are named as the corresponding executable, with the file extension ".config": OXUploader.exe.config and OXUploaderC.exe.config respectively. A description of each parameter can be found in Configuration parameters
Furthermore, the application can be started with commandline parameters. All supplied options overwrite the default settings from the configuration file, which are assumed if an option is missing. The following parameters are recognized:
-adminuser <Admin username on the OX server (for admin migration)> -adminpassword <Admin password on the OX server (for admin migration)> -appointmentsmindate <Minimum date of appointments to be migrated> -batchmode <true/false> -clearfolders <true/false> -emailssmindate <Minimum date of e-mails to be migrated> -exchangemailboxname <Name of the Exchange mailbox to migrate> -exchangeserverurl <URL of the Exchange server> -exchangeserverusername <Username on the Exchange server> -exportappointmentparticipants <true/false> -exportappointmentuids <true/false> -ignorejunkfolder <true/false> -ignoresyncissuesfolder <true/false> -ignoretrashfolder <true/false> -importfoldername <Name of the migration target subfolder> -logautoflush <true/false> -logconsole <true/false> -loglevel <off/error/warning/info/verbose> -logonexchangemailbox <true/false> -logpostdata <true/false> -logtextfile <Path to logfile> -migrateappointments <true/false> -migratecontacts <true/false> -migrateemails <true/false> -migratenotes <true/false> -migratetasks <true/false> -password <Password on the OX server> -profilename <Name of the profile> -pstfile <Path to PST file> -pstpassword <Password for the PST file> -serverurl <URL of the OX server> -skipemptyfolders <true/false> -storename <Name of the store inside the profile> -tasksmindate <Minimum date of tasks to be migrated> -uploadchunksize <Number of uploaded mails per request> -uploadthresholdbytes <Threshold of bytes for sending forced> -username <Username on the OX server> -recoverableexceptionmaxretries <max. retries after recoverable error> -suppressnotificationmails <true/false> -skipmailswithnonresolvedrecipients <true/false>
The following chapters contain some advanced information and configration options for the OXUploader migration tool.
The time needed to perform a migration correspondends with the size of the .pst file, of course. So, for large mailboxes, this could be a quite time intensive task, and may be improved in knowledge of the following observations, especially when performing multiple simultaneous batch migrations. The I/O-ratio is about the following: Per each byte read from disk, about 0.65 bytes are written to disk, and 0.12 bytes are sent to the server. This is caused by the fact that the messages read out from the .pst-file are exported to RFC822 .eml files first, then those files are loaded again before finally sending them to the server. Therefore, the throughput of the local file system should be as fast as possible. Since the temporary created RFC822 e-mail files are created in the user's temp folder, it would be best to move the location to a separate location as the .pst-file - another hdd, maybe even a ramdisk for the temp directory would make sense for heavy batch migrations. It's also recommended to temporarily disable virus protection and indexing services during the migration, and Outlook 2007 should be preferred against Outlook 2003.
When executing multiple migrations simulataneously from one machine, each instance of the tool must have exclusive access to the .pst-file it is migrating. Furthermore, each instance must use a different logfile. The tool relies on Outlook, and so it also can't work around Outlooks own limitations, especially as Outlook is designed as client application. More details can be found at the knowledge base article here: http://support.microsoft.com/kb/257757/en-us .
When the server is configured appropiate, the migration tool can also be used to import .pst-files into the OX account of the specified user, without the need to supply the user's password. Therefore, the username and password of a special admin user is needed for authentication against the OX server. For example, to migrate the .pst-file "c:\test.pst" into the account "test", a command could look like:
OXUploaderC.exe -batchmode true -pstfile "c:\test.pst" -serverurl "http://ox.example.invalid" -username test -adminuser admin -adminpassword secret
Sometimes .pst-files are broken our corrupted, and the migration tool may not be able to open them correctly, or opening them takes a very long time when the internal repair operations take place. To reduce the impact of broken .pst-files, it's recommended to check the integrity of the files using Microsofts SCANPST.exe tool, see http://support.microsoft.com/kb/287497 . Sadly this utility is designed to run interactively, but there are some utilities out there that automate the SCANPST.exe tool to be run from the commandline, pointing to the .pst-file to scan, for example cmdscan.exe from http://www.olfolders.de/Lang/English/OLfix/download.htm . Doing so, one would be able to incorporate a SCANPST.exe launch prior a batch call to the migration tool, e.g. the following command could be invoked to scan and repair the .pst file "c:\test.pst", passing the path to the SCANPST.exe location:
cmdscan.exe -rename "c:\Program Files (x86)\Microsoft Office\Office12\SCANPST.EXE" "c:\test.pst"
Migrating the same items into the same target folder multiple times usually results in the items getting duplicated on the server. An exception to this rule are appointments with unique identifiers (UIDs), see http://www.ietf.org/rfc/rfc2445.txt, chapter 18.104.22.168, for details. To avoid importing an appointment with the same identifier multiple times, the server rejects an appointment when the UID already exists on the server. To force the migration of appointments regardless of their UIDs, the tool optionally removes the UIDs from the appointment. The relevant setting is named "ExportAppointmentUIDs", when set to "False", existing UIDs are removed before sending them to the server. Furthermore, the migration tool has an option to clear the folder contents before triggering the export. When "ClearFolders" is set to "True", the target folder is emptied prior to the items being exported. Note that any existing data in these folders will be permanently lost.
Instead of using a local mail profile or a .pst file for migration, it's also possible to logon to and migrate an Exchange mailbox directly. It's recommeded that the migration tool is executed inside the exchange domain by the owner of the mailbox. To perform an administrative migration for other user's mailboxes, the following preconditions must be met:
The administrative migration can only be executed from the commandline in "batch mode", see (5) for details. The mailbox or the name of the user that is going to be migrated needs to be specified inside the commandline parameter "exchangemailboxname". For example, to migrate the mailbox of exchange user "test" to the Open-Xchange account with username "test", combined with admin migration at the OX server (see (6c) for details), one could execute the migration tool in the following way:
OXUploaderC.exe -batchmode true -exchangeserverurl 192.168.0.4 -exchangemailboxname test -serverurl "http://ox.example.invalid" -username test -adminuser admin -adminpassword secret
Or, if the password of the OX user is available:
OXUploaderC.exe -batchmode true -exchangeserverurl 192.168.0.4 -exchangemailboxname test -serverurl "http://ox.example.invalid" -username test -password secret
The OXUploader migration tool itself can be installed without the need for elevated access rights by the end user, as the installer only accesses the local non-roaming application data directory and the HKCU hive in the registry. It can't be installed 'per machine', which means that it is not allowed to set the value of the ALLUSERS msi property to "1". The tool can be pre-configured for the end-users by setting public properties at the commandline for the installation process. These are processed by the installer and then written into the tool's config-file. The following parameters can be adjusted (the values in square brackets that are listed below indicate the default values of the properties when not overridden by the msi commandline - so that would be the default pre-configuration):
ADMINUSER  ADMINPASSWORD  BATCHMODE [False] CLEARFOLDERS [False] EXPORTAPPOINTMENTPARTICIPANTS [True] EXPORTAPPOINTMENTUIDS [True] IGNOREJUNKFOLDER [True] IGNORETRASHFOLDER [True] IMPORTFOLDERNAME  LOGAUTOFLUSH [True] LOGCONSOLE [False] LOGLEVEL [Info] LOGTEXTFILE [.\pst2ox.log] MIGRATEAPPOINTMENTS [True] MIGRATECONTACTS [True] MIGRATEEMAILS [True] MIGRATENOTES [True] MIGRATETASK [True] PASSWORD  PROFILENAME  PSTFILE  PSTPASSWORD  SERVERURL [http://] SKIPEMPTYFOLDERS [True] STORENAME  UPLOADCHUNKSIZE  UPLOADTHRESHOLDBYTES  OXUSERNAME  RECOVERABLEEXCEPTIONMAXRETRIES  SUPPRESSNOTIFICATIONMAILS [True] SKIPMAILSWITHNONRESOLVEDRECIPIENTS [False]
For example, to predefine a Server URL that should be used for the migration afterwards, one would execute e.g.:
"Open-Xchange Outlook Uploader.msi" SERVERURL="http://ox.example.invalid"
While the Open-Xchange server uses SMTP as the only recipient address type, data from Microsoft Exchange might contain several additional address types. To migrate such Exchange data to the Open-Xchange server, each e-mail recipient or particpiant of an appointment or task needs a valid SMTP address. While the migration tool tries to retrieve the SMTP address of message recipients in different ways, sometimes there might be recipients that can't be resolved without a connection to the Microsoft Exchange server / Active Directory and it's global address lists. Especially, this may happen with .pst-files that were created using Microsofts EXMERGE tool. In order to resolve that issue, the OXUploader migration tool can establish a connection to the exchange server and to it's global address list prior migrating a .pst-file to the Open-Xchange server, so that the recipient's SMTP addresses can be resolved. To do so, there are two parameters that can be set to logon to the exchange server prior migrating the .pst-file: ExchangeServerURL and ExchangeServerUsername. The username parameter is optional (if not defined, the identity of the current windows user is used) and normally should not need to be set in batch-mode to prevent a windows logon prompt. For example, to logon to the exchange server at "192.168.0.4" and perform an admin migration for the username "test" in unattended mode, a command could look like:
OXUploaderC.exe -batchmode true -exchangeserverurl 192.168.0.4 -serverurl "http://ox.example.invalid" -username test -adminuser admin -adminpassword secret -pstfile ".\test.pst" -logtextfile ".\test.log"
When migrating an Exchange Public Folders store, the folders are migrated below the root Public Folders folder on the Open-Xchange server. To do so, the user performing the migration must have appropiate permissions to create public folders on the server. Since access rights of the folders are not migrated, custom permissions on the folders should be applied manually afterwards.
This chapter describes all possible configuration parameters that can be found in the OXUploader.exe.config / OXUploaderC.exe.config configuration files or can be passed to the migration tool from the commandline.
Please report bugs and missing features via Open-Xchange Bugzilla. Many thanks in advance for your support.
Product: Open-Xchange MS Outlook Uploader
Portions of the Software may use, include third party software, other copyrighted material or Open Source Software. Acknowledgements, licensing terms and disclaimers for such material are contained in separate agreements. Licensee’s use of such material is governed by the terms of the applicable agreements and can be found on the OX web site, are listed under: http://www.open-xchange.com/de/licenses/open-xchange-microsoft-outlookr-uploader.html
The Open-Xchange Microsoft Outlook Uploader requires the Outlook Redemption library® by Dmitry Streblechenko. As the distributable version of Redemption cannot be used in open source projects, it is not included in the repository. However, for development purposes only, you can download a copy of the library at http://www.dimastr.com/redemption/ and install it on your development PC.
The source code for the Open-Xchange Microsoft Outlook® Uploader is available in a public Subversion repository. To checkout the latest sources, use the following command:
svn --username anonymous checkout https://svn.open-xchange.com/migration/OXUploader
The Open-Xchange Microsoft Outlook® Uploader can be compiled easily using Visual Studio 2008®. For both the interactive and the commandline version of the migration tool, there are C# project files (.csproj) in the PST2OX and the PST2OXc subdirectories (PST2OX is the 'codename' of the migration tool). Just open the project file in Visual Studio and build the project.