Preamble
--------
This software is still experimental. Some parts of this documentation
describe how features are supposed to work although they have not been
implemented yet. They are marked with [not implemented].
There's no home page yet. Please refer to the SourceForge page instead:
http://sourceforge.net/projects/sync4jevolution/
Introduction
------------
sync4jevolution synchronizes Evolution's contact and calender items
[calender not implemented yet]
with a SyncML server. The items are exchanged in the vCard and
vCalender formats and via the Funambol Sync4j C++ client API library,
which should make sync4jevolution compatible with the majority of
SyncML servers. Full, one-way and incremental synchronization of items
are supported.
sync4jevolution does not synchronize with another SyncML capable
device directly: a SyncML server that that device and sync4jevolution
can talk to is needed. The remainder of this document assumes that
Funambol's Sync4j server bundle for Linux V2.3 was installed using the
default configuration.
With a server that fully supports SyncML and the vCard standard the
following works:
- copy a complete database to the server and restore it
from the server later
- delete or modify an item locally, then make the same change
on the server
- delete, modify or add items on the server (by synchronizing with
another client), then make the same change locally
- conflict resolution (where two clients modify the same item,
then sync with the server) is handled by the server, but
sync4jevolution has support which ensures that no data is lost
by creating duplicates (see Conflict Resolution below)
Although all of the features are covered by unit testing and
have been verified to work, this software is still experimental.
Make a backup of your
$HOME/.evolution/addressbook
$HOME/.evolution/calender
directories before running it for the first time. In older Evolution
versions the same data is found in $HOME/evolution.
Usage
-----
Currently sync4jevolution comes as a simple command line tool which is
configured via files. A graphical interface via an Evolution plugin
would also be possible, but is not implemented yet. As command line
parameters sync4jevolution only supports one option which specifies the
configuration file that drives the synchronization run:
sync4jevolution [<server>]
The <server> string is used to find the configuration which determines
how synchronization is going to proceed. Selection of sources of
Evolution data which are to be synchronized with that server is done
via configuration files. It is possible to configure sources without
activating their synchronization, see the "disabled" property below.
If the SyncML server is not specified, sync4jevolution lists all
available Evolution backend databases.
Progress and error messages are both sent to stdout. In case of an
error the synchronization run is aborted and sync4jevolution returns a
non-zero value. Recovery from failed synchronization is done by
forcing a full synchronization during the next run, i.e. by sending
all items and letting the SyncML server compare against the ones it
already knows.
After a successful synchronization the server's configuration file is
updated so that the next run can be done incrementally. If the
configuration file has to be recreated e.g. because it was lost, the
next run recovers from that by doing a full synchronization.
Configuration
-------------
The configuration file of a certain <server> is stored in
$HOME/.sync4j/evolution/<server>/spds/syncml/config.txt
The format is a simple list of
<property> = <value>
pairs with one pair per line. Leading spaces and space around the
equals character are skipped. <value> then runs until the the end of
the line. In other words, it cannot start with spaces nor contain line
breaks. Do not put quotation marks around <value>, they would be
treated as part of the value itself. Lines starting with a hash (#)
after optional leading spaces are treated as comments and skipped.
Each data source is configured in
$HOME/.sync4j/evolution/<server>/spds/sources/<source>/config.txt
See "etc/example/spds/syncml/config.txt" for options in the server
configuration and "etc/example/spds/sources/addressbook_1/config.txt"
for options in the data source configuration. Without changing this
example configuration can be used for testing the operation of
sync4jevolution, see "Exchanging Data" below.
Normally at least the following configuration options need to be adapted:
spds/syncml
syncURL
deviceId
username
password
spds/sources
uri
evolutionsource
Each data source corresponds to one database at the SyncML server, so
two entries have to be added for each Evolution calendar as it stores
both events/appointments and todo items [NOT IMPLEMENTED] The Evolution data source is
determined by the type of data given in "type" and uniquely identified
with the "evolutionurl" property.
One can synchronize with multiple server databases in one run, but
the same server database can only be accessed once. To synchronize
the same server database with multiple local databases, one has
to setup two independent configurations with different "deviceId"
settings and synchronize them separately.
If the Evolution data source requires authentication, the
"evolutionuser" and "evolutionpassword" are used as credentials. In
this case the directory that contains the source's config.txt should
only be accessible by the user. [NOT IMPLEMENTED YET]
Exchanging Data
---------------
sync4jevolution transmits address book entries as vCard 2.1, although
Evolution exports them as 3.0. This is done because most servers do
not yet support importing 3.0. Importing new or modified entries from
the server can be done in 2.1 and 3.0 vCards.
How the server stores the vCards depends on its implementation and
configuration. In the default Sync4j server installation, vCards are
converted into an internal format, but it preserves the Evolution
vCard extensions.
To check which data is preserved, one can use this procedure:
1. synchronize the address book with the server
2. create an new address book in Evolution
3. add a configuration for that second address book and the
same database on the SyncML server
4. synchronize again, this time using the other data source
The "etc/localhost_1" directory contains a configuration for
a default Sync4j installation on the local host and an Evolution
address book called "sync4jevolution test #1". The
"etc/localhost_2" is the pendant for a second address book
called "sync4jevolution test #2". Both configurations can
be copied directly to ".sync4j/evolution":
mkdir -p ~/.sync4j/evolution
cp -a etc/localhost* ~/.sync4j/evolution
rm -rf ~/.sync4j/evolution/localhost*/spds/sources/CVS
The last step is only necessary when working with a checkout
of the sync4jevolution sources from CVS.
For them to work, also create the two address books
sync4jevolution test #1
sync4jevolution test #2
inside Evolution. sync4jevolution never creates address
books itself.
Steps 1 above then becomes an invocation of
sync4jevolution localhost_1
and step 4
sync4jevolution localhost_2
This copies all contacts into the server and from there into the new
address book. Now one can either compare the address books in
Evolution or do that automatically:
- save the complete address books: mark all entries, save as vCard
- normalize the files with the provided Perl script:
test/normalize_vcard.pl list1.vcf >list1.normal.vcf
test/normalize_vcard.pl list2.vcf >list2.normal.vcf
- compare the normalized lists, e.g.:
diff -c list1.normal.vcf list2.normal.vcf
Normalizing is necessary because the order of cards and their
properties as well as other minor formatting aspects may be
different. The automatic unit testing (see HACKING) also contains
a "testVCard" test which verifies the copying of contact
entries.
Modifying either address book and synchronizing back and forth
can be used to verify that sync4jevolution works as expected. If
you do not trust sync4jevolution or the server, then it is prudent
to run these checks with a copy of the original address book.
Make a backup of the .evolution/addressbook directory.
Did I mention that you should make backups?
Conflict Resolution
-------------------
If two clients make changes to the same item, the first one to
sync will get the server to copy its changes. The second one
then runs into a conflict when it tries to push its own changes
into the server.
The SyncML server now has to decide how to proceed. If the server
decides to continue with its own copy and asks to overwrite the
locally modified copy (the default with Sync4j),
sync4jevolution will make a local copy first. This leads to
duplicates which have to be merged manually on the client side
where the conflict occurred. Currently there is no support
inside sync4jevolution: there is only an ERROR entry in the
log. A summary at the end of syncing would be better, or
even opening GUI dialogs to resolve the conflicts immediately...
Tracking Changes inside Evolution
---------------------------------
The SyncML protocol requires that a client knows which items have been
added, modified and deleted since the last sync. This is supported by
the Evolution database server, albeit in a limited way:
the same function lists changes and also moves the so called "change
marker" forward. Therefore asking for changes twice in a row will only
list changes the first time and not report the same changes a second
time. sync4jevolution delays asking for changes as long as possible
and only does it when synchronization has really started. Then
if synchronization completed and items where added, modified or
deleted on behalf of the server, the change marker is moved forward.
If synchronization fails for some or all items, then sync4jevolution
cannot mark individual items for retransmission during the next
sync and forces the next sync to execute in slow mode.
The change marker that sync4jevolution uses is a string which is
composed as "sync4jevolution:<syncURL>/<name>" where <syncURL> comes
from the server config file and <name> from the source config
file. This implies that changes are tracked separately for each server
and server database that Evolution might be synchronized with.
Known Problems
--------------
- refresh-server results in a Sync4j client library error at the end
of the sync:
TestEvolution.cpp:534:Assertion
Test name: TestEvolution::testDeleteAll
assertion failed
- Expression: !res
Should be fixed in the client library.
- various vcard related problems in the Sync4j server:
TestEvolution::testVCard fails the check that items
are identical after copying them to the server and back
Many of these issues have been fixed in the server already,
but not yet in 2.3b4.
- Removing a field and then synchronizing with the Sync4j server
will not remove that field on the server. The server will preserve
the old value instead.
This is necessary because the server cannot distinguish between
removed fields and fields that a client does not store. To avoid
losing data when copying back items from a less capable client the
server preserves missing fields, even in situation where the field
was intentionally removed on the client.
The workaround for this conceptual problem is to never clean
(= remove) a field - better fill it with e.g. a single space.
Support
-------
If you would like to ask questions, please use the Sync4j
users mailing list. You can subscribe at
http://sourceforge.net/mail/?group_id=30236
or mail
sync4j-users@lists.sourceforge.net
directly. If you mail the list without subscribing, please ask
to get replies to you directly, as some people might reply
only to the list otherwise.
However, before asking a question make sure that it has not
been answered already (archives are linked to from the list
page) and is not covered in this document. There is no FAQ yet.
If you run into any kind of issue during synchronization with
sync4jevolution, please try to determine as good as you can
whether it is caused by sync4jevolution, the Sync4j client
library or the server that you talk to.
Issues in the server should be reported using the issue tracker
for it. For Sync4j, it is located at
http://forge.objectweb.org/tracker/?group_id=96
There you can also report issues with the Sync4j client library.
Because binary releases of sync4jevolution will contain
that library and have to be updated, please also create another
issue in the sync4jevolution tracker linking to the objectweb
issue.
If unsure, just open a ticket in the sync4jevolution tracker
and it will be forwarded appropriately after an initial analysis.
That tracker is hosted at SourceForge and can also be used
for feature requests:
http://sourceforge.net/tracker/?group_id=146288&atid=764733
Be sure to always include the following information:
- version of sync4jevolution
- version of Evolution
- server and its version
- Linux distribution
- client log if appropriate,
server log if appropriate and available
- a description of what you do,
what you expect to see,
what you get instead
Compiling from Source
---------------------
To compile the code the 3.x version of the Sync4j C++ client library
is needed. It is currently only available from CVS, checkout the
"3x" module from the CVS at
http://forge.objectweb.org/projects/sync4j
Because that code changes a lot and thus might occasionally be
incompatible with the current head revision of sync4jevolution,
please checkout revision
funambol30b1
That is the latest revision of the client that I have verified to
work with the latest sync4jevolution.
The recommended way to make that library available is by
installing it into its own directory with shared libraries disabled:
configure --prefix=<dir> --disable-shared; make; make install
and then pointing the configure of sync4jevolution towards it:
configure --with-sync4j=<dir> --disable-shared
Shared versions of the libraries are not recommended at the moment
because the client libraries API is not expected to be stable.
Also needed are the Evolution development files. The code was tested
with Evolution 2.0.4. It is unclear which other versions it is
compatible with.
The build system is the normal autotools system.
See INSTALL for general instructions how to use that
and "./configure --help" for Sync4jEvolution specific
options.
Author
------
Patrick Ohly
patrick.ohly@gmx.de
http://ohly.home.pages.de/
7ab0dc0b94