Child pages
  • Database Synchronization with Symmetric DS
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 13 Next »

Primary mentor


Backup mentor


Assigned to


Commonly, OpenMRS is deployed and implemented in resource-poor settings where internet connectivity is not 100% reliable. At the same time, many implementations in these environments want a unified system in which each facility has a common view of all data. To address this, OpenMRS has invested a lot of time and effort into the development of a Synchronization module that performs bi-directional synchronization across all configured servers. Partners In Health supports implementations in both Rwanda and Haiti that use this synchronization module to support local servers that provide fast, reliable access to data across multiple facilities.

The paradigm employed by the current synchronization module is one of API-level synchronization. All changes made via the API and persisted to the database via hibernate are captured, logged, and transmitted to the other servers in the network through a central "parent" node. This approach, although relatively successful, has a number of drawbacks. One is that it puts the burden of maintaining database synchronization on the application. This opens up a number of failure points and has proven fairly maintenance intensive. Another is that it does not allow for any direct manipulation of the underlying database, limiting certain system integration options, and complicating support and maintenance.

The goal of this project is to develop an alternative synchronization paradigm using SymmetricDS. SymmetricDS, from it's website, describes itself as "an asynchronous data replication software package that supports multiple subscribers and bi-directional synchronization. It uses web and database technologies to replicate tables between relational databases, in near real time if desired." Phase 1 of this project would be to build the necessary tools and configuration to successfully synchronize a single database table across 2 OpenMRS instances. Phase 2 would be to support all tables (via web configuration) in the OpenMRS schema.


  1. Set up two duplicate OpenMRS instances and configure SymmetricDS to successfully synchronize the "person" table.
  2. Support bi-directional sync that supports periods of downtime, and which implements simple conflict resolution:
    • Likely involves customization of SymmetricDS via creation of a custom IDataLoaderFilter.
    • Likely involves matching of uuids rather than primary key ids if uuids are available on the table. Otherwise a last-update-wins approach.
  3. Develop a new OpenMRS module
    • Ideally "embeds" symmetricDS as a library rather than depending on an external setup
    • Facilitates configuration by automatically setting up synchronization for all tables in the OpenMRS schema
    • Provides a UI for changing / enabling / disabling synchronization on individual tables.


Sync Module
Symmetric Thread 1
Symmetric Thread 2


Steps Done upto now

1. Setup two OpenMRS instances

  • Done. Completed as specified on Wiki - Multiple Instances with the renamed .wars of omrsroot and omrsclient running on 2 ports for jetty. Independent two databases and 'omrsroot' and 'omrsclient' for sync, and having individual application data directories.

Steps to setup a root instance and a client instance for the project demo purpose
Folders referred to steps given below.
OpenMRS checkout location=OpenMRS-1.x.x
Default Application Data Directory=
Linux: .OpenMRS
Windows7: C:\Users\your_name\AppData\Roaming\OpenMRS

Step 1: First rename your Application data directory to something else so that the setup will run all new.
Step 2: Make two copies of OpenMRS.war and rename them to root.war, client.war inside OpenMRs-1.x.x/webapp/target
Step 3: Go to OpenMRs-1.x.x/webapp,

mvn jetty:run -Djetty.port=8042

Set up OpenMRS using the Advanced option where you can name your own database. Name the database to rootdb.
Step 4: Exit Jetty. Now you once again have a new Application data directory created. Rename this to something else. Say OpenMRS_root.
Go inside, copy all the folders and files. Create a new folder where you prefer. eg: OpenMRS-1.x.x/webapp/root. Paste the copied content inside this folder. So root is your new Application data directory for the root instance we are going to try.
Step 5: Open the runtime properties file inside this folder, paste the following line in it. We are letting the root-runtime properties know where to find its own application data directory, with its own modules seperated from another instance's ones.
Copy the edited file to OpenMRS-1.x.x/webapp from where you run the mvn jetty run command.

eg: application_data_directory=root

Note: This path is relative to the new placement of (Additionally, you may paste the same to OpenMRs-1.x.x/webapp/target where the .war actually resides, for safety :) )
Cool, so the root is setup. Run the command 

mvn jetty:run -Djetty.port=8042

to see your working root OpenMRS instance!
Step 6: Repeat step3 with the client.war. eg:

mvn jetty:run -Djetty.port=8047

And name your new database to clientdb
Step 7: Repeat step 4 with renaming to OpenMRS_client. Let the new folder you create be OpenMRS-1.x.x/webapp/client for example. So client is your new Application data directory for the root instance we are going to try.
Step 8: Repeat step 5 with

eg: application_data_directory=client

Now the client is all setup!
So by the end, you will have 2 OpenMRS instances you can run at the same time.As for my example, 
root on localhost/8042, with rootdb, and appdata directory=root
client on localhost/8047, with clientdb, and appdata directory=client

2. Configure SymmetricDS for the two OpenMRS instances. Then Synchronize the Person table.

  • Registering and starting nodes
  • Send loads, push/(and) pull data.


The testing and documenting for early stages will go inline with development.

Time Period

Suggested Workflow


23rd April - 21st May

Community Bonding Period


21st May - 31st May

Bi-directionally synchronize person table on 2 OpenMRS instances. 

(minor issue reported)

1st June - 10th June

Develop OpenMRS module to embed SymmetricDS jar.

(web.xml to be resolved)

11th June - 9th July

Develop means to identify & resolve conflicts arising through bi- directional synchronization. Implement IDataLoaderFilter.
The module will include developed filter functionality at the end.

In Progress

9th July - 16th July

Configure SymmetricDS for synchronization of all tables in OpenMRS schema. Include this in the on-going module.


16th July - 5th August

Develop the UIs for authenticating & configuring SymmetricDS.
Develop the UI to give the user ability to enable/disable and thus control synchronization for individual tables.


15th August - 13th August

Test and document module and developed filter functionality


13th August - 20th August

Getting feedback from community. Test on multiple physical nodes for network latency and other practical issues.
Implement security and monitoring functionality (If time permits as suggested above)


UI Mockups Proposed

Linking page from Personal Space

  • No labels