The Sync Module adds a Custom Hibernate Interceptor to know whenever something is going into the database. This requires that all changes to the database go through the API. If the changes do not go through the API, then the changes will not get logged and so will not get sent to the parent/child servers.

The hibernate interceptor stores the action into the sync_record table. Each transaction gets its own sync_record. A sync_record therefore can have multiple objects inside of it. Each sync_record is sent to the parent server and to each child server. The receiving server runs that sync_record on its own server, matching records using uuids.

Sync'ing Module Objects

All objects that go through hibernate that implement OpenmrsObject are sync'able. If your object implements that interface (or you can extend BaseOpenmrsObject for convenience) then sync will pick it up and know how to deal with it. Make sure that your module is installed on all the parent and child servers.

Sync_record and sync_server_record tables

On servers with children:

• As soon as a sync_record is written, a sync_server_record row is created for each child server. As changes are sent down to children, the sync_server_record rows are set to a status of COMMITTED.
  On servers without a parent:
• The sync_record rows will always have a status of NEW.
  On servers with a parent:
• The sync_record rows will change to COMMITTED after the record has been sent up to the parent

There is a scheduled task that cleans out old sync records. This task is enabled by default and set to delete at least 4 week old records every week. The logic behind this task is:

• if server has a parent (meaning this server is a leaf node or in the middle of the tree): delete all sync_record rows that are COMMITTED or NOT_SUPPOSED_TO_SYNC
• if server is root node (no parent, only children): delete sync_server_record rows that are safe to delete (aka, old and marked as COMMITTED or NOT_SUPPOSED_TO_SYNC), then delete rows irrespective of status in sync_record that have zero rows in sync_server_record

sync_record.original_uuid is the uuid of the first sync_record that caused this. If a record was created on itself, the uuid and original_uuid columsn will be equal. If the record was received from a child, the sync_record.original_uuid on the parent will be equal to the sync_record.uuid from the child. The sync_record.uuid will be different.

Sync_import table

This holds the data coming in from a parent or up from a child that has to be committed. Only holds uuids so that we know what we have received already and don't recommit something. When first put into the table the status is PENDING. Once it has been committed to the database the status is COMMITTED. If the server is a child server, once the status will change to COMMITTED_AND_CONFIRMATION_SENT once an ack has been sent back to the parent server. If a server resends a sync record, the uuid in the sync record will match up with the uuid in the sync_import table. That row in the sync_import table will then get a status of ALREADY_COMMITTED and the sync_record will not be written to the database.

Sync_server table

Defines all the parent and child servers

Sync_class and sync_server_class tables

These tables store information about what java classes cannot be sent to all or some servers. The sync_class table stores the global default information that all servers will inherit from by default. The sync_server_class holds specific restrictions for each child/parent server.

Note: New entries in sync_class DO NOT propagate to sync_server_class entries. Any new rows put into sync_class must be copied to current servers

If a java class or package is listed in sync_server_class and has a "zero" for send_to, then that object will never be sent to the respective server. If there is a zero for "receive_from", then that object will not be written to the database if its received from the respective server.

The Sync Module by default comes with several classes already excluded that clearly represent actions only intended for local server and therefore are not subject to sync: global properties, scheduler configuration, etc. While the sync user interface allows administrators to add/remove to this list of classes to customize their specific implementation, it is strongly recommended the defaults that come pre-installed are left as is.

(Back to Sync Module home page)