Epic - Reference Application


The OpenMRS Reference Application is a sample EMR application running atop the OpenMRS API.  OpenMRS has always had a web application component; however, the web application focused primarily on basic administrative features and lacked most content, leaving it up to modules and administrators to provide EMR functionality and content.  The Reference Application, on the other hand, strives to provide more of a starter set of content along with basic EMR functionality (e.g., registration, basic reports, etc.).  The web application framework upon which the Reference Application is based comprises a handful of new modules that run within the existing web application and provide a new, Groovy-based framework for more agile web development.

As of May 2013, the Reference Application is a work in progress, porting the work done using the Reference Application framework at Mirebalais Hospital in Haiti to become a generic application for the OpenMRS community.


Here's the architecture diagram we drew after a meeting including representatives from PIH, Thoughtworks (Mirebalais and JSS teams, and advisors), and OpenMRS.

Layers (bottom-up)

  • Framework (existing)
    • Core OpenMRS API (effectively our low-level data API)
    • APIs from key existing modules (Reporting, HTML Form Entry, XForms, IDGen, etc)
  • Framework (new)
    • App Framework module: a thin module to support the pluggable app paradigm, but without defining a UI
    • EMR API module: a thick module that provides high-level APIs relevant to a clinical EMR, to complement the low-level data API of OpenMRS core. Makes opinionated decisions about how to represent common medical concepts in the underlying data model. No UI.
  • UI-layer libraries and utilities
    • UI Library: reusable components and widgets (CSS, HTML templates, JS). Assumes that you will use the OpenMRS Reference Application Style Guide, but does not assume you're using any particular server-side or client-side UI Framework. (Not necessarily
    • UI Framework module: helps you develop traditional server-side code, facilitating rapid application development in line with the OpenMRS module framework.
    • Offline Library: common tooling to support apps that want to cache metadata and data so they can be used offline
  • Apps
    • To support reusability and sharing of building blocks, most user-facing functionality should be build as "Apps". An OpenMRS module may provide 0 or more apps.
    • Implementation projects will create apps for their own purposes.
      • Sometimes we will be able to "harvest" these for inclusion in the OpenMRS Reference Application, or for use by other implementations.
      • Often these will be custom apps of little interest outside the implementation. This is not a problem.
    • For the Reference Application we'll allocate some work into finding/improving/bundling/building apps for common use cases (registration/check-in, triage/vitals station, patient search, chart review, reports, etc)
  • Distributions
    • Apps are intended to be reusable and pluggable building blocks. A "Distribution" is a particular combination of OpenMRS modules, plus configuration to wire together those building blocks.
    • Typically contains: CSS, XML configuration, Metadata Sharing packages
    • PIH is building the Mirebalais module to represent the Mirebalais Hospital distribution
    • Thoughtworks will build a JSS distribution
    • OpenMRS's core team will build a "Reference EMR" distribution

App Framework

Reference Application

Included Modules

Reference Application

Glue that ties together and configures some of these other modules.

Defines the login and home screens.

Reference Metadata

Includes the "content" for our Reference Distribution. E.g. Roles, Encounter Types, Concepts.

Eventually this will include sample clinical forms as well.

UI Commons

Standard CSS and UI elements, that can be used across apps to build consistent APIs.

This module also contains (or should contain) a small number of highly-reusable standard messages that you can rely on living for a long time.

Core Apps

Core set of apps including Find Patient and Patient Dashboard.

Also includes common HTML Form Entry tags, e.g. <encounterDiagnoses/>

Registration AppApp and UI for "Register a Patient". (Much of the business logic for this lives in the Registration Core module.)
DispensingApp for recording that meds were dispensed to a patient. (This will only cover a very simple workflow. We do not intend to expand this module into a "real" dispensing system, and we explicitly will not expand it to track inventories. This function should be covered by an external system, or a module built for this purpose.)
EMR APICommon OpenMRS APIs for EMR workflows. (Generally these APIs are higher level than the ones in core.)
Registration CoreCommon OpenMRS APIs for registering new patients (progressively searching for duplicates, etc). We do not use any UI from this module.
Id GenCommon OpenMRS API for generating patient identifiers. You may use this directly, or use the "primary identifier type" defined by the EMR API module
Reporting ModuleCommon OpenMRS API for querying for cohorts and datasets. We use its calculations, but not its UI.
Provider Management ModuleUsed for "Provider Types". (This module contains quite a bit more functionality, but we are not interested in that for the reference application.)
App Framework ModuleFramework for building the full application out of smaller self-contained pieces
UI FrameworkFramework for building server-side pages and fragments, using Java and Groovy
Calculation Module

Framework for calculating data points about patients or groups of patients.

(Any reference application code should use this, and not the Logic module.)

Metadata Sharing ModuleWe use this to import/export the packages of "content" in the reference application. (See the Reference Metadata module.)
HTML Form Entry ModuleFramework for defining data-collection forms without significant programming skills in a way that nicely integrates into the application's UI.
HTML Form Entry 1.9 extensionsAdds a few necessary HTML Form Entry tags (e.g. <encounterProviderAndRole/>) needed for working with OpenMRS 1.9+

Includes our standard page decorators, header, and includes. It also gives the UI Framework access to the App Framework's SessionContext.

(This module exists to tie together the App Framework, UI Framework, and UI Commons modules, which are intentionally independent of each other.)

EventFramework for loosely coupled inter-module communication. (We don't use this much yet, but we'd like to base a lot of the architecture on it.)

Framework that lets us publish our APIs RESTfully.

(We don't do this much yet, but it's a fundamental part of our intended architecture.)

Metadata MappingRequired by the Metadata Sharing module.
Serialization.xstreamRequired by the Reporting module
HTML WidgetsRequired by the Reporting module
Logic ModuleRequired by OpenMRS core. We do not use this module, but prefer the Calculation module
UI Library

(To be removed.)

It is included because it is required by the Provider Management Module (for the functionality we don't use).

Paper Record(To be removed.)


Continuous Delivery Pipeline

Below is the current state of the Deployment pipeline in Bamboo.