OX Outlook Uploader
Open-Xchange Microsoft Outlook® Uploader (Beta)
Later this year, Open-Xchange will release 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.
Features
- Migration of E-Mails, appointments, contacts, tasks and sticky notes
- Folder structure is preserved, subfolders are created as necessary
- Attachments and participants are preserved
- Support for recurring appointments
- Migration of .pst-files
- Migration of data files from installed mail profiles
- Migration of Microsoft Exchange mailboxes
- Easy to use 3-step interactive wizard to configure the migration
- Unattended mode to perform migrations without user interaction
- Commandline interface to automate batch migrations
Prerequisites
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:
Windows System
- Windows XP and newer or Windows Server 2003 and newer
- Microsoft® Office® Outlook (2002/XP, 2003, 2007 or 2010) or Microsoft® Exchange Server or standalone versions of Extended MAPI (Exchange 5.5 through 2010)
- Microsoft® .NET Framework 2.0
Open-Xchange Server
- Open-Xchange server, version 6.16.1 or later
- The user account(s) for which the data should be migrated should already have been created
Download and installation
Please note that everything from this page and beyond is in Beta: That means that nothing is final, changes will be made before final release, stability is not guaranteed and nothing from this site should be used in production.
To download the Open-Xchange Microsoft Outlook® Uploader (Beta) installation packages and Release Notes, follow this link
The access-data are:
- User name: oxuploaderbeta
- Password: first$cut
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.
Usage (interactive mode)
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
| |
4. Configure advanced options
| |
5. Migration in process
| |
6. Migration completed
|
Usage (unattended mode)
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:
- Username
- ServerURL
- PSTFile or ProfileName and StoreName or ExchangeServerURL
- Password or AdminUser and AdminPassword
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).
Configuration
Configuration files
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.
Commandline 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>
Misc
Performance considerations
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.
Limitations when running multiple instances
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 .
Admin migration
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
Personal storage files
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"
Duplicated items
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 4.8.4.7, 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.
Exchange mailboxes
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:
- Ensure the target account already has been created on the OX server
- Grant the administrating user "Receive As" permissions to the mailbox store of all accounts that should be migrated, details can be found at http://support.microsoft.com/default.aspx?scid=kb;EN-US;821897 and http://msexchangeteam.com/archive/2006/01/25/418099.aspx
- The migration tool is ececuted by the administrative user, who already should be logged on to the exchange domain
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
Administrative installation
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 [25] UPLOADTHRESHOLDBYTES [2097152] OXUSERNAME [] RECOVERABLEEXCEPTIONMAXRETRIES [3]
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"