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
|
|
|
|
items with a SyncML server. The items are exchanged in the vCard 2.1
|
|
|
|
or 3.0 format and iCalender 2.0 format via the Funambol Sync4j C++
|
|
|
|
client API library, which should make SyncEvolution compatible with
|
|
|
|
the majority of SyncML servers. 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-05-01 11:23:41 +02:00
|
|
|
device 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 www.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 Funambol's Sync4j on one's own server
|
|
|
|
- installing a SyncML server on the desktop
|
|
|
|
|
|
|
|
The recommended solution is www.scheduleworld.com because it is easier
|
|
|
|
than setting up a server and provides better support for vCard and
|
|
|
|
iCalendar data than the stock Sync4j 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-05 22:44:55 +02:00
|
|
|
[ not quite yet: scheduleworld still has some problems that the
|
|
|
|
admin is working on - the text above was written for SyncEvolution
|
|
|
|
0.3, which will be released once the problems have been resolved ]
|
|
|
|
|
2006-05-01 11:23:41 +02:00
|
|
|
The remainder of this document assumes that either Funambol's Sync4j
|
|
|
|
server bundle for Linux V2.3 was installed using the default
|
|
|
|
configuration or scheduleworld is used: because scheduleworld uses
|
|
|
|
Sync4j, 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
|
|
|
|
understanding of the format of items. The Sync4j server supports that
|
|
|
|
for contacts and calendars but not tasks; see "Configuration with
|
2006-05-01 11:23:41 +02:00
|
|
|
Sync4j" below for more information. scheduleworld also supports that
|
|
|
|
for calendars and 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.
|
|
|
|
|
|
|
|
You also need a working SyncML server. If you do not have and/or
|
|
|
|
cannot get an account on an existing one, installing the Funambol
|
|
|
|
Sync4j server bundle is very easy. See:
|
|
|
|
http://www.funambol.com/opensource/downloads.html
|
|
|
|
|
|
|
|
For Sync4j V2.3, an additional patch is recommended to preserve
|
|
|
|
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-01-21 16:52:19 +01:00
|
|
|
configuration file that drives the synchronization run:
|
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
|
|
|
|
via configuration files. It is possible to configure sources without
|
2006-04-09 13:48:11 +02:00
|
|
|
activating their synchronization: if the "sync" property 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 configured sync mode or "two-way" if a source
|
|
|
|
is currently set to "none".
|
2005-11-05 23:04:33 +01:00
|
|
|
|
2006-03-11 20:23:43 +01:00
|
|
|
If the SyncML server is not specified, SyncEvolution lists all
|
2005-11-26 22:16:03 +01:00
|
|
|
available Evolution backend databases.
|
|
|
|
|
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.
|
|
|
|
This is done with the "normalize_vcard" utility script described
|
|
|
|
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
|
|
|
|
compare against the ones it already knows.
|
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
|
|
|
|
|
|
|
|
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
|
2006-03-11 20:23:43 +01:00
|
|
|
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
|
|
|
|
"type" and uniquely identified with the "evolutionurl" property.
|
2005-12-10 20:16:02 +01:00
|
|
|
|
|
|
|
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.
|
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
|
|
|
|
local database or modified it in an unexpected way, SyncEvolution
|
|
|
|
always creates the following files during a synchronization:
|
|
|
|
- a dump of the database in a format which can be imported
|
|
|
|
back into Evolution, e.g. .vcf for address books
|
|
|
|
- a full log file with debug information
|
|
|
|
- a dump of the database after the synchronization for
|
|
|
|
automatic comparison of the before/after state with
|
|
|
|
"normalize_vcard"
|
|
|
|
|
|
|
|
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
|
|
|
|
different than the empty sring or 0: if a limit is set,
|
|
|
|
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
|
|
|
|
a lot less useful because the data will probably
|
|
|
|
be lost during the next reboot.
|
|
|
|
|
|
|
|
|
2006-04-09 13:48:11 +02:00
|
|
|
Configuration with Sync4j
|
|
|
|
-------------------------
|
|
|
|
|
|
|
|
A default Sync4j 2.3 installation already contains databases which
|
|
|
|
SyncEvolution can synchronize with Evolution address books and
|
|
|
|
calendars. They are adressed with
|
|
|
|
uri = card
|
|
|
|
for contacts and
|
|
|
|
uri = cal
|
|
|
|
for calendars in the source config.
|
|
|
|
|
2006-04-17 19:28:07 +02:00
|
|
|
WARNING: the current Sync4j 2.3 cannot parse calendar entries
|
2006-05-01 11:23:41 +02:00
|
|
|
as sent by SyncEvolution. Until these issues are resolved in the
|
2006-04-17 19:28:07 +02:00
|
|
|
server, one has to fall back to a setup where the server does not
|
|
|
|
have to convert tasks. This is similar to the configuration for
|
|
|
|
tasks described in the next paragraph.
|
|
|
|
|
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
|
|
|
|
file source, but if that source is also used for real notes or
|
|
|
|
files, then one has to setup another FileSyncSource. Adding
|
|
|
|
a new "todo" sync source is best done via the graphical Sync4j admin
|
|
|
|
tool:
|
|
|
|
- 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
|
|
|
|
Sync4j server avoids this kind of data loss by updating its copy of an
|
|
|
|
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
|
|
|
|
configuration. In the default Sync4j server installation, vCards
|
|
|
|
and calendar items are converted into an internal format, but at
|
|
|
|
least for vCards it preserves most of the properties used by
|
|
|
|
Evolution.
|
2005-12-10 20:16:02 +01:00
|
|
|
|
|
|
|
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
|
|
|
|
|
2006-04-09 13:48:11 +02:00
|
|
|
The "etc/localhost_1" directory contains a configuration for a default
|
|
|
|
Sync4j installation on the local host and Evolution address book,
|
|
|
|
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.
|
|
|
|
|
|
|
|
The same configuration also exists for scheduleworld, but beware
|
|
|
|
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-04-09 13:48:11 +02:00
|
|
|
inside Evolution. SyncEvolution never creates databases
|
|
|
|
itself.
|
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
|
2005-12-10 20:16:02 +01:00
|
|
|
- normalize the files with the provided Perl script:
|
2006-04-17 17:59:33 +02:00
|
|
|
synccompare list1.vcf >list1.normal.vcf
|
|
|
|
synccompare list2.vcf >list2.normal.vcf
|
2005-12-10 20:16:02 +01:00
|
|
|
- compare the normalized lists, e.g.:
|
|
|
|
diff -c list1.normal.vcf list2.normal.vcf
|
|
|
|
|
2006-04-17 17:59:33 +02:00
|
|
|
Alternatively, one can invoke synccompare with two file names
|
2006-03-15 23:09:04 +01:00
|
|
|
as arguments and it will normalize and compare them automatically
|
|
|
|
with diff in the side-by-side mode:
|
2006-04-17 17:59:33 +02:00
|
|
|
synccompare list1.vcf list2.vcf
|
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-01-21 16:52:19 +01:00
|
|
|
different. The automatic unit testing (see HACKING) also contains
|
2006-05-01 11:23:41 +02:00
|
|
|
a "testItems" test which verifies the copying of special
|
2006-01-21 16:52:19 +01:00
|
|
|
entries.
|
2005-12-10 20:16:02 +01:00
|
|
|
|
|
|
|
Modifying either address book and synchronizing back and forth
|
2006-03-11 20:23:43 +01:00
|
|
|
can be used to verify that SyncEvolution works as expected. If
|
|
|
|
you do not trust SyncEvolution or the server, then it is prudent
|
2005-12-10 20:16:02 +01:00
|
|
|
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?
|
|
|
|
|
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
|
|
|
|
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
|
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
|
|
|
|
the Evolution database server, albeit in a limited way:
|
|
|
|
|
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
|
|
|
|
and server database that Evolution might be synchronized with.
|
|
|
|
|
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-03-12 23:31:52 +01: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-02-04 21:21:59 +01:00
|
|
|
- refresh-server results in a Sync4j client library error at the end
|
2006-04-06 19:02:43 +02:00
|
|
|
of the sync with the client library shipped with 0.2:
|
2006-02-04 21:21:59 +01:00
|
|
|
|
|
|
|
TestEvolution.cpp:534:Assertion
|
|
|
|
Test name: TestEvolution::testDeleteAll
|
|
|
|
assertion failed
|
|
|
|
- Expression: !res
|
|
|
|
|
2006-04-09 13:48:11 +02:00
|
|
|
With the current library source that is avoided, but a refresh-server
|
2006-04-06 19:02:43 +02:00
|
|
|
with empty local address book does not delete all items on the
|
|
|
|
server as it should, leading to:
|
|
|
|
|
|
|
|
TestEvolution.cpp:674:Assertion
|
|
|
|
Test name: TestEvolution::testDeleteAll
|
|
|
|
assertion failed
|
|
|
|
- Expression: countItems( source ) == 0
|
|
|
|
|
2006-03-19 22:37:30 +01:00
|
|
|
ObjectWeb #304806
|
|
|
|
|
2006-03-18 18:30:52 +01:00
|
|
|
- various vcard and special character related problems in the
|
|
|
|
Sync4j server and client library:
|
2006-02-04 21:21:59 +01:00
|
|
|
TestEvolution::testVCard fails the check that items
|
|
|
|
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-03-18 18:30:52 +01:00
|
|
|
Characters with special meaning in XML like & < > cannot be
|
|
|
|
exchanged.
|
2006-02-04 21:21:59 +01:00
|
|
|
|
2006-03-19 22:37:30 +01:00
|
|
|
ObjectWeb #304828, #304786, #304784, #304782
|
|
|
|
|
|
|
|
- error handling could be improved
|
|
|
|
|
|
|
|
ObjectWeb #304805, #304562
|
|
|
|
|
2006-04-17 19:28:07 +02:00
|
|
|
- calendar conversion fails resp. loses information
|
|
|
|
|
|
|
|
ObjectWeb #304946, #304993, #304994, #304995, #304996, #304997
|
|
|
|
|
2006-02-04 21:21:59 +01:00
|
|
|
- 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
|
2006-03-11 20:23:43 +01:00
|
|
|
SyncEvolution, please try to determine as good as you can
|
|
|
|
whether it is caused by SyncEvolution, the Sync4j 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
|
|
|
|
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.
|
|
|
|
|
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-01-21 16:52:19 +01:00
|
|
|
To compile the code the 3.x version of the Sync4j 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
|
|
|
|
Debian 3.1 (Sarge) you can install them with
|
|
|
|
apt-get install libcurl3-dev evolution-data-server-dev
|
|
|
|
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
|
|
|
|
SyncEvolution specific options. For the convenience of those checking
|
|
|
|
out from CVS directly, the files generated with "autogen.sh" are also
|
|
|
|
available from CVS.
|
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/
|