OX Outlook Uploader

Revision as of 08:44, 14 July 2010 by Khgras (talk | contribs) (Usage - Interactive mode)

Open-Xchange Microsoft Outlook® Uploader (Beta)

Description

Later this year, Open-Xchange will release Open-Xchange Microsoft Outlook® Uploader for migration of Outlook® PST-files to Open-Xchange Server.

Prerequisites for testing

a) Client
Before the Microsoft Outlook Uploader can be installed, the following requirements must be met on the target machine:

  • Microsoft® Office® Outlook (2002/XP, 2003, 2007 or 2010)
  • Microsoft® .NET Framework 2.0

The installation of the above prerequisites needs elevated rights on the target machine, and might require a reboot.

b) Open-Xchange Server
As migration target, an Open-Xchange server, version 6.16.1 or later is required. Furthermore, the user account for which the data should be migrated should already have been created on the server.

Download

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

Installation

After the download of the package, you can start the installation by double-clicking on the package. On the first screen, you will see some information about the Open-Xchange Microsoft Outlook Uploader. Please follow the installation steps in the wizard.

Usage - Interactive mode

1. Choose the migration source
a. First, either choose a personal storage file (.pst file) or a mail profile to be imported.
b. When having made a selection, click on Next

2. Select a personal storage file to migrate
a. When clicking on Browse the standard folder for saving .pst files opens.
b. As some .pst files are password protected the password can be entered in the second field.
c. When having chosen a file, click on Next.

3. Select a data file from a profile to migrate
a. Select one of the existing profiles from the drop-down menu.
b. Select a store from the profile.
c. Finally, enter a password if needed.
d. To proceed, click Next.

4. Please enter information about the server
a. In the Server URL field, enter the Open-Xchange Server address.
b. Enter your username in the second field.
c. Enter your password in the third field.
d. In order to make further settings, activate the Configure advanced settings checkbox.
e. To proceed, click on Next.

5. Configure advanced options
a. The folder id is preselected but can be changed.
b. In the second field enter the name of the folder in which the E-Mails are to be saved.
c. In case not all mail folders are to be exported from the .pst file, an Outlook folder can be selected by clicking on the Select button.
d. In order to ignore the Trash or Junk folder for the migration, activate the respective checkbox.

6. Migration in process
a. This window displays the status and a log protocol of the migration.
b. When the process is finished, click on Next.

7. Migration completed
a. This window displays an overview of the migration and you can view the log file by clickin on the respective button.
b. To close the wizard, click on Finish.

Misc

Performance considerations:
The time needed to perform a migration correspondents 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 during the migration, and Outlook 2007 should be preferred against Outlook 2003.

Limitations when running multiple instances:
When executing multiple migrations simultaneously 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 log file. 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 appropriate, 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, tim 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.

Reporting of Bugs

Please report bugs and missing features via Open-Xchange Bugzilla. Many thanks in advance for your support.

Product: Product: Open-Xchange MS Outlook Uploader

Installation and configuration for Administrators

Installation for Administrators

The Open-Xchange Microsoft Outlook® Uploader Beta 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 command line 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 command line - so that would be the default pre-configuration):

ADMINUSER []
ADMINPASSWORD []
BATCHMODE [False]
IGNOREJUNKFOLDER [True]
IGNORETRASHFOLDER [True]
IMPORTFOLDERNAME []
LOGAUTOFLUSH [True]
LOGCONSOLE [False]
LOGLEVEL [Info]
LOGTEXTFILE [.\OXUploader.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"

Usage - Configuration

The application's configuration settings can be adjusted in config files, both for the OXUploader.exe main application for interactive mode and for the command line 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.

Furthermore, the application can be started with command line 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)>
batchmode <true/false>
ignorejunkfolder <true/false>
ignoretrashfolder <true/false>
importfoldername <Name of the migration target subfolder>
logautoflush <true/false>
logconsole <true/false>
loglevel <off/error/warning/info/verbose>
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>
uploadchunksize <Number of uploaded mails per request>
uploadthresholdbytes <Threshold of bytes for sending forced>
username <Username on the OX server>
recoverableexceptionmaxretries <max. retries after web error>

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 passed via the command line when starting the tool, see (3). When the parameter "batchmode" is "true", the migration starts automatically. In this case, the following settings have to be available, either supplied via the command line or defined in the configuration file:

  • Username
  • ServerURL
  • PSTFile -or- ProfileName and StoreName
  • Password -or- AdminUser and AdminPassword

For example, tim 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 Misc.