Write Modules, Save Lives – Part 1

Following is the article on OpenMRS module development that I wrote for Linux For You (July, 2012 Edition) . This article is released under CC by SA by Linux for You.

OpenMRS, a widely used Electronic Medical Record system, is a community-developed, open-source, and enterprise-grade platform. Its core is very thin, and almost every functionality is provided through pluggable modules. It’s robust enough for a nationwide health-care system, and nimble enough for a field-based clinic. This article series will cover how to do OpenMRS module development, and is aimed at J2EE developers, and people who want to contribute to OpenMRS.

A lot of OpenMRS modules exist, and the list is constantly increasing. A detailed list is available at https://modules.openmrs.org/modules/. OpenMRS offers functionality to directly install/update modules through a Web interface—on the fly, without restarting Tomcat.

This first article in this series will cover the basics of the OpenMRS architecture and how to install, update, stop and start a module in OpenMRS. The OpenMRS is built on the Spring and Hibernate Stack and uses MySQL as the database.

Basic architecture

Figure 1: Typical architecture of the OpenMRS stack

The components are:

  • Spring: An application development framework for developing MVC architecture applications.

  • POJO: Plain Old Java Object.

  • Hibernate: The Java persistence framework project, performs powerful object-relational mapping, and queries databases using HQL and SQL.

  • DAO: Direct Access Object

  • Liquibase: Database-independent library for tracking, managing and applying database changes.

An interesting fact about OpenMRS modules is that they are like mini subsystems that can not only communicate with OpenMRS core services, but can also have their own services and schema that can be used by other modules. This makes modules flexible enough to be independent of the system, and robust enough to be dependent on each other, if required.

Module installation

Note: Installing modules through the Web interface is disabled by default (for security purposes). To enable it, set the ‘module.allow_web_admin‘ runtime property to true and restart the application.

  1. Download the module to the local filesystem.

  2. Go to the Manage Module page on the administration page, then click Add or Upgrade Module.

  3. After this, select the .omod module file you downloaded, and click Upload.

  4. The module will be installed without restarting the server. Note that each time an action is taken on a module, the OpenMRS context is restarted. When a module is loaded, database changes in Liquibase that will be required by the module (if any) are applied to the database.

The module is now accessible to everyone privileged to use it. Modules can have granular privileges i.e. any specific set of roles as required by the module.

Note: There are other ways of installing modules, like directly searching the OpenMRS modules repository and installing directly from the repository—or dropping the .omod file in the defined module repository folder.

Module start/stop

Go to the OpenMRS module management page and click the red button to stop it, or the green button to start it. During this, no database changes made by the module are lost; only the OpenMRS context is restarted, and the module is started or stopped.

Module updates

You can check for updates to modules by clicking the Check For Update button on the Manage Modules page. You can also upload a newer version of the module through the Web interface, or directly dump the module file to the OpenMRS module repository.

On an update, first the old module is removed. After that, database changes from the previous version to the newer version (i.e. with different IDs) are applied to the database. Then the module is loaded.

Module deletion

To delete a module, in the module management page, click the grey icon next to the module you want to delete. Any database changes done by the module are not deleted. The OpenMRS context will be restarted after removal of the module from the module repository folder.


  • List of OpenMRS sites: http://openmrs.org/about/locations/

  • OpenMRS module repository: http://modules.openmrs.org/

  • Most downloaded modules: https://modules.openmrs.org/modules/stats.jsp