OpenMRS
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:
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 their status (if they are started, stopped or failed to start) as well as uninstall them.
To uninstall a module:
- 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.
To install a module:
- 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 exact 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: (UPDATE THIS FOR v1.9)
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 that 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
Provides a feature-rich and user-friendly web interface for managing reports within OpenMRS. http://go.openmrs.org/book-reporting
Reporting Compatibility
Contains pages and features that were previously included into OpenMRS core code itself and are needed to run the Reporting module. It was written for the 1.5 and later releases of OpenMRS. 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
Exposes the OpenMRS API as REST web service. http://go.openmrs.org/book-rest
Role-based Home Page
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 will 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, 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.
It is best to use a dedicated Maven archetype to create a new module. Before you start you will need to install Maven. 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 the settings file 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 in which to create a project for your new module. The command you need to run is:
mvn module-wizard:generate
Follow the steps of the wizard by answering the questions. At the end, a new Maven project will be 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 a 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.