2006-01-21 16:52:19 +01:00
|
|
|
Preamble
|
|
|
|
--------
|
|
|
|
|
2006-03-18 18:30:52 +01:00
|
|
|
This software is ready for testing by a wider audience. 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].
|
2006-01-21 16:52:19 +01:00
|
|
|
|
2006-02-04 21:21:59 +01:00
|
|
|
There's no home page yet. Please refer to the SourceForge page instead:
|
|
|
|
http://sourceforge.net/projects/sync4jevolution/
|
2006-03-11 20:23:43 +01:00
|
|
|
Because the original name "sync4jevolution" is not really appropriate,
|
|
|
|
it was changed to SyncEvolution. The web page and project name will
|
2006-04-17 19:28:07 +02:00
|
|
|
be changed eventually, too.
|
2006-02-04 21:21:59 +01:00
|
|
|
|
2006-01-21 16:52:19 +01:00
|
|
|
|
2005-11-05 23:04:33 +01:00
|
|
|
Introduction
|
|
|
|
------------
|
|
|
|
|
2006-05-01 11:23:41 +02:00
|
|
|
SyncEvolution synchronizes Evolution's contact, calender and task
|
2006-06-15 11:35:30 +02:00
|
|
|
items via SyncML. The items are exchanged in the vCard 2.1 or 3.0
|
|
|
|
format and iCalender 2.0 format via the Funambol C++ client API
|
|
|
|
library, which should make SyncEvolution compatible with the majority
|
|
|
|
of SyncML servers (but see below under known problems). Full, one-way
|
|
|
|
and incremental synchronization of items are supported.
|
2005-11-05 23:04:33 +01:00
|
|
|
|
2006-03-11 20:23:43 +01:00
|
|
|
SyncEvolution does not synchronize with another SyncML capable
|
2006-06-15 11:35:30 +02:00
|
|
|
device or another computer directly. A SyncML server that that device
|
|
|
|
and SyncEvolution can talk to is needed. There are several options for
|
|
|
|
that:
|
|
|
|
- using a web service like ScheduleWorld (sync.scheduleworld.com)
|
|
|
|
which stores the data to be synchronized on a ScheduleWorld server
|
|
|
|
and provides access to it via SyncML
|
|
|
|
- installing a SyncML server like the free one from Funambol
|
|
|
|
(www.funambol.com) on one's own server
|
2006-05-01 11:23:41 +02:00
|
|
|
- installing a SyncML server on the desktop
|
|
|
|
|
2006-06-15 11:35:30 +02:00
|
|
|
The recommended solution is ScheduleWorld because it is easier than
|
|
|
|
setting up a server and provides better support for vCard and
|
|
|
|
iCalendar data than the stock Funambol server installation. Setting up
|
|
|
|
a server on the desktop has the additional problem that not all mobile
|
|
|
|
devices can communicate with the desktop via HTTP.
|
2006-05-01 11:23:41 +02:00
|
|
|
|
2006-06-15 11:35:30 +02:00
|
|
|
The remainder of this document assumes that either Funambol's server
|
|
|
|
bundle was installed using the default configuration or ScheduleWorld
|
|
|
|
is used: because ScheduleWorld is based on the Funambol server,
|
|
|
|
configuration and usage are often similar.
|
2005-11-05 23:04:33 +01:00
|
|
|
|
2006-04-09 13:48:11 +02:00
|
|
|
With a server that fully supports SyncML and vCard/iCalender
|
|
|
|
the following works:
|
2006-01-21 18:06:59 +01:00
|
|
|
- copy a complete database to the server and restore it
|
|
|
|
from the server later
|
2006-01-23 22:51:43 +01:00
|
|
|
- delete or modify an item locally, then make the same change
|
2006-01-21 18:06:59 +01:00
|
|
|
on the server
|
|
|
|
- delete, modify or add items on the server (by synchronizing with
|
2006-01-23 22:51:43 +01:00
|
|
|
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
|
2006-03-11 20:23:43 +01:00
|
|
|
SyncEvolution has support which ensures that no data is lost
|
2006-03-19 22:37:30 +01:00
|
|
|
by creating duplicates (see "Conflict Resolution" below)
|
2005-12-10 20:16:02 +01:00
|
|
|
|
2006-04-09 13:48:11 +02:00
|
|
|
For conflict resolution and synchronization between clients which
|
|
|
|
support different attributes of items the server needs an
|
2006-06-15 11:35:30 +02:00
|
|
|
understanding of the format of items. The Funambol server supports
|
|
|
|
that for contacts, but not yet for the calendar events and tasks that
|
|
|
|
SyncEvolution sends; see "Configuration with Funambol" below for more
|
|
|
|
information. ScheduleWorld also works with SyncEvolution and
|
|
|
|
calendars plus tasks.
|
2006-04-09 13:48:11 +02:00
|
|
|
|
2006-02-04 21:21:59 +01:00
|
|
|
|
2006-03-11 20:23:43 +01:00
|
|
|
Installation
|
|
|
|
------------
|
|
|
|
|
|
|
|
To install SyncEvolution, just unpack an archive with a precompiled
|
|
|
|
binary for your platform in a directory of your choice. Then create
|
|
|
|
a configuration in $HOME/.sync4j/evolution as described below under
|
|
|
|
"Configuration". No special environment variables are needed, although
|
|
|
|
one might want to add the directory with contains the "syncevolution"
|
|
|
|
binary to the shell's PATH variable.
|
|
|
|
|
|
|
|
When a binary packages is not available for the target system
|
|
|
|
and/or is not up-to-date, compiling from source can also be used
|
|
|
|
to produce a binary. See below in "Compiling from Source" for details.
|
|
|
|
|
2006-06-15 11:35:30 +02:00
|
|
|
You also need a working SyncML server. If you do not have an account
|
|
|
|
and/or do not want to get an account on an existing one like
|
|
|
|
ScheduleWorld, installing the Funambol server bundle is very easy:
|
2006-03-11 20:23:43 +01:00
|
|
|
http://www.funambol.com/opensource/downloads.html
|
|
|
|
|
2006-06-15 11:35:30 +02:00
|
|
|
For Funambol Sync4j V2.3, an additional patch is recommended to preserve
|
2006-03-11 20:23:43 +01:00
|
|
|
line breaks of items on the server:
|
|
|
|
http://forge.objectweb.org/tracker/index.php?func=detail&aid=304718&group_id=96&atid=300096
|
|
|
|
|
2006-03-19 22:37:30 +01:00
|
|
|
Although all of the features are covered by unit testing and
|
|
|
|
have been verified to work, it is highly recommended that you
|
|
|
|
make a backup of your
|
|
|
|
$HOME/.evolution/addressbook
|
|
|
|
$HOME/.evolution/calender
|
2006-04-09 13:48:11 +02:00
|
|
|
$HOME/.evolution/tasks
|
2006-03-19 22:37:30 +01:00
|
|
|
directories before running it for the first time. In older Evolution
|
|
|
|
versions the same data is found in $HOME/evolution.
|
|
|
|
|
2006-03-11 20:23:43 +01:00
|
|
|
|
2005-11-05 23:04:33 +01:00
|
|
|
Usage
|
|
|
|
-----
|
|
|
|
|
2006-03-11 20:23:43 +01:00
|
|
|
Currently SyncEvolution comes as a simple command line tool which is
|
2005-11-05 23:04:33 +01:00
|
|
|
configured via files. A graphical interface via an Evolution plugin
|
|
|
|
would also be possible, but is not implemented yet. As command line
|
2006-03-11 20:23:43 +01:00
|
|
|
parameters SyncEvolution only supports one option which specifies the
|
2006-06-12 23:01:28 +02:00
|
|
|
configuration file that drives the synchronization run and several
|
|
|
|
options which choose the data sources in that configuration:
|
2005-11-05 23:04:33 +01:00
|
|
|
|
2006-04-09 13:48:11 +02:00
|
|
|
syncevolution [<server>] [<source> ...]
|
2005-11-05 23:04:33 +01:00
|
|
|
|
2005-11-26 22:16:03 +01:00
|
|
|
The <server> string is used to find the configuration which determines
|
|
|
|
how synchronization is going to proceed. Selection of sources of
|
2005-11-05 23:04:33 +01:00
|
|
|
Evolution data which are to be synchronized with that server is done
|
2006-06-15 11:35:30 +02:00
|
|
|
via configuration files. Each source corresponds to one Evolution
|
|
|
|
address book, calendar or task list.
|
2005-11-05 23:04:33 +01:00
|
|
|
|
2006-06-15 11:35:30 +02:00
|
|
|
If no arguments are given, SyncEvolution lists all available Evolution
|
|
|
|
data sources.
|
|
|
|
|
|
|
|
For each source one can set a different synchronization mode. It is
|
|
|
|
possible to configure sources without activating their
|
|
|
|
synchronization: if the synchronization mode of a source is set to
|
|
|
|
"none", it will be ignore. Explicitely listing one or more source
|
|
|
|
names after the server chooses just those sources for synchronization
|
|
|
|
with their configured sync mode. If such a selected source is
|
|
|
|
currently set to "none", it will be synchronized in "two-way" mode
|
|
|
|
once. The setting in the configuration file is not changed.
|
2005-11-26 22:16:03 +01:00
|
|
|
|
2006-03-19 22:37:30 +01:00
|
|
|
Progress and error messages are written into a log file that is
|
|
|
|
preserved for each synchronization run. Details about that is found
|
|
|
|
in the "Automatic Backups and Logging" section below. Immediately
|
|
|
|
before quitting SyncEvolution will show all errors or warnings
|
|
|
|
encountered and print a summary of how the databases were modified.
|
2006-05-27 17:57:00 +02:00
|
|
|
This is done with the "synccompare" utility script described
|
2006-03-19 22:37:30 +01:00
|
|
|
in the "Exchanging Data" section.
|
|
|
|
|
|
|
|
In case of an error the synchronization run is aborted prematurely and
|
|
|
|
SyncEvolution will return 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
|
2006-05-25 19:32:07 +02:00
|
|
|
compare against the ones it already knows. If the error is detected
|
|
|
|
by SyncEvolution itself, then it attempts to cause the full
|
|
|
|
synchronization only for the failed database, but if the SyncML
|
|
|
|
client library itself runs into a problem it might cause a full
|
|
|
|
synchronization of all databases even if only one of them failed.
|
2006-06-15 11:35:30 +02:00
|
|
|
Therefore it might be less risky to invoke SyncEvolution for each
|
2006-06-12 23:01:28 +02:00
|
|
|
data source separately.
|
2005-11-05 23:04:33 +01:00
|
|
|
|
|
|
|
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
|
2006-04-09 13:48:11 +02:00
|
|
|
next run recovers from that by doing a full synchronization. The risk
|
|
|
|
associated with this is that the server might not recognize items that
|
|
|
|
it already has stored previously which then would lead to duplication
|
|
|
|
of items.
|
2005-11-05 23:04:33 +01:00
|
|
|
|
2006-02-04 21:21:59 +01:00
|
|
|
|
2005-11-05 23:04:33 +01:00
|
|
|
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
|
2005-12-10 20:16:02 +01:00
|
|
|
$HOME/.sync4j/evolution/<server>/spds/sources/<source>/config.txt
|
|
|
|
|
2006-06-15 11:35:30 +02:00
|
|
|
See "etc/localhost_1/spds/syncml/config.txt" for options in the server
|
|
|
|
configuration and "etc/localhost_1/spds/sources/addressbook_1/config.txt"
|
|
|
|
for options in the data source configuration. Without changes this
|
|
|
|
example configuration can be used immediately with a local Funambol
|
|
|
|
installation for testing the operation of SyncEvolution, see "Exchanging
|
|
|
|
Data" below.
|
2005-12-10 20:16:02 +01:00
|
|
|
|
|
|
|
Normally at least the following configuration options need to be adapted:
|
|
|
|
spds/syncml
|
|
|
|
syncURL
|
|
|
|
deviceId
|
|
|
|
username
|
|
|
|
password
|
|
|
|
spds/sources
|
|
|
|
uri
|
|
|
|
evolutionsource
|
2005-11-05 23:04:33 +01:00
|
|
|
|
2006-04-09 13:48:11 +02:00
|
|
|
Each data source corresponds to one database at the SyncML server.
|
|
|
|
The Evolution data source is determined by the type of data given in
|
2006-06-12 23:01:28 +02:00
|
|
|
"type" and uniquely identified with the "evolutionsource" property.
|
2006-06-15 11:35:30 +02:00
|
|
|
To get a list of available data sources, run SyncEvolution with no
|
2006-06-12 23:01:28 +02:00
|
|
|
arguments. "evolutionsource" can be set to either the name or URL
|
2006-06-15 11:35:30 +02:00
|
|
|
of a data source that SyncEvolution prints then.
|
|
|
|
|
|
|
|
The "uri" property is used to identify with which database on the
|
|
|
|
SyncML server the Evolution data is to be synchronized. Each server
|
|
|
|
usually documents what needs to be configured here. The provided
|
|
|
|
configurations for ScheduleWorld and Funambol on the local host
|
|
|
|
already have this set correctly.
|
|
|
|
|
|
|
|
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 Evolution data sources, one
|
|
|
|
has to setup two independent configurations with different "deviceId"
|
|
|
|
settings and synchronize them separately. Such a setup is provided
|
|
|
|
with the "localhost_1/2" configs and using it for testing is explained
|
|
|
|
in more detail in "Exchanging Data" below.
|
2005-11-05 23:04:33 +01:00
|
|
|
|
|
|
|
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
|
2005-12-10 20:16:02 +01:00
|
|
|
only be accessible by the user. [NOT IMPLEMENTED YET]
|
|
|
|
|
2006-02-04 21:21:59 +01:00
|
|
|
|
2006-03-19 22:37:30 +01:00
|
|
|
Automatic Backups and Logging
|
|
|
|
-----------------------------
|
|
|
|
|
|
|
|
To support recovery from a synchronization which damaged the
|
2006-06-15 11:35:30 +02:00
|
|
|
local data or modified it in an unexpected way, SyncEvolution
|
2006-03-19 22:37:30 +01:00
|
|
|
always creates the following files during a synchronization:
|
2006-06-15 11:35:30 +02:00
|
|
|
- a dump of the data in a format which can be imported
|
2006-03-19 22:37:30 +01:00
|
|
|
back into Evolution, e.g. .vcf for address books
|
|
|
|
- a full log file with debug information
|
2006-06-15 11:35:30 +02:00
|
|
|
- a dump of the data after the synchronization for
|
2006-03-19 22:37:30 +01:00
|
|
|
automatic comparison of the before/after state with
|
2006-06-15 11:35:30 +02:00
|
|
|
"synccompare"
|
2006-03-19 22:37:30 +01:00
|
|
|
|
|
|
|
If the source configuration option "logdir" is set, then
|
|
|
|
a new directory will be created for each synchronization
|
|
|
|
in that directory, using the format
|
|
|
|
SyncEvolution-<server>-<yyyy>-<mm>-<dd>-<hh>-<mm>[-<seq>]
|
|
|
|
with the various fields filled in with the time when the
|
|
|
|
synchronization started. The sequence suffix will only be
|
|
|
|
used when necessary to make the name unique. By default,
|
|
|
|
SyncEvolution will never delete any data in that log
|
|
|
|
directory unless explicitly asked to keep only a limited
|
|
|
|
number of previous log directories.
|
|
|
|
|
|
|
|
This is done by setting the "maxlogdirs" limit to something
|
2006-06-15 11:35:30 +02:00
|
|
|
different than the empty string and 0. If a limit is set,
|
2006-03-19 22:37:30 +01:00
|
|
|
then SyncEvolution will only keep that many log directories
|
|
|
|
and start removing the oldest ones when it reaches the limit.
|
|
|
|
This cleanup is only done after a successful synchronization
|
|
|
|
and is limited to directories starting with the
|
|
|
|
SyncEvolution-<server>
|
|
|
|
prefix, so it is safe to put other files or directories
|
|
|
|
into the configured log directory.
|
|
|
|
|
|
|
|
If that option is not set, then the directory will be
|
|
|
|
created as
|
|
|
|
$TMPDIR/SyncEvolution-<username>-<server>
|
|
|
|
with access allowed for the user only. Files from a
|
|
|
|
previous synchronization will be overwritten. This is
|
2006-06-15 11:35:30 +02:00
|
|
|
a lot less useful because the data will usually
|
|
|
|
be lost during the next reboot and each synchronization run
|
|
|
|
overwrites the data of the previous one.
|
2006-03-19 22:37:30 +01:00
|
|
|
|
|
|
|
|
2006-06-15 11:35:30 +02:00
|
|
|
Configuration with ScheduleWorld
|
|
|
|
--------------------------------
|
2006-06-12 23:01:28 +02:00
|
|
|
|
2006-06-15 11:35:30 +02:00
|
|
|
It is recommended to sync against the new vCard 3.0 URI (card3) and
|
|
|
|
iCalendar 2.0 URI (cal2, task2). These are the native formats of
|
|
|
|
Evolution and a lot of effort went into ensuring that they store as
|
|
|
|
much Evolution data as possible. SyncEvolution is primarily tested
|
|
|
|
against ScheduleWorld. The "scheduleworld_1" example configuration is
|
|
|
|
ready to be used with these URIs, one only has to fill in the real
|
|
|
|
username and password.
|
2006-06-12 23:01:28 +02:00
|
|
|
|
|
|
|
|
2006-06-15 11:35:30 +02:00
|
|
|
Configuration with Funambol
|
|
|
|
---------------------------
|
2006-04-09 13:48:11 +02:00
|
|
|
|
2006-06-15 11:35:30 +02:00
|
|
|
A default Funambol installation already contains databases which
|
2006-04-09 13:48:11 +02:00
|
|
|
SyncEvolution can synchronize with Evolution address books and
|
2006-06-15 11:35:30 +02:00
|
|
|
calendars. They are adressed in a source config with
|
2006-04-09 13:48:11 +02:00
|
|
|
uri = card
|
|
|
|
for contacts and
|
|
|
|
uri = cal
|
2006-06-15 11:35:30 +02:00
|
|
|
for calendars. Tasks (aka todos) are not supported directly.
|
2006-04-09 13:48:11 +02:00
|
|
|
|
2006-06-15 11:35:30 +02:00
|
|
|
WARNING: the current Sync4j 2.3 and Funambol 3.0 cannot parse calendar
|
|
|
|
entries as sent by SyncEvolution. Until these issues are resolved in
|
|
|
|
the server, one has to fall back to a setup where the server does not
|
|
|
|
have to convert calendar events. This is similar to the configuration
|
|
|
|
for tasks described in the next paragraph.
|
2006-04-17 19:28:07 +02:00
|
|
|
|
2006-04-09 13:48:11 +02:00
|
|
|
Although Evolution tasks are sent and received as special calendar
|
|
|
|
events, the server cannot parse them. Therefore it is necessary to
|
|
|
|
store each task as files on the server without having the server parse
|
|
|
|
them. One can use the existing
|
|
|
|
uri = snote
|
2006-06-15 11:35:30 +02:00
|
|
|
file URI, but if that URI is also used for real notes or files, then one
|
|
|
|
has to setup what is called FileSyncSource. Just as the client library,
|
|
|
|
the Funambol server also has "sync sources" of data. Adding a new "todo"
|
|
|
|
sync source is best done via the graphical admin tool:
|
2006-04-09 13:48:11 +02:00
|
|
|
- connect to the server
|
|
|
|
- unfold the tree and select "Modules/pdi/FileSystem SyncSource"
|
|
|
|
- enter the following values:
|
|
|
|
Source URI: todo
|
|
|
|
Name: todo
|
|
|
|
Type: text/x-todo
|
|
|
|
Source Directory: <server install dir>/db/todo
|
|
|
|
Supported types: text/x-todo
|
|
|
|
Supported versions: text/x-todo
|
|
|
|
Encoded: deselected
|
|
|
|
MultiUser: deselected if all users access the same database,
|
|
|
|
selected if every user gets his own database
|
|
|
|
- add the new sync source
|
|
|
|
- create the <server install dir>/db/todo directory
|
|
|
|
|
|
|
|
The drawback of the file based approach is that the server always
|
|
|
|
keeps tasks exactly as the clients send them: imagine that
|
|
|
|
SyncEvolution stores a task on the server and then a phone fetches
|
|
|
|
that task from the server, possibly throwing away attributes that it
|
|
|
|
does not support. When now the task is modified on the phone and sent
|
|
|
|
back to the server, only the attributes supported by the phone remain
|
|
|
|
on the server and thus after another synchronization with
|
|
|
|
SyncEvolution also in Evolution. For calendar entries and contacts the
|
2006-06-15 11:35:30 +02:00
|
|
|
Funambol server avoids this kind of data loss by updating its copy of an
|
2006-04-09 13:48:11 +02:00
|
|
|
item instead of replacing it wholesale.
|
|
|
|
|
|
|
|
|
2005-12-10 20:16:02 +01:00
|
|
|
Exchanging Data
|
|
|
|
---------------
|
|
|
|
|
2006-05-01 11:23:41 +02:00
|
|
|
SyncEvolution transmits address book entries as vCard 2.1 or 3.0
|
|
|
|
depending on the type chosen in the configuration. Evolution uses
|
|
|
|
3.0 internally, so SyncEvolution converts between the two formats
|
|
|
|
as needed. Calendar items and tasks have to be sent and received
|
2006-05-25 11:14:39 +02:00
|
|
|
in iCalendar 2.0 format. Only the UTF-8 character set is supported.
|
2005-12-10 20:16:02 +01:00
|
|
|
|
2006-05-01 11:23:41 +02:00
|
|
|
How the server stores the items depends on its implementation and
|
2006-06-15 11:35:30 +02:00
|
|
|
configuration. In the default Funambol server installation, contacts
|
2006-05-01 11:23:41 +02:00
|
|
|
and calendar items are converted into an internal format, but at
|
2006-06-15 11:35:30 +02:00
|
|
|
least for contacts it preserves most of the properties used by
|
|
|
|
Evolution whereas iCalendar 2.0 items are not parsed properly at all
|
|
|
|
at the moment. ScheduleWorld uses the same format as Evolution for
|
|
|
|
calendars and tasks and thus requires no conversion. Contacts are
|
|
|
|
stored in an LDAP server using the same schema also supported by
|
2006-05-01 11:23:41 +02:00
|
|
|
Evolution.
|
2005-12-10 20:16:02 +01:00
|
|
|
|
2006-06-15 11:35:30 +02:00
|
|
|
To check which data is preserved, one can use this procedure
|
|
|
|
(described for contacts, but works the same way for calendars and
|
|
|
|
tasks):
|
2005-12-10 20:16:02 +01:00
|
|
|
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
|
|
|
|
|
2006-04-09 13:48:11 +02:00
|
|
|
The "etc/localhost_1" directory contains a configuration for a default
|
2006-06-15 11:35:30 +02:00
|
|
|
Sync4j 2.3 installation on the local host and Evolution address book,
|
2006-04-09 13:48:11 +02:00
|
|
|
calendar and tasks all called "SyncEvolution test #1". The
|
|
|
|
"etc/localhost_2" is the pendant for a second client which
|
|
|
|
synchronizes against the same server and Evolution databases called
|
|
|
|
"SyncEvolution test #2". Both configurations can be copied directly to
|
|
|
|
".sync4j/evolution":
|
2006-01-21 16:52:19 +01:00
|
|
|
mkdir -p ~/.sync4j/evolution
|
|
|
|
cp -a etc/localhost* ~/.sync4j/evolution
|
|
|
|
|
2006-05-01 11:23:41 +02:00
|
|
|
Note that the second client pretends to be a "sc-pim-ppc" client to
|
|
|
|
avoid the need to reconfigure the default Sync4j installation. This
|
|
|
|
implies that you cannot use this predefined Evolution config if you
|
|
|
|
actually synchronize against a PocketPC client.
|
|
|
|
|
2006-06-15 11:35:30 +02:00
|
|
|
The same configuration also exists for ScheduleWorld, but beware
|
2006-05-01 11:23:41 +02:00
|
|
|
that username/password must be adapted in the spds/syncml/config.txt
|
|
|
|
files.
|
|
|
|
|
2006-04-09 13:48:11 +02:00
|
|
|
For them to work, also create the two address books/calendars/tasks
|
2006-03-11 20:23:43 +01:00
|
|
|
SyncEvolution test #1
|
|
|
|
SyncEvolution test #2
|
2006-06-15 11:35:30 +02:00
|
|
|
inside Evolution. SyncEvolution never creates automatically what is
|
|
|
|
referenced in a source configuration to avoid surprises.
|
2006-01-21 16:52:19 +01:00
|
|
|
|
|
|
|
Steps 1 above then becomes an invocation of
|
2006-04-09 13:48:11 +02:00
|
|
|
syncevolution localhost_1 addressbook_1
|
2006-01-21 16:52:19 +01:00
|
|
|
and step 4
|
2006-04-09 13:48:11 +02:00
|
|
|
syncevolution localhost_2 addressbook_2
|
2005-12-10 20:16:02 +01:00
|
|
|
|
|
|
|
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:
|
2006-01-21 16:52:19 +01:00
|
|
|
- save the complete address books: mark all entries, save as vCard
|
2006-05-27 17:57:00 +02:00
|
|
|
- invoke synccompare with two file names as arguments and it will
|
|
|
|
normalize and compare them automatically
|
2006-03-15 23:09:04 +01:00
|
|
|
|
2005-12-10 20:16:02 +01:00
|
|
|
Normalizing is necessary because the order of cards and their
|
|
|
|
properties as well as other minor formatting aspects may be
|
2006-05-27 17:57:00 +02:00
|
|
|
different. The output comes from a "diff --side-by-side", but
|
|
|
|
is augmented by the script so that the context of each change
|
|
|
|
is always the complete item that was modified. Lines or items
|
|
|
|
following a ">" on the right side were added, those on the
|
|
|
|
left side followed by a "<" were removed, and those with
|
|
|
|
a "!" between text on the left and right side were modified.
|
|
|
|
|
|
|
|
The automatic unit testing (see HACKING) contains a "testItems"
|
2006-06-15 11:35:30 +02:00
|
|
|
test which verifies the copying of special entries using the
|
|
|
|
same method.
|
2005-12-10 20:16:02 +01:00
|
|
|
|
2006-06-15 11:35:30 +02:00
|
|
|
Modifying one of the address books or even both at the same time and
|
|
|
|
then synchronizing back and forth can be used to verify that
|
|
|
|
SyncEvolution works as expected. If you do not trust SyncEvolution 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.
|
2005-12-10 20:16:02 +01:00
|
|
|
|
2005-11-25 21:53:04 +01:00
|
|
|
|
2006-01-23 22:51:43 +01:00
|
|
|
Conflict Resolution
|
|
|
|
-------------------
|
|
|
|
|
|
|
|
If two clients make changes to the same item, the first one to
|
2006-06-15 11:35:30 +02:00
|
|
|
synchronize will copy its changes to the server. The second one
|
2006-01-23 22:51:43 +01:00
|
|
|
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
|
2006-04-09 13:48:11 +02:00
|
|
|
locally modified copy (the default with Sync4j), SyncEvolution 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 for that inside SyncEvolution:
|
|
|
|
there is only an ERROR entry in the log and the summary will show
|
|
|
|
the duplicated items.
|
2006-01-23 22:51:43 +01:00
|
|
|
|
2006-05-01 11:23:41 +02:00
|
|
|
Merging items on the server is difficult because the SyncML protocol
|
|
|
|
does not specify which parts of a conflicting item were updated.
|
|
|
|
In general a server can only make more or less educated guesses
|
|
|
|
which might lead to data loss. It is better to avoid this situation
|
|
|
|
in the first place by synchronizing before making changes.
|
|
|
|
|
2006-02-04 21:21:59 +01:00
|
|
|
|
2005-11-26 22:16:03 +01:00
|
|
|
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
|
2006-06-15 11:35:30 +02:00
|
|
|
the Evolution data server, albeit in a limited way and some backends
|
|
|
|
might not implement it:
|
2005-11-26 22:16:03 +01:00
|
|
|
|
2005-12-10 20:16:02 +01:00
|
|
|
the same function lists changes and also moves the so called "change
|
2005-11-26 22:16:03 +01:00
|
|
|
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
|
2006-03-11 20:23:43 +01:00
|
|
|
time. SyncEvolution delays asking for changes as long as possible
|
2005-11-26 22:16:03 +01:00
|
|
|
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.
|
|
|
|
|
2006-03-11 20:23:43 +01:00
|
|
|
If synchronization fails for some or all items, then SyncEvolution
|
2005-11-26 22:16:03 +01:00
|
|
|
cannot mark individual items for retransmission during the next
|
|
|
|
sync and forces the next sync to execute in slow mode.
|
|
|
|
|
2006-03-11 20:23:43 +01:00
|
|
|
The change marker that SyncEvolution uses is a string which is
|
|
|
|
composed as "SyncEvolution:<syncURL>/<name>" where <syncURL> comes
|
2005-11-26 22:16:03 +01:00
|
|
|
from the server config file and <name> from the source config
|
|
|
|
file. This implies that changes are tracked separately for each server
|
2006-06-15 11:35:30 +02:00
|
|
|
and source configuration that Evolution might be synchronized with.
|
2005-11-26 22:16:03 +01:00
|
|
|
|
2006-02-04 21:21:59 +01:00
|
|
|
|
|
|
|
Known Problems
|
|
|
|
--------------
|
|
|
|
|
2006-03-19 22:37:30 +01:00
|
|
|
ObjectWeb #<num> refers to the Funambol issue tracker at:
|
|
|
|
http://forge.objectweb.org/tracker/?group_id=96&atid=100096
|
|
|
|
|
2006-06-15 11:35:30 +02:00
|
|
|
- Synchronization with http://syncml.mobiledit.com fails, apparently
|
|
|
|
due to problems in the client library. Your mileage with non-Funambol
|
|
|
|
based servers may vary.
|
|
|
|
|
|
|
|
ObjectWeb #305503
|
|
|
|
|
2006-03-18 18:30:52 +01:00
|
|
|
- various vcard and special character related problems in the
|
|
|
|
Sync4j server and client library:
|
2006-06-12 23:01:28 +02:00
|
|
|
TestEvolution::testItems fails the check that items
|
2006-02-04 21:21:59 +01:00
|
|
|
are identical after copying them to the server and back
|
2006-04-09 13:48:11 +02:00
|
|
|
|
2006-02-04 21:21:59 +01:00
|
|
|
Many of these issues have been fixed in the server already,
|
2006-03-12 23:31:52 +01:00
|
|
|
but even in 2.3 plus patch some information is still lost
|
|
|
|
(see "testing vcard conversion and copying" on the sync4j-user
|
|
|
|
mailing list for details).
|
2006-02-04 21:21:59 +01:00
|
|
|
|
2006-03-19 22:37:30 +01:00
|
|
|
ObjectWeb #304828, #304786, #304784, #304782
|
|
|
|
|
2006-06-15 11:35:30 +02:00
|
|
|
- ScheduleWorld preserves almost all Evolution
|
2006-06-05 23:21:24 +02:00
|
|
|
contact and calendar data, the exceptions are:
|
|
|
|
- the LDAP schema used to store contacts does not distinguish
|
|
|
|
between different emails, so although all email addresses
|
|
|
|
are preserved, their type gets lost
|
|
|
|
- "Department" and "Office" of a contact get lost
|
|
|
|
- the order of email addresses and phone numbers in the
|
|
|
|
Evolution GUI is not preserved
|
|
|
|
|
2006-06-15 11:35:30 +02:00
|
|
|
- ScheduleWorld's LDAP schema for email addresses implies that when
|
|
|
|
a client sends back a modified contact with a certain set of
|
|
|
|
email addresses, the server can either add them to its own copy
|
|
|
|
of the contact (thus preventing clients from removing old addresses)
|
|
|
|
or replace all of the contact's addresses with the ones sent
|
|
|
|
by the client. Currently ScheduleWorld does the latter, but this
|
|
|
|
also implies that modifying contacts on devices which store less
|
|
|
|
or no email addresses than Evolution may delete still valid email
|
|
|
|
addresses.
|
|
|
|
|
|
|
|
- "refresh-from-client" synchronization is not supported by the
|
|
|
|
current ScheduleWorld server. It might be added soon.
|
|
|
|
|
|
|
|
- Copying a calendar event via the ScheduleWorld server from one client
|
|
|
|
to another, then deleting it on the first client and trying to
|
|
|
|
synchronize this change to the second client currently does not
|
|
|
|
delete the event on the second client (CalendarSync::testDelete in
|
|
|
|
the test suite). This is under investigation.
|
|
|
|
|
2006-03-19 22:37:30 +01:00
|
|
|
- error handling could be improved
|
|
|
|
|
|
|
|
ObjectWeb #304805, #304562
|
|
|
|
|
2006-06-12 23:01:28 +02:00
|
|
|
- The Funambol servers upto and including 3.0 do not support
|
|
|
|
iCalendar 2.0, see above.
|
2006-04-17 19:28:07 +02:00
|
|
|
|
2006-06-15 11:35:30 +02:00
|
|
|
- Removing a field and then synchronizing with a Funambol server
|
2006-02-04 21:21:59 +01:00
|
|
|
will not remove that field on the server. The server will preserve
|
2006-06-15 11:35:30 +02:00
|
|
|
the old value instead. Other servers might do the same.
|
2006-02-04 21:21:59 +01:00
|
|
|
|
2006-06-15 11:35:30 +02:00
|
|
|
This is necessary because a SyncML server cannot distinguish between
|
2006-02-04 21:21:59 +01:00
|
|
|
removed fields and fields that a client does not store. To avoid
|
|
|
|
losing data when copying back items from a less capable client the
|
2006-06-15 11:35:30 +02:00
|
|
|
server preserves missing fields, even in a situation where the field
|
2006-02-04 21:21:59 +01:00
|
|
|
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.
|
|
|
|
|
2006-06-12 23:01:28 +02:00
|
|
|
- Evolution 2.0.4 and 2.4.2.1 still display the old content of a contact
|
|
|
|
which was updated during a certain test (TestEvolution::testMerge).
|
|
|
|
Exact reason unknown, needs to be investigated.
|
|
|
|
|
2006-06-11 23:53:24 +02:00
|
|
|
- Evolution 2.0.4 (and perhaps also other versions) have a problem
|
|
|
|
when SyncEvolution receives a calendar event with a new timezone
|
|
|
|
definition. SyncEvolution adds the definition to the Evolution
|
|
|
|
database, but an already running Evolution crashes when trying to
|
|
|
|
open the new event. Restarting Evolution solves that problem.
|
|
|
|
|
2006-02-04 21:21:59 +01:00
|
|
|
|
|
|
|
Support
|
|
|
|
-------
|
|
|
|
|
2006-06-15 11:35:30 +02:00
|
|
|
If you would like to ask questions, please use the Funambol Sync4j
|
2006-02-04 21:21:59 +01:00
|
|
|
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
|
2006-03-11 20:23:43 +01:00
|
|
|
SyncEvolution, please try to determine as good as you can
|
2006-06-15 11:35:30 +02:00
|
|
|
whether it is caused by SyncEvolution, the Funambol C++ client
|
2006-02-04 21:21:59 +01:00
|
|
|
library or the server that you talk to.
|
|
|
|
|
|
|
|
Issues in the server should be reported using the issue tracker
|
2006-06-15 11:35:30 +02:00
|
|
|
for it. For Funambol, it is located at
|
2006-02-04 21:21:59 +01:00
|
|
|
http://forge.objectweb.org/tracker/?group_id=96
|
2006-06-15 11:35:30 +02:00
|
|
|
There you can also report issues with the client library.
|
2006-02-04 21:21:59 +01:00
|
|
|
|
2006-03-11 20:23:43 +01:00
|
|
|
Because binary releases of SyncEvolution will contain
|
2006-02-04 21:21:59 +01:00
|
|
|
that library and have to be updated, please also create another
|
2006-03-11 20:23:43 +01:00
|
|
|
issue in the SyncEvolution tracker linking to the objectweb
|
2006-02-04 21:21:59 +01:00
|
|
|
issue.
|
|
|
|
|
2006-03-11 20:23:43 +01:00
|
|
|
If unsure, just open a ticket in the SyncEvolution tracker
|
2006-02-04 21:21:59 +01:00
|
|
|
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:
|
2006-03-11 20:23:43 +01:00
|
|
|
- version of SyncEvolution
|
2006-02-04 21:21:59 +01:00
|
|
|
- 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
|
|
|
|
|
|
|
|
|
2005-11-25 21:53:04 +01:00
|
|
|
Compiling from Source
|
|
|
|
---------------------
|
|
|
|
|
2006-06-15 11:35:30 +02:00
|
|
|
To compile the code the 3.x version of the Funambol C++ client library
|
2006-03-12 10:48:59 +01:00
|
|
|
is needed. A compatible snapshot of it is included in SyncEvolution
|
|
|
|
source packages and will be used automatically. Instructions for
|
|
|
|
working with CVS sources directly are contained in the HACKING
|
|
|
|
document.
|
2005-12-10 20:16:02 +01:00
|
|
|
|
2006-03-18 18:30:52 +01:00
|
|
|
Also needed are the Evolution and libcurl development files. On
|
2006-06-15 15:49:12 +02:00
|
|
|
Debian 3.1 (Sarge) you can install them with:
|
|
|
|
apt-get install libcurl3-dev evolution-data-server-dev libdb3-dev
|
|
|
|
and optionally for the test suite:
|
|
|
|
apt-get install libcppunit-dev
|
|
|
|
|
2006-03-18 18:30:52 +01:00
|
|
|
The code was tested with Evolution 2.0.4 and 2.4.2.1. It is unclear
|
|
|
|
which other versions it is compatible with.
|
2005-11-25 21:53:04 +01:00
|
|
|
|
2006-03-11 20:23:43 +01:00
|
|
|
The build system is the normal autotools system. See INSTALL for
|
|
|
|
general instructions how to use that and "./configure --help" for
|
2006-06-15 11:35:30 +02:00
|
|
|
SyncEvolution specific options.
|
2006-02-04 21:21:59 +01:00
|
|
|
|
|
|
|
|
|
|
|
Author
|
|
|
|
------
|
|
|
|
|
|
|
|
Patrick Ohly
|
|
|
|
patrick.ohly@gmx.de
|
2006-03-11 20:23:43 +01:00
|
|
|
http://ohly.home.pages.de/
|