Wiki Spaces


Get Help from Others

Q&A: Ask OpenMRS
Discussion: OpenMRS Talk
Real-Time: IRC Chat | Slack


Page tree

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3


Sync Module
Symmetric Thread 1
Symmetric Thread 2


Steps Done upto nowA POC completed successfully by the end of GSoC 2012. Installing the developed module enables sync for your OpenMRS databases.

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: /home/user_name/.OpenMRS

Windows7: C:\Users\your_name\AppData\Roaming\OpenMRS

Step 1: First rename your existing Application data directory to something else so that the setup will run all new. This applies if you have already been using OpenMRS before this trial.
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,

Code Block
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 

Code Block
mvn jetty:run -Djetty.port=8042

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

Code Block
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. (As with the 2.x release of Symmetric)

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

3. IDatabaseWriterFilterAdapter extension point (As with the 3.x release of Symmetric)


5. Embedding SymmetriDS in an OpenMRS module, resolving dependencies, troubleshooting and configuring Symmetric nodes to start gracefully with specific configurations matching the embedded approach. (As with the 3.x release of Symmetric)

Module : org.openmrs.module.syncsds (SymmetricDS Sync Module)

SymmetricDS being embedded to an application causes a new Jetty instance to be spawned on new Thread (and perform data carriage on new defined ThreadPools). SyncSDS module consists of a new webapp directory to contain a web.xml to start symmetric with a Jetty instance. Installing the .omod on OpenMRS will spawn the Jetty and start Symmetric node which maps to that OpenMRS instance and its database. 


Client is configured such that if no node identity is found and it is not a root node (no registration url), to auto insert node, group, security and identity rows. Clients will not run any initial SQL scripts, but manage with the above. Registration number of attempts has been left at infinity, leaving the client to keep polling for a root node to register with.

Please find all configuration files also on the module svn location.

6. Known issues

  • Any changes to configurations on property files either on root or on client (ipaddresses, ports, database urls, database passwords) require the omod to be rebuilt.
  • Since the location for webapp/resourses to be held for an uploaded omod differs on whether OpenMRS.war is deployed on Tomcat or Jetty, user requires to notify on global properties which category he falls to.
  • Module activator gets called pointlessly after the module is stopped and results in an exception harmless to neither OpenMRS nor Symmetric.


  • Configure personal settings such as ip, port for Symmetric to run, your database specific property settings on the root and client property files.
  • Changes to node identity names, nodegroup names should be reflected on the SQL script on omod/src/main/webapp as well.
  • Prior to installing your omod, include the following global properties to your database.
    • syncsds.symmetric.nodeGroup            for root only : ‘root’
    • syncsds.symmetric.nodePort               for root : ‘8087’, for client : ‘8835’ (changes to values should result on property file configurations too)
    • syncsds.jettyUser                                 for OpenMRS jetty users: ‘true’, fot for Tomcat users: ‘false’
  • Deploy the OpenMRS war giving the following JVM option
    • -Djmx.http.console.for.embedded.webserver.enabled=false
    • eg: (for Jetty users) 
Code Block

mvn jetty:run -Djetty.port=8042 -Djmx.http.console.for.embedded.webserver.enabled=false

8. Youtube Video of synchronizing few patients

You can find a brief demonstration on [0] and a much more descriptive version on [1]



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. 


1st June - 10th June

Develop OpenMRS module to embed SymmetricDS jar.


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.

Completed for a subset of tables
Issues due to complex data
model discussed

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.

Allocated for troubleshooting module
encapsulation and extension development
- mentioned additional

15th August - 13th August

Test and document module


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)

Tested on 2 physical nodes
with 2 operating systems


Client & root specific configuration to get OpenMRS databases setup for Symmetric running on a new Jetty instance.
Includes a web.xml, sql script and configuration on properties files to fit the embedded approach, differing from the standalone approach