Revision 1
Sunday, 10 June 2007
Components of the Citadel Push Email solution have been developed under my free time under a
view of a starting a business should demand warrant; Due to this I do not accept any direct
donations, however, I am willing to work under contract should you have any needs that need to be
fulfilled.
http://bionicmessage.net
The Citadel Email connector for Funambol was coded in Australia from local and imported code :)
Additional Literature
Documention for various aspects of Funambol 5 is available from
http://forge.objectweb.org/project/showfiles.php?group_id=96&release_id=1981
Documention for the PocketPC client is available from
http://forge.objectweb.org/project/download.php?group_id=96&file_id=8210
The Citadel Email Connector follows a similar design to the Funambol GroupDAV Connector (
http://bionicmessage.net/funambol/ ), and documentation for it is helpful here too. In particular, the
install process for the GroupDAV connector has been documented at the OpenGroupware
Documentation Project - http://docs.opengroupware.org/search?SearchableText=Funambol
1 Funambol 6 stable has been released at the time of writing; however, until Funambol 6 can be stability proven with
the connector stay with 5 instead.
2 Despite the notification component being coded to use Clickatell, modifying it to use another SMS gateway with a
HTTP interface would be trivial. The only requirement is the ability to specify the UDH (message header) and
message contents in binary.
HSQLDB
HSQLDB is a native Java SQL-compliant database, and is more conveinient where PostgreSQL is
not in place on the system.
HSQLDB may be downloaded from SourceForge:
http://sourceforge.net/project/showfiles.php?group_id=23316
The HSQLDB zip file contains many utilities, however, all we are interested in is hsqldb.jar, which
can be found in lib/
I suggest you copy hsqldb.jar to a stand alone location and use this startup shell script:
#!/bin/sh
java -classpath hsqldb.jar org.hsqldb.Server -database.0 fnbl \
-dbname.0 fnbl
This starts a HSQLDB server with one database – 'fnbl'
PostgreSQL
A JDBC driver .jar for PostgreSQL can be downloaded from http://jdbc.postgresql.org/ .
Ensure you have a database set up for Funambol before we install it.
3 Funambol's J2ME client only listens for SMS notifications on port 50001, the reason being that SMS notifications
on other ports are usually intercepted by the phone software itself (i.e Symbian S60 where there already is a
SyncML client), and is therefore discouraged by the WAP specs.
Environment Variables
After extracting the zip archive, the actual Funambol server files will be located in Funambol/ds-
server . Before we start configuring the Funambol server, I recommend creating a bash script with
the environment variables that can be used with the “source” command:
#!/bin/sh
export JAVA_HOME=<PATH_TO_JDK>
export J2EE_HOME=<PATH_TO_TOMCAT>
The next important line is “modules-to-install=”. If you only want to use the Citadel email
connector, all you need is:
modules-to-install=foundation-3.0.9,citadel
Running it
Run bin/start.sh to start Funambol. Hopefully the first launch should go without incident
Once the administration tool is launched, go File->Login. Remember to change the port from 8080
if you have done, and then, if all is well, login.
Figure 3: The sync settings screen allows Figure 4: This screen allows you to
you to choose the data on the device to sync. customize the emails you receive, and how
For now untick the defaults (Calendar, much text data to accept per email.
Tasks) and tick email. Tap Details next to The Citadel Email connector is capable of
Email to continue passing along attachments – if you wish to
receive them. Tap Advanced Settings to go
to the next step
Untick
Tap
until sync
starts
Tap to sync
all activated
options
Enjoy!
Clickatell basics
Clickatell is a SMS gateway which can be used to send SMS'es, in particularly, exotic things like
WAP push, over the Internet. Most importantly, SMS gateways like Clickatell charge rates many
times lower than what the wireless carriers charge customers up front, and no phones/datacards are
needed. This is particularly important as we aren't in bed with every mobile carrier like our friends
from Ontario, Canada are.
Please note that the use of Clickatell doesn't mean any specific endorsement by the developer;
Clickatell was chosen based on recommendations on forums, capabilities, documentation supplied,
and of course, cost. The notification module that has been coded for Clickatell can be hacked to use
an SMS gateway of equivalent features with a JDK, text editor, and five minutes worth of work :)
Clickatell offers multiple products, the one required here is the SMS gateway itself, or “Clickatell
Central (API)”, details of which are at https://www.clickatell.com/products/sms_gateway.php and
you can sign up at https://www.clickatell.com/central/user/client/step1.php?prod_id=2
Once you have signed up for Clickatell, you will be provided with some basic details:
All that is required to be defined for a connection is the ID for it. After it is created, take note of the
API ID that has been assigned.
Store logs
The “store” directory contains individual directories for each device that syncs. In addition to the
database for each device, two HTML files are generated for each sync - “connector” and “store”.
These aren't too useful without knowledge of the connector's inner workings, but can reveal the
Message-ID of the message that caused the connector to halt.
Tomcat logs
The Tomcat launcher captures the STDOUT and STDERR while it is running Funambol. These can
be found in Tomcat/logs/catalina.out. In rare cases, some Java exceptions may be logged here.
Recovery syncs
To force the device to do a 'full sync' – i.e replace its database and start fresh in the PocketPC
Funambol client, go Menu->Tools->Recover.
Full sync's can also be forced remotely, in the Principals applet in the Funambol administration tool.
Select a username and device pair, double click to see its details and click reset for the email sync
source.
The Funambol J2ME client can be used with mass-market mobile phones that support J2ME. While
it does support push email notification via SMS, we have yet to be able to make it work (please
email me if it does for you!). However, using the J2ME client certainly beats out using your devices
web brower to check mail. It supports message size and day filters so it is a good alternative to
inbuilt device mail clients if you are concious of wireless data usage.
Configuration of the J2ME client isn't a hard task if you are
familiar with the configuration options. Note that a
limitation of the J2ME client is that it doesn't share your
phones address book; it will only share SyncML address
sources, which can be those inbuilt into Funambol, or the
GroupDAV Connector to share your Citadel address book.
You can also have the client not share the address book by
entering a bogus name into the address book source field,
as shown in the example configuration image.