Groupware sync guide

= Install and sync instructions =

Introduction
The BionicMessage GroupWare Sync server is a custom distribution of the Funambol 6.5.14 Device Sync server intended for use with GroupWare servers that implement the GroupDAV standard. There are additions such as the Citadel email connector and a groupware authentication backend.

Other useful documents
Basic documentation for Funambol v6.5 is available from the Funambol Open Source download page.

The Funambol Administration guideis particularly useful for post-install configuration.''

Installation
'''NOTE: As the install script mentions Funambol will come up on port 8080. You may already have something running on this port. If you do, shut it down for now. You can change the port Funambol is on after the install script is done'''

The setup process has changed from the previous bundles. The installation of the server is now done by a script launched automatically by the extractor binary. If you downloaded the 'BYO JRE' version, you will need to:

ln -s /opt/jdk1.5.0 java #symbolic link to existing jdk ./install.sh #Run installer

The install script will ask for the server you are using, the server and port its webserver is on. If you are running Citadel, you will also be asked for the server the Citadel is actually running on.



For the initial install you need to answer 'y' to the Funambol install script when it asks to create the databases.

After Funambol has installed itself, the install script will then bring up the server. Once the server is running post-configuration occurs. You will be asked if you wish to authenticate users against your groupware server, or stay with the default Funambol method of creating users in its database with any credentials they use.



During post configuration a set of sync sources are automatically set up, so if everything is done right, thats all you need to do to start syncing!

Configuring your device and syncing
You will need to configure your device's SyncML software with the following information:

With this configuration you should be ready to sync all your data. Where possible, on first sync, do each data type separately incase one of them fails.

= Advanced administration topics =

Structure
Note the layout of the server bundle:

Funambol administration tool
The Funambol administration tool can be used to configure GroupDAV sync settings and other aspects of the Funambol server, such as authentication.

Lauch it by entering the admin/bin directory and running funamboladmin:

cd admin/bin

./funamboladmin Note: Users of OS X Leopard will have to launch the administration tool another way due to a bug:

sh platform6/lib/nbexec --clusters funamboladmin

After startup, login, by going to the File menu and clicking login.

There may be a delay when logging in, be patient.

If login fails, stop and start server again to be sure. If problem persists, see the troubleshooting section.

The left hand pane of the Funambol administration tool lists available configuration options and modules. Of interest to us is the ‚'groupdav' module. Expanding Modules->groupdav->BionicMessageGroupDAVConnector shows two choices:


 * Calendar (including task sync)
 * Contacts

Double clicking on contacts or calendar will take you to a source configuration screen.

Sync source configuration options
Each sync source has various configuration options:

Click ‚Save settings to activate the sync source. Should you want to reconfigure it later, just expand the Calendar/Contact type node.

CalDAV based time filtering
As of GroupDAV Connector 2.2, the connector can obtain a list of objects from the server via a CalDAV query. This functionality can be used to filter the events processed by the connector and eventually synced to the device. At the time of writing this functionality has only been tested on eGroupware SVN versions.

Setting up proper encoding for SIF based sources (older Funambol clients)
As of Funambol 6.5.14 these steps are no longer required for newer clients, but some clients, such as the Java Demo/Test client still need it.

When using SIF based sync sources (i.e text/x-s4j-sif*), the data coming in and out of the sync source needs to be 'wrapped' in a way that separates it from the SyncML stream, which is also XML. Base64 encoding is used to achieve this. Also, you can encrypt the data with DES for added security.


 * 1) Click on Server Settings in the administration tool tree
 * 2) Click Configure on the Data Transformation Manager row.
 * 3) Click the + ‚plus button on the Data Transformations group to add a new configuration row, and enter in the SyncML ID of the sync source, and ‚b64, respectively.

For more information, see ‚'Manually Enabling Encryption/Encoding' in the Funambol Administration guide.

Syncing calendars and tasks on Symbian (S60/UIQ) devices

 * Note: The install script creates a special source for Symbian devices: 'groupdav-s60-v'.

Symbian S60 devices sync the calendar and todo as a whole and need special treatment by the connector. All you need to do when creating a sync source is:


 * Click on the empty row below the default calendar source and add a new one: tasks pointing to your servers task source, i.e ‚/groupdav/Tasks/ for Citadel.

Note the output type should be text/x-vcalendar

Sync sources configured for S60 devices cannot be used by other devices/clients.

Post-sync configuration for Palm Synthesis event sync
After the first sync, you need to configure the timezone for your Palm device in the Funambol administration tool. As you did in the post-install configuration, start and log into your Funambol server.


 * 1) Double-Click the Devices node in the left pane to access the devices panel
 * 2) List all the devices known to the server by clicking the ‚Search button
 * 3) Select your device from the table and click ‚Edit
 * 4) Select your timezone from the dropdown
 * 5) Tick Convert dates to this timezone
 * 6) Fill in the type and description fields to keep Funambol happy.
 * 7) Click Save.
 * 8) Configure Synthesis to sync against your GroupDAV Calendar sync source
 * 9) Sync.

Citadel Push Email
The install scripts will install the Citadel Email connector if you specified the Citadel server type during install time. You can use this to achieve "Push Email" functionality with Citadel and clients such as:
 * The Funambol Windows Mobile (PocketPC and Smartphone) client (recommended)
 * The Funambol J2ME client (Many modern mobile phones)

Options for push notification
Currently there are two methods available to send a new email notification to a phone:
 * Using Funambol's CTP server technology - which keeps an open TCP session between the phone and server (even behind operator NAT).
 * Using a SMS gateway (i.e Clickatell) to send a WAP Push message

CTP has an advantage in that there is no cost per message, but will drain battery, and seems to take a megabyte or two per day on top of any email traffic. If CTP sessions drop due to network or device problems the session usually does not come back until the user manually syncs. SMS has an advantage in that it will not drop battery, but there is a small cost per message.

Note: When the default notification type is changed devices will have to be deleted within the Funambol admin tool and then resynced in order to use them.

CTP Server
The CTP server has been included with the bundle distribution, and should be a 'plug and play' affair. However, you first have to set JAVA_HOME:

From the root dir of the bundle (i.e where ./install.sh is): export JAVA_HOME=`pwd`/java # or where your JRE is cd ctp-server bin/ctpserver.sh start # append -debug for console output

SMS notification
The bundle includes the 'BMClickatell' notification configured to use the Clickatell SMS gateway, however, is capable of using equally capable gateways provided they have a HTTP API.

To use SMS notification, run postreconfig while the server is running: ./postreconfig.sh setusepostnotify

You then need to use the administration tool to set your username, password and API ID detail. The SMS component is under smsnotify->bmclickatell.

For each user and device you wish to use push with you need to set its phone number, in international format (i.e 61430004010 for an Australian mobile number) in the Devices section of the Funambol admin tool.

URL field format
Should you wish to use the SMS notification component with another gateway, consider the URL format: http://api.clickatell.com/http/sendmsg?api_id=%s&user=%s&password=%s&to=%s&udh=%s&data=%s When using a different gateway you must specify the URL fields in the exact same order.

Configuring Citadel to notify Funambol when new email arrives
Citadel needs to be configured to tell Funambol when email arrives. This needs to be done on two levels: system and user.

The system configuration involves entering the Funambol server, sync source and administrator password in Citadel. This can be done via Webcit or the command line Citadel client by logging in as the Administrator and going to the site configuration. Each user wishing to use push email then needs to login via webcit and goto their Advanced settings page and then to Edit your push email settings and set their preference to use Funambol.

Enabling verbose logging
In the Funambol administration tool, logging can be configured in Server Settings->Logging. Turning up the verbosity can reveal more about server and connector operations.

Enabling debug mode logging
For security reasons, Funambol doesn't disclose the contents of sync items in the log file. This behavior can be changed by changing -Dfunambol.debug=false to -Dfunambol.debug=true

Tomcat stderr file
tools/tomcat/catalina.out catches stdout and stderr output, which often contains exceptions which miss the logger.

Connector/Store logs
Connector and store logs for each sync source can be found in the store directory you configured for your sync source. These log communication with the GroupDAV server and any errors encountered by the sync source.

Installing connector updates
The server bundle contains a custom updating tool called fnbl-get, which will compare timestamps of the module archives in your ds-server installation to those on the server, and offer to upgrade them while keeping configuration in place.

To run the updater you have to stop the server first and then run the update script:

./stop.sh ./upgrade-modules.sh

For each module installed fnbl-get will compare the modification timestamps and offer to download a new version. After downloading all updates, the Funambol module installer script will run, and like the initial setup, ask if you want to overwrite the database for each module. As each module is already installed you should answer 'n' when asked.

Forcing a module update
If need be, you can force fnbl-get to download the latest version by setting the timestamp of the module archives back, by using the touch command: touch -t 197001010101 ds-server/modules/bmclickatell.s4j touch -t 197001010101 ds-server/modules/groupdav-2.1.s4j