ERP5SyncML is a synchronization engine based on the SyncML protocol which makes
it possible to distribute the data on several sites without need of a permanent
and rapid connection between these sites. That also allows the mobile users
(phone, PDA,...) to use ERP5 without permanent connection.
Table of Contents
Installation¶
The following list of business templates and their dependencies needs to be
installed: erp5_base, erp5_core. For business template installation guide
see HowToInstallBusinessTemplates
The 4Suite API is used to parse xml messages, so you must install it (a
rpm is avaible for mandriva 2007.1, and you can find source code at http://sourceforge.net/projects/foursuite/)
Install site instances¶
If you want to do synchronization, you should have at least two Site instances.
One of them has to be a master and all other have to be clients. Any modification
made on any Site will be sent to the master, and the master send back each
modification to each client. Like this, all Sites (master and clients) are
informed about modifications.
Let's say we have one zope running on our local box. We will create for example
two Sites, the fist one wich will be the master with the id 'erp5_server', and
the second one wich will be the client with the id 'erp5_client1'.
If you want to make sure that your box is installed correctly, you should go
on one object of your site and then add to the url the method 'asXML' like this :
http://localhost:9080/erp5_server/person_module/1/asXML
If everything is fine, you should have no errors and you should see the xml
corresponding to your object.
How to Install the synchronization tool¶
Go to the zope management interface and then add to all your sites (master and clients) an ERP5SyncML Tool.
The last thing to do is to configure your synchronization tool inside the zope
management interface. You have in this tool many tabs. The 'publication' tab is
used on the server and the 'subscription' tab is used on all clients. A publication
is a setting for something we want to share with others. So on the master we have
to specify as many publication as the number of folders we want to share. A
subscription is a setting for something we want to synchronize from a master,
so on each client we have to specify as many subscriptions as the number of
folders we want to synchronize with the master.
I do have on my server side the following publication :
- Title: Person
- Use Activity: Unchecked
- Publication Url: http://localhost:9080/erp5_server
- Destination Path: /erp5_server/person_module
- Source URI: Person
- Query: objectValues (it will be completed automatically)
- XML Mapping: asXML
- Synchronize with other ERP5 sites: Checked
- Content Type: application/vnd.syncml+xml (it will be completed automatically)
- Conduit: ERP5Conduit
- GPG key name: (it can stay empty)
- Id Generator: generateNewId
- Gid Generator: getTitle
- Media Type: text/xml
- Authentication Required: Checked
- Authentication Format: b64
- Authentication Type: syncml:auth-basic
I do have on my client side the following subscription (for me, the subscrption
and publication are on the same computer but you could have, someting else than localhost) :
- Title: Person
- Use Activity: Unchecked
- Publication Url: http://localhost:9080/erp5_server
- Subscription Url: http://localhost:9180/erp5_client1
- Destination Path: /erp5_client1/person_module
- Source URI: Person
- Target URI: Person
- Query: objectValues (it will be completed automatically)
- XML Mapping: asXML
- Synchronize with other ERP5 sites: Checked
- Content Type: application/vnd.syncml+xml (it will be completed automatically)
- Conduit: ERP5Conduit
- GPG key name: (it can stay empty)
- Id Generator: generateNewId
- Gid Generator: getTitle
- Media Type: text/xml
- Login: syncml
- Password: ******
Explanations:
-
Title: the title is used to identify the Subscription/Publication
if there is a several of them on a same computer.
-
Use Activity: this check box is used to activate or not the
use of activity. With activity, the synchronisation time should be more
important (about 2 times slower), but more safe, and could be continued after
a crash.
-
Publication Url: this is the url of the publication site
where we want to synchronize to.
-
Subscription Url: this is the url of the subscription site.
-
Destination Path: the url of the destination directory we
want to synchronize to.
-
Source URI: this option is usefull to synchronize an erp5
site with an external server (like http://www.memotoo.com), in case of
synchronization between erp5 sites, it sould be the same as the Title
property.
-
Target URI: like Source URI, Traget URI must be the same
as Title property in case of synchronization between erp5 sites.
-
Query: by default, the query is objectValues wich return
a list of all objects, but for more speed, it's better to make a script who
accept the gid in parameter. For my synchronization, I'm using a script that
I have called PersonModule_getPersonList and who permit to synchronize much
more quickly. A give the script afterwards.
-
XML Mapping: the xml mapping is used to send data synchronization.
asXML script will return the xml corresponding to the object where it will applied,
but for specific use, you can write your own XML mapping. I write one to
synchronize VCard : PersonExportAsVcard
-
Synchronize with other ERP5 sites: The method currently used
to send data to erp5 and external sites is not the same (it will be improved soon).
-
Content Type: the type of content use to exchange data (could
be 'application/vnd.syncml+wbxml' or 'application/vnd.syncml+xml' for example)
-
Conduit: the conduit is a piece of code in charge of updating
an object attributes from an XUpdate XML stream. If you want to synchronize
other things that the “clasic” erp5 objects, you must write your own conduit.
- GPG key name: a name of gpg key to use
- Id Generator: This set the method name wich allows to generate a new id
- Gid Generator: This set the method name wich allows to find a gid from any object
-
Media Type: the type of media exchanged between publication
and subscription. Currently, only two types of media are supported : text/xml and text/vcard.
-
Authentication Required: If this box is checked, the publication
will ask a login and password to the subscription when it tries to get or send data.
-
Authentication Format: the format used to encode the login
and password. Currently, only b64 is supported, but it's very easy to add other format.
-
Authentication Type: the type of the authentication, according
to syncml specifications. Currently, only syncml:auth-basic is supported
-
Login: the login used to authenticate the subscription on the
server. The login must exist on the server. It makes it possible to set up restrictions
and to make a follow-up on the synchronizations because the objects created will be
with the login entered here.
- Password: the password should correspond to the Login
Note: If you don't want authentication, you can leave the
field Login and Password empty on the subscription (but it is not an obligation)
and you must uncheck the Authentication Required checkbox on the publication
side (and you can leave empty the Format authentication and Type authentication
fields but it is not an obligation).
My script PersonModule_getPersonList:
#Parameter List : gid=None, **kw
if gid is not None:
kw['title'] = gid
object_list = [x.getObject() for x in context.person_module.searchFolder(limit=None, **kw)]
return object_list
How to start a synchronization¶
The synchronization starts only from a client, so you should go on one of the
client instance. Then you have to go on the portal_synchronizations and select
one of the subscriptions and hit Sync.
The Reset button erase all signatures on the side where it's hit, that means that
next synchronization will be a SLOW SYNC (= 201 synchronization code). if the
server reiceives a 201 alert code, it erases all of his signatures.
If you want to see the xml messages transferring between the two sites, you have two ways :
- use a software like tcpdump or wireshark
-
watch the log of the instance (the easiest way):
tail -f /var/log/zope/event.log
How to resolve conflict¶
There is some case, where after a synchronization, the data coudn't be merged,
this is a conflict. Typically it's append when a data is modified on a client
and the same data (on the same object) is modified on another client or on the
server, after a synchronization, a conflict appear in the Conflicts tab of
portal_synchronization (on the server only).
To resolve a conflict, it's very easy : In the Conflicts tab, you can see all
the conflicts with the publisher and the subscriber values, you just have to
chose the version you want to keep by clicking on Subscriber or Publisher.
Documentation written by Fabien Morin fabien.morin@gmail.com
Related Articles¶