Hyper Open Edge Cloud

How To Use SyncML Tool

How To showing how to distribute data on different sites without need for persistent interconnections.
  • Last Update:2016-02-09
  • Version:001
  • Language:en

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.

ERP5 HowTo | SyncML - Screenshot Conflict

Documentation written by Fabien Morin fabien.morin@gmail.com

Related Articles