Customizing OpenMRS with Plug-in Modules

OpenMRS has a modular architecture which allows special functionality to be easily added or removed from the system. Modules have full access to the system and can modify or enhance the behavior of the system. For example, the Sync module adds the ability for an OpenMRS server to synchronize its data with other OpenMRS servers; the HTML Form Entry module provides a way to create web-based forms for collecting data; and the Flowsheet module adds a new way for viewing information. Modules also provide a mechanism for adapting OpenMRS to local needs. For more information about published modules visit the OpenMRS Wiki:

http://go.openmrs.org/book-modules

Module Repository

You can view available modules in the OpenMRS Module Repository:

http://modules.openmrs.org/

It is a place where you can find published modules. Each module has a page with a description, a link for downloading, and a link to the module's documentation.

Some modules may be under development, but not yet published in the module repository. Many of these can be seen by browsing the "modules" section of the OpenMRS Subversion code repository

http://svn.openmrs.org/openmrs-modules/

Managing Modules

You can see available modules under Administration page, Manage Modules. The listing contains all the installed modules. You can see here their status (if they are started, stopped or failed to start) as well as uninstall them.

Stop the module
Start the module
Uninstall the module

A module is distributed as a single file with the .omod extension. You can install it from the dedicated Manage Modules section on the Administration page.

You can either point to a local path to the .omod file or find and install a module directly from the Install from Module Repository section which connects to the module repository.

Choose a file and click Upload
Search for a module by name
Install the chosen module

If uploads are not allowed from the web, you can copy the .omod file into the folder:

~/.OpenMRS/modules

(Where ~/.OpenMRS is assumed to be the Application Data directory which the running OpenMRS is currently using. You can find the precise location under Administration > Module Properties.) After moving the file to that location, restart OpenMRS. The module will be loaded and started.

Bundled modules

OpenMRS is delivered with some bundled modules which are included in a standard installation. The list may differ from version to version. OpenMRS 1.8 contains:

HTML Form Entry

Allows anyone with basic HTML programming skills and knowledge of the OpenMRS system to create forms which can be entered without any proprietary tools directly from a web browser. It is a preferred form entry module. HTML Forms allow a lot of control over the form's layout. http://go.openmrs.org/book-htmlform

XForms

Allows data entry to be done directly from any JavaScript enabled browser. The module converts an OpenMRS form to an XForm. XForms are well-suited to forms that will be filled out on mobile devices. http://go.openmrs.org/book-xforms

FormEntry

Allows a form's content to be designed in InfoPath, and then allows end users to fill out the form and submit it to OpenMRS. OpenMRS is moving away from the InfoPath format because InfoPath is proprietary and difficult to troubleshoot. http://go.openmrs.org/book-formentry

HTML Widgets

Provides a set of reusable HTML form field widgets in order encapsulate the common input requirements for OpenMRS. It is meant to be something that developers can utilize in their code. http://go.openmrs.org/book-widgets

Reporting

The Reporting module provides a feature-rich and user-friendly web interface for managing reports within OpenMRS. http://go.openmrs.org/book-reporting

Reporting Compatibility

Was written for the 1.5 and later releases of OpenMRS. It contains pages and features that were previously included into OpenMRS core code itself and are needed to run the Reporting module. http://go.openmrs.org/book-compat

Serialization XStream

Provides an implementation of serialization/deserialization strategy using the XStream library. http://go.openmrs.org/book-serial

Other popular modules

Clinical Summary

Allows you to create clinical summaries. http://go.openmrs.org/book-clinsum

Groovy

Was created as a proof of concept (for embedding Groovy into OpenMRS) and to serve as a base module for other modules that want to use Groovy scripting as well. http://go.openmrs.org/book-groovy

HTML Form Flowsheet

Allows you to generically model a paper flowsheet. Provides basic functionality for embedding small HTML Forms inside of larger HTML Forms, where each small HTML Form represents one row in a patient chart. Additionally, the module allows you to specify any number of tabs in a tab-based layout, each containing a distinct HTML Form. http://go.openmrs.org/book-hff

HTML Form Entry Designer

WYSIWYG Form Designer for the HTML Form Entry Module. http://go.openmrs.org/book-hfed

ID Generation

Provides a facility for managing identifier generation and allocation within an OpenMRS implementation. Introduces different identifier generation strategies including automatic and pooled. http://go.openmrs.org/book-idg

Metadata Sharing

Allows all kinds of metadata (concepts, HTML forms, locations, roles, programs, etc.) to be exchanged between different OpenMRS installations. http://go.openmrs.org/book-mds

Request Account

Allows users to request their own accounts, specifying their own preferred username and preferred password. An administrator can then approve or deny pending account requests. http://go.openmrs.org/book-reqacct

REST Webservices

The module exposes the OpenMRS API as REST web service. http://go.openmrs.org/book-rest

Role Based Homepage

Allows for administrators to define a custom "Home Page" for each defined Role within the system. These Home Pages may be simply pages that already exist, and which particular users would be best served to have as their default. For example, System Administrators may want the Administration page as their default home. Alternatively, administrators can "author" new pages within the running application for their users. http://go.openmrs.org/book-rbh

Synchronization

Fits in scenarios when you have multiple sites using OpenMRS with separate databases and you want them to copy data to each other that is keep them synchronized. http://go.openmrs.org/book-sync

Writing Your Own Module

This section covers basics of writing your own module. We encourage to contribute modules you write to the Module Repository. You can also use our code repository for your module. For more information how to gain access to both please visit this page

http://go.openmrs.org/book-svnrepo

In order to develop and test a module you will need to have OpenMRS installed in a version on which you want to run your module.

To create a new module it is best to use a dedicated Maven archetype. Before you start you will need to have maven installed. See the Maven web site at http://maven.apache.org/ for more instructions.

The next step is to update the settings.xml file to point Maven to the Maven Module Archetype. You can find the file in one of the following locations:

Linux: ~/.m2
Windows XP: C:\Documents and Settings\user_name\.m2
Windows Vista/7: C:\Users\user_name\.m2

If it does not exist you need to create one. Add the following content:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"

  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">

  <pluginGroups>
    <pluginGroup>org.openmrs.maven.plugins</pluginGroup>
  </pluginGroups>
  <profiles>
    <profile>
      <id>OpenMRS</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      <properties>
        <archetypeCatalog>http://mavenrepo.openmrs.org/nexus/service/local/repositories/releases/content/archetype-catalog.xml</archetypeCatalog>
      </properties>
      <repositories>
        <repository>
          <id>openmrs-repo</id>
          <name>OpenMRS Nexus Repository</name>
          <url>http://mavenrepo.openmrs.org/nexus/content/repositories/public</url>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>openmrs-repo</id>
          <name>OpenMRS Nexus Repository</name>
          <url>http://mavenrepo.openmrs.org/nexus/content/repositories/public</url>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>

</settings>

Maven is a command line tool so open a console and enter the folder where you want to have a project for your new module created. The command you need to run is:

mvn module-wizard:generate

Follow the steps of the wizard by answering the questions. In the end you should have a new Maven project generated. To build it you just need to enter the project folder and run:

mvn install

You will find the produced .omod file for your module in the directory omod/target.

Developing a module requires from you to be familiar with the Spring framework. Read the Spring web site at http://www.springsource.com/ for more details. There are also a few things specific to the OpenMRS platform which you will need to remember:

The Spring web context file can be found at omod\src\main\resources\webModuleApplicationContext.xml.
Modules are able to add and modify tables in the OpenMRS database. The files omod\src\main\resources\sqldiff.xml and omod\src\main\resources\liquibase.xml hold the SQL commands which can be executed as module is installed.
Modules can extend OpenMRS core JSP pages via extension points. A module registers an extension in omod\src\main\resources\config.xml for each extension point in the system to which it wants to add content.

You should find extension points in the JSP pages you want to extend. Look for:

<openmrs:extensionPoint pointId="..."

It is best to learn by example, so you should look at some other modules in the OpenMRS code repository for code snippets to reuse in your own work. Consider examining the Webservices.rest module.