OX6:OXtender for Business Mobility Installation Guide

Revision as of 14:14, 1 September 2009 by Mheiland (talk | contribs) (Upgrade from a previous version)

Installation of the OXtender for Business Mobility

Description

The OXtender for Business Mobility is an extension to the Open-Xchange Server enabling Exchange ActiveSync capabilities. ActiveSync is a widespread proprietary protocol developed by Microsoft which allows mobile devices to communicate with groupware servers or desktop computers. Client-side implementations of ActiveSync are available for Windows Mobile, Apple iPhone, Symbian, BlackBerry and Android devices. The protocol covers a very large amount of business smartphones and handheld computers. Since Open-Xchange is able to communicate through native ActiveSync, there are no third party clients required on compatible devices. Integration to the native applications of the specific device is more seamless than with any other synchronization technology. ActiveSync supports synchronization of E-Mail, appointments, contacts and tasks by polling, manual sync or push.

Components

With the OXtender for Business Mobility, Open-Xchange also introduces the Universal Synchronization Module (USM). This module provides a framework for synchronization protocols such as Exchange ActiveSync (EAS) or other services building on this foundation. USM acts as a layer between the Open-Xchange HTTP API and the synchronization protocol. It handles synchronization specific tasks like conflict management. The synchronization stack (USM) and protocol implementation (EAS) are shipped as OSGi bundles and run as a plug-in of an Open-Xchange instance.

Component Overview

USM, EAS and OX work together as components. This is a general outline about how these components interact.

When the device initiates a synchronization through ActiveSync, it contacts the webserver using the URL /Microsoft-Server-ActiveSync via HTTP/s. This URL is forwarded to the Open-Xchange application server where the corresponding servlet is offered by the EAS component. The EAS component then uses USM to initiate a connection to the OX HTTP API and exchanges groupware data. In all cases, USM works as an client to the Open-Xchange HTTP API. It also uses some database tables which are accessed through the Open-Xchange SQL interface to store metadata like synchronization status. The same component stack is used to transport groupware data back to the device.

Requirements

Since the OXtender for Business Mobility is a server plug-in based on the OSGi Framework it can be added to an existing Open-Xchange installation very easily. Open-Xchange Server 6.10 or later is required to operate this extension. The OXtender for Business Mobility uses the resources and services offered by the Open-Xchange server, no additional software or configuration is required.

Please Note: To get in favor of the latest minor features and bugfixes, you need to have a valid license. The article Updating OX-Packages explains how that can be done.

Upgrade from a previous version

It is very important to know that updating your installation requires a bit more than just installing the latest packages. Some additional tasks need to be executed by the administrator to successfully upgrade the USM installation.

Please follow these steps to do so:

After downloading the packages, they can be installed using the operating systems package manager. For example:

dpkg -i open-xchange-usm_6.11.0.0-4_all.deb

This will extract the package and configure the integration to the Open-Xchange server.

Please make sure that if you have chosen to not overwrite the existing configuration file during the package installation process, you need to merge the new settings in the newly created /opt/open-xchange/etc/groupware/usm.properties.dpkg-new file to the existing file, or just overwrite the old one with the new one and redo your configuration settings.

Now the Open-Xchange Groupware daemon needs to be shut down:

/etc/init.d/open-xchange-groupware stop

The next step is to purge some database tables, as the USM installer is not able to do this step on his own at the moment. To do so please execute the following mysql commands. Afterwards you need to re-run the updatetasks once again. This is done by resetting the database version of the OX database which will trigger all relevant updatetasks. Note that the database name for Open-Xchange Server mentioned in this example can be different, depending on your setup.

mysql> USE oxdatabase_6;
mysql> DROP TABLE USMSessionFields;
mysql> DROP TABLE usmSessionIdSequenceTable;
mysql> DROP TABLE USMDataStorage;
mysql> DROP TABLE usmIdMapping;
mysql> DROP TABLE usmIdSequenceTable;
mysql> DROP TABLE easUIDMapping;
mysql> DROP TABLE USMSession;
mysql> DROP PROCEDURE get_usmIdSequenceTable_id;
mysql> DROP PROCEDURE get_usmSessionIdSequenceTable_id;
mysql> UPDATE version SET version=33;

Finally the Open-Xchange Groupware daemon needs to started again:

/etc/init.d/open-xchange-groupware start

New Installation

After downloading the packages, they can be installed using the operating systems package manager. For example:

dpkg -i open-xchange-usm_6.11.0.0-4_all.deb

This will extract the package and configure the integration to the Open-Xchange server.

Since the USM package provides some additional database tables, it is required to re-run several updatetasks after the installation. This is done by resetting the database version of the OX database which will trigger all relevant updatetasks. Note that the database name for Open-Xchange Server mentioned in this example can be different, depending on your setup.

mysql> USE oxdatabase_6;
mysql> UPDATE version SET version=33;

Please restart the Open-Xchange Server after adding this plug-in and applying the database modification. On the first login of a user after the restart, all required database tables will be created.

Configuration

Open-Xchange configuration

The configuration for USM and the EAS protocol can be found in the two configuration files:

/opt/open-xchange/etc/groupware/usm.properties
/opt/open-xchange/etc/groupware/eas.properties

Make sure that the following two parameters are properly set:

In usm.properties

com.openexchange.usm.access_check_module=syncml

and in eas.properties

com.openexchange.usm.eas.access_check=false

Documentation about the configuration parameters can be found inside the configuration file. After the installation is complete, the Open-Xchange groupware needs to be restarted, after that USM and EAS services are available.

Apache Configuration

Mobile devices supporting ActiveSync use a special URL to communicate with the ActiveSync enabled server. This URL needs to be forwarded to the Open-Xchange ActiveSync servlet. When using Apache 2 and mod_proxy_ajp, this servlet can simply be added to the webservers proxy_ajp configuration:

ProxyPass /Microsoft-Server-ActiveSync ajp://127.0.0.1:8009/Microsoft-Server-ActiveSync smax=0 ttl=60 retry=5

The example assumes that the Open-Xchange server is running on the same machine like the webserver. Please refer the Open-Xchange administrator documentation for more information about Apache configuration. Please restart apache after performing the configuration change.