OpenMRS Reference Application 2.x Implementer Documentation

Reference Application 2.9.0


Reference Application 2.9.0  is a release of our new Reference Application, a state of the art implementation of OpenMRS, which may serve as a solid base for new implementations. It is designed using the latest UI 3.x and App Framework, which make it easy to add new functionality as small apps in a similar fashion to mobile applications. The Reference Application comes with a number of apps out of the box. Currently we provide apps, which enable you to:

  • Register patients
  • Start and end visits
  • List patients with active visits
  • Admit/transfer/discharge patients
  • Take clinical notes
  • Capture patient vitals
  • Display patient summary and visit history.
  • Capture allergies
  • Enter forms from the patient dashboard
  • Patient request/scheduling appointment
  • Patient's condition list
  • Dispense medication
  • Attach patient note

Try It Out!

Hosted Demo Server 

You can explore the latest released version of the Reference Application by going to and signing in with the following credentials:


Each user has access to different parts of the application and we encourage you to explore them all.

Note that this server is reset every 24 hours, so if it is unresponsive or the entire site seems down, please try again in 10-15 minutes.


You can download a standalone version of this release from The first time you run this you have the option of setting up demo data or not.


You can run the OpenMRS Platform with the Reference Application modules on top of it. These are two separate downloads at ("Platform", and "Modules & Data").

Demo patients

If you want to see demo data on top of an Enterprise installation, go to Advanced Settings and set "referencedemodata.createDemoPatientsOnNextStartup" to the number of demo patients you want to create, then restart your servlet container. (Creating demo patients is a bit slow, so we recommend creating <50 the first time you try this.)

Legacy OpenMRS vs. Reference Application

The Reference Application is built on top of the OpenMRS Platform 2.x, which still includes the Legacy User Interface (the original web application). You can still download and use the legacy application. See the download page. (for legacy UI module)

The Reference Application is a set of modules that are installed in addition to the legacy OpenMRS web application. It means that when you install the Reference Application, you can still access all the features of the legacy application, however we keep them hidden from users by default.

Required Initial Configuration

For all features of the reference application to work well, you will need to make the configurations below:

  • To register a patient, the logged in user needs to have an associated provider account, meaning no patient registration will be possible if there is no user that has a provider account and yes this includes super user. Go to System Administration - Manage Accounts - Add New Account to add a new user and provider. Remember to create both a user account (with appropriate privileges) and a provider account.

Advanced Configuration

You can find more info about configuring the reference application here.


As mentioned previously the Reference Application is built of small apps. There are a couple of apps provided out of the box and we expect to improve them and increase their number over time. The apps that come with the Reference Application focus on basic functionality. They are designed and developed in a way that satisfies as many use cases as possible and also can be adjusted to specific needs. In this paragraph we will describe features that come with the Reference Application and their configuration options.

Location based login

When you first open up the Reference Application you will see a login screen.

You can login as a system developer with full privileges by giving the default username admin and password Admin123. You also need to select Location for this session. (For more details see here.) Locations are configurable from Advanced Administration - Manage locations. In order for a location to appear on a login screen you need to open it up and select a checkbox next to the Login location tag.

You should change the system developer password by going to System Administration - Advanced Administration - Manage Users. Search for admin, pick it in results, change the password and hit Save.

Role based home page

You can see all apps that are available in your installation by logging in as a system developer and opening the home page.

Less privileged users do not see all apps, because they are hidden if they don't have privileges to use them. We have defined a set of application and organizational roles, which you can use, modify or create new as needed. Organizational roles inherit from application roles. Roles start from "Application:" or "Organizational:", e.g. "Application: Writes Clinical Notes" or "Organizational: Doctor". You can view all roles by signing in as an administrator and going to System Administration - Advanced Administration and Manage roles.

If you open a role you can see which privileges it has. In the Reference Application we assign API level privileges to all roles automatically and limit access by assigning UI level privileges. You can easily distinguish the two, because UI level privileges start from "Task:" or "App:". Task privileges relate to specific features available in apps, whereas App privileges limit access to whole apps.

If you have a starter implementation you must create users from System Administration - Advanced Administration - Manage Users and assign them organizational roles. In demo data we have created 3 users for you: doctor, nurse and clerk.

When you create users, you need to create providers as well, otherwise they will not be able to enter data. Go to System Administration - Advanced Administration - Manage Providers and bind a new provider with a previously created user.


The Reference Application is partially translated into several languages. (To see how to contribute translations, or just see the current status, see Translating the Reference Application.)

Each user account has a "default locale" that is applied when they log in. The administrator can set this when creating a user account, or a user can change it on their own from My Account (under their username in the header):


...then by choosing Default Settings and setting the Default Locale

The next time the user logs in, they will see the UI in the newly-selected language.


The registration app is available under the Register a patient button from the home page. It is seen by users having the "Application: Registers patients" role. 

The registration form supports keyboard navigation. You can go to a next field by hitting the TAB or ENTER key. Going backwards is possible with SHIFT + TAB.

All fields are being validated and you cannot advance if you do not provide a correct input. In order to move to next field, you must pass the validation.  For example, you must enter Given and Last Name before moving to enter Gender, unless Unidentified Patient checkbox is ticked.

The registration app has an auto-complete feature for given and family names. It displays suggestions based on a selected algorithm. The default auto-suggestion works given an administrator entered a list of names under Advanced Administration - Settings - Registrationcore - Given Name Auto Suggest List. On the same page you can change the default auto-suggestion algorithm by replacing Patient Name Search: registrationcore.BasicPatientNameSearch with registrationcore.NamePhoneticsPatientNameSearch (uses the Name Phonetics module) or registrationcore.ExistingPatientNameSearch (returns suggestions based on patient names that already exist in the db). Developers can also provide a customized algorithm by implementing this interface and creating a named bean.

The system also searches for similar patients based on the information you entered so that you can review them and avoid creating duplicates. As soon as a duplicate is found you will see a bar at the top that there are similar patients found and you can click the Review patient(s) button to see them.

If you want to integrate the Address Hierarchy Module or add custom person attributes, you can find directions for Registration App Configuration.

If you want to integrate Registration with a Master Patient Index (MPI) you can find directions for /wiki/spaces/~approce/pages/16875546.

If you want to add/remove address fields or change the address field labels that appear on the form, you can go to System Administration - Advanced Administration - Manage Address Template. For more information see Administering Address Templates.

Patient search

You can use the Find Patient Record app to display recently viewed patients or find any patient in a database by name or ID.

If the search field is empty, you see a listing of recently viewed patients. As soon as you start typing and enter at least the number of characters set as the value of the Min Search Characters global property on the settings page, you will see results changing live for what you entered. Note that when searching by patient identifier you need to enter the full patient identifier because partial searches only work when searching by patient name.

Patient Summary

Once you open up a patient you see a clinical summary.

The header has basic demographic details, which you can edit by clicking the Edit button. There's also Show Contact Info, which expands a section with contact details when clicked. If a patient has an active visit you can see a green bar in the header saying when it started and also patient's current location.

Right below the header you can see boxes DIAGNOSISVITALS and VISITS. To the right you can find General Actions and Current Visit Actions if a patient has an active visit.


Currently you can see there a list of diagnoses entered as visit notes from 3 years back with the most recent at the top. You can configure the period by going to System Administration - Advanced Administration - Settings - Coreapps and enter Recent Diagnosis Period in Days.

A diagnosis that was entered as free-text is displayed in quotes. Each kind of diagnosis is displayed only once. See also Visit Notes.


The box shows the last captured vitals. See also Capture Vitals.


The box lists previous visits. It says if it was an outpatient or inpatient visit. You can click each visit to open up Visit details.  Click the pencil next to visits to see them all, and edit them.


This area lists known allergies, and the effect they have on the patient.  Click the pencil next to allergies to add/edit allergies.


On the right you can find a box with actions. General Actions are:

  • Start Visit - start a visit if there is no active visit yet
  • Add Past Visit - enter a retrospective visit
  • Merge Visits - merge past visits
  • Chart Search - search for patient chart
  • Any forms which are marked as showing up under General Action section
  • Schedule a New Appointment
  • Request Appointment

Current Visit Actions are displayed if there is an active visit and they include:

  • End visit - end a visit
  • Visit Note - enter a visit note
  • Admit to Inpatient / Exit from Inpatient - change a type of visit
  • Transfer to Ward/Service - transfer to a defined location (displayed only when in an inpatient visit)
  • Capture vitals - enter patient's vitals

Note: Some actions may not be visible based on privileges of the currently logged in user.

Note: You can now add custom forms in the actions section.  See Manage Forms to add your own action items.

Custom widgets

In Reference Application 2.6.0 we introduced a number of new customizable widgets. Please see this page for more information.

Patient Visits

It is accessible from the Visits box on Patient Summary. You can either open up a specific visit or click Show more info to display the latest visit.

You can see it has the same patient header as Patient Summary. Right below on the left you can see a list of visits with date and diagnoses captured during a particular visit. The most recent visit is displayed at the top. You can click at any visit to see its details on the right. It has Visit Actions buttons if a visit is active and a list of encounters, which you can view by clicking show details. It is possible to edit them with the pencil icon or delete with the x icon.

Only encounters that are specifically configured as "editable" can be edited. This is how it's done for the built-in reference application forms. There is currently not a way to edit your own forms.   In order to edit an encounter, you either need to have the privilege "Task: emr.patient.encounter.edit", or else have participated in the encounter.

All forms can be deleted. To delete, you need the privilege "Task: emr.patient.encounter.delete", or else to have participated.

"Participated" means that either you created the encounter, or else you are one of the providers of the encounter.

There's also Actions on the right where you can find general actions, which are the same as in Patient Summary.

Active Visits

You can see patients with active visits through the Active Visits app available from the home page.

When you click on a name you will see that patient's summary.

Capture Vitals

It is accessible from both the home page via the Capture Vitals app or directly from Current Visit Actions on both Patient Summary and Patient Visits. The app is designated for a standalone capture vitals station. It allows you to quickly find a patient, enter vitals and continue repeating this process. The action available from Current Visits Actions allows you to capture vitals for the currently displayed patient and return to the summary.

The form for capturing vitals has basic validation. It calculates BMI from Height and Weight. It supports keyboard navigation in the same way as the registration form.

Capture Allergies

It is accessible from the Patient Dashboard, by clicking the pencil beside allergies.  If there are any existing allergies, it shows them in the list.  If the patient has no known allergies, this can be specified by clicking the green "No Known Allergies" button.

When you click to "Add New Allergy", it allows you to select the allergy type; drug, food or environmental.  You can click the allergen, and then specify the reaction it causes and the severity.  You can also add a comment if you like.  After you click save, 

Visit Notes

The form for entering visit notes is accessible from Patient Summary and Patient Visits. It is listed under Current Visits Actions.

First you enter a primary diagnosis by starting to type in the Add presumed or confirmed diagnosis field. It has an auto-suggest feature which finds diagnosis concepts, but also has the Non-coded selection with the value you entered. You need to pick from the auto-suggest list to add the diagnosis, which then appears on the right under Primary Diagnosis. If you repeat these steps, your selections will appear under Secondary Diagnoses.

Diagnoses are either primary or secondary.  First diagnosis added will set as primary by default.  By unchecking primary, it will move the diagnosis under Secondary Diagnosis.  For each of the diagnosis (doesn't matter it's primary or secondary), it can be confirmed or presumed.  The default setting is presumed when the "Confirmed" checkbox is not checked.  Please don't get confused with the checkboxes of "Primary" and "Confirmed" as they are for two different questions.  Primary checkbox is for whether the diagnosis is primary or secondary diagnosis (when Primary is unchecked, it means it's secondary diagnosis).  Confirmed checkbox is for whether the diagnosis is confirmed or presumed (when Confirmed is unchecked, it means the diagnosis is presumed).

It is also possible to enter a free-text clinical note. When you are done you just need to click Save.

Admissions, Discharges and Transfers

A patient can be admitted, discharged or transferred from Patient Summary or Patient Visits under Current Visit Actions.

Locations can be configured from System Administration - Advanced Administration - Manage Locations. You need to have a location marked with the Visit location tag, which has children marked with the Admission location or Transfer location tags.

For an example look at the setup in the demo data. See Demo.

Configure Metadata

Click on the Configure Metadata app on the main apps screen.  If you want to add, edit, retire/restore or delete metadata in the new UI, this is where you go.

When you click on any of the links in blue above, you should be able to view page that lists the respective metadata, the action column on the right has these icons , click the pencil icon to edit, the 'x' icon to retire and the trash icon to delete items forever. When you retire an item, the 'x' icon gets replaced with 'restore' icon which when clicked should un retire the item. To add a new piece of metadata, click on the add button at the top of the listing page, e.g 'Add New Encounter Type' in case of encounter types.

Manage Forms

Under the Configure Metadata screen, there is now a new app to "Manage Forms".  It is possible to add custom forms to the new user interface without any custom programming!  When you initially enter Manage Forms, it shows you a list of forms that exist in the system.  Obviously, before you can configure where a custom form will appear in the system, you must create the form.  Both HTML and XForms are supported, but they must be created through the legacy user interface, under System Administration - Advanced Administration.

After you've created your custom form that you want to add to the new user interface / patient dashboard, you can click "Add" in the UI column next to the form name, as seen in the screenshot above.  Clicking "Add" opens up the configuration screen for that form.

There is a rich user interface for configuring metadata i.e add, create, retire/void, restore and delete metadata, as seen above you can also configure where and how your form will appear.  Let's discuss these settings individually.

UI Location - This is where you want the form to appear.  Is this a top level action (General Action), or a form that gets filled out as part of the current visit (Current Visit Actions)?

Display Style - Do you want the form to be rendered like a standard HTML form, or do you want the form to be rendered in simple view (like the OpenMRS 2.0 vitals form)?

Label Text or Message Code - What do you want this form to be called?  It defaults to the form name, which is probably acceptable under most circumstances.

Icon - Do you want to use a custom icon?  You can see possible icons and their names at

Privilege Required - Do you want to limit who can fill out the form?  You can specify a privilege the user's role must have to be able to see the form.  Note: the privilege name must start with "App:" or "Task:"

Order - Do you want this form to appear in a specific position in the list of forms?  This is a way to sort your forms manually.  If you want this form to be first, you must use a negative number.

Show If - Do you want to display the form only if the patient has certain characteristics?  Perhaps you would only want a maternal health form to be visible on the patient dashboard of a female patient.  You would use something like "patient.person.gender=='F' && patient.person.birthdate < '2001-01-01T00:00:00.000+0000' && patient.person.dead==false".  Or show if males with an active visit " && patient.person.gender=='M' ". Or show if the patient has a current visit and they are currently admitted, " && visit.admitted". For more information on what properties are available, see the Conditionally displaying Apps and Extensions page.

If you are replacing a built-in form, with a new custom form, you can view the configuration of the integrated forms in the source code.

Data Management (Merge Patient Electronic Records)

Under the Data Management App, you will find the ability to Merge Patient Electronic Records.

If you know both patient IDs, you can enter them in the Patient ID box. Alternatively, you can search in the lower box. Once you search, click each patient once and the Patient ID boxes will automatically be filled.

Click Continue and you will be redirected to the display page where you choose which patient to keep and which to archive. All information will be transferred to the patient you choose to keep and this action can not be undone.

Click the green button labeled Yes, Continue, the records will be merged, the other patient will be archived and you will be redirected to the patient screen.

System Administration

Under the System Administration App, you will find system administration tools.  This currently includes the Style Guide, especially useful to programmers,  It also includes Advanced Administration which returns you from the new user interface to the legacy user interface.  This is useful for configuring legacy settings and modules that don't yet have a user interface in the new UI; like Reporting and Facility Data Module for example.  You can also manage global properties and user accounts by selecting the appropriate app from the page shown in the screenshot below, you can navigate to this page by selecting  Home -> System Administration.

Manage Apps

This allows implementers to add or remove applications to/from the system without having to build a module. This is done by configuring a JSON definition.  For more information see System Administration: Manage Apps.

Viewing And Managing Accounts

In the reference applications, user and provider accounts are linked to a person record and are managed from the same page. From the home page navigate to the account listing page by clicking System Administration -> Manage Accounts as seen in the screenshot above to view all the accounts.

  •  To add a new account, from the account listing page, click on the 'Add New Account'  button, fill the form and save.
  •  To Edit an existing account, from the account listing page click the pencil icon beside the account you wish to edit.
  1. To edit the person details, under person details section click on the pencil icon on the right, make changes and save or press cancel if you don't wish to save the changes.
  2. To add a new user account, under user details section click on the last tab with the '+' sign, make changes and save or press cancel if you don't wish to save the changes. It now includes support for user capabilities.
  3. To edit an existing user account, under user details section click on the associated pencil icon on the right hand side of the tab content pane for that user account, make changes and save or press cancel if you don't wish to save the changes. 
  4. To add a new provider account, under provider details section click on the last tab with the '+' sign, make changes and save or press cancel if you don't wish to save the changes.
  5. To edit an existing provider account, under provider details section click on the associated pencil icon on the right hand side of the tab content pane for that provider account, make changes and save or press cancel if you don't wish to save the changes.

Note: Retiring and deleting user and provider accounts is not supported as of 2.3 but should be in future releases.

Viewing And Managing Settings (formerly Global Properties from 1.8 downwards)

From the home page navigate to the account listing page by clicking System Administration -> Manage Settings (formerly Global Properties from 1.8 downwards) as seen in the screenshot above to view all the Settings (formerly Global Properties from 1.8 downwards).

  • Click on the 'Add New Setting (formerly Global Property from 1.8 downwards)' button to add a new Setting (formerly Global Property from 1.8 downwards).
  • The action column on the right has these icons , click the pencil icon to edit and the trash icon to delete a setting (formerly global property from platform 1.8 downwards).

Note: Some Setting (formerly Global Property from 1.8 downwards) values are truncated to fit in the allocated space, clicking the pencil icon should take you to the edit screen from where you can see the entire value. On the listing page, hovering over the name cell should display the description also.

New Features

  • Built-In Reports

    What this module does

    Built-in reports OWA provides basic reporting and give some insight into your data in Reference Application distribution. Data can be seen visually how they have spread and it gives an overview about the present data.

    Currently there are some basic reports available. If anyone wants to add more sophisticated reports, it's really easy and there are some common components that can be reused from the OWA when it  comes to displaying the data.

    Documentation / How-To

    You need to have the Reference Metadata module 2.7.0 or higher installed in your OpenMRS server. This module includes the report definitions which the built-in reports OWA is being displaying. 

    Currently there are 10 basic reports have configured. 

    • Number or Visits
    • Number of Patient Registrations
    • Number of Admissions per service area
    • Number of Transfers per service area
    • Number of Discharges per service area
    • Number of Visit Notes
    • List of Diagnosis’s made and quantity
    • List of Providers (grouped by active/retired)
    • List of Users (grouped by active/retired)
    • List of new Patient Registrations

    You can see those reports under Administration -> Manage Report Definitions -> Report Administration once you install the Reference Metadata module 2.7.0 or higher.

    After ensuring that the reports are properly configured with the Reference Metadata module installation, you can upload the  openmrs-owa-built-in-reports to your OpenMRS server.

    Then you can open up the owa from Administration -> Open Web Apps Module -> Manage Apps  -> Built In Reports. 



    List of Users in the OpenMRS system has visualized as follows:

    List of Diagnosis in the entire system is available as below:

    When there is no data in OpenMRS for any of the reports, it will be indicated to the user like below:


    More MetaData Management in Admin UI

    OpenMRS Legacy Module contains a lot of administrative functionalities which are needed to manage the reference application. Most of this administrative functionalities contain a legacy model and less experience to the users. So OpenMRS Community wanted to migrate those administrative features to the Modern Open web app view.

    More Metadata Management in AdminUI project is one of those projects which are designed to migrate some of these administrative functionalities to the modern open web app view. In the More Meta data Management in AdminUI project, We focused on this following functionalities,
    1. Manage Modules - This feature will be used to manage the modules in the OpenMRS reference application.
    2. System Information - This feature will be used to display the System information about the OpenMRS server and the system.
    3. Manage Scheduler - This feature will be used to manage the tasks in the OpenMRS reference application.

    These features are implemented as Open Web Apps with the modern view to the users.


    Those features are implemented as an Open Web App and included into the SysAdmin Open Wep App. 

    Used technologies for the developments, 

    • Front End Development : HTML, CSS, Angular JS, jQuery
    • Back End Development: Java, REST API

    Manage Modules

    This feature will be used to manage the modules in the OpenMRS reference application. Users can use this implementation for this following functionalities,

    Features of the Manage Modules



    New/ Existing/ Modified Feature

    1. List all the installed Module

    New Icons used to indicate the module status

    Modified Feature

    2. Start the module

    No Modifications

    Existing Feature

    3. Stop the module

    Confirmation Pop up will be shown with the dependent modules details to alert the user

    Modified Feature

    4. Delete/Unload the module

    Confirmation Pop up will be shown with the dependent modules details to alert the user

    Modified Feature

    5. Check updates

    Module updates will be checked with OpenMRS AddOns and listed in the new page for
    the user selection.

    Modified Feature

    6. Check one module update

    Check the update with OpenMRS AddOns and indicate the update status

    New Feature

    7. Start All Modules

    No Modifications

    Existing Feature

    8. Add/Upgrade Modules

    Implemented Drag and Drop feature

    Modified Feature

    9. Search Modules

    Connected with OpenMRS Addons and user can search the module independently

    Modified Feature

    10. Search Module Information

    User can view the detailed information about the searched module

    New Feature

    11. Module Information View

    Used to display the module information with required modules, aware of modules,
    and depend on module details

    New Feature

    12. View not installed module information

    Connected with OpenMRS add-ons and indicate the user about the installation features.

    New Feature

    System Information

    This feature will be used to display the System information about the OpenMRS server and the system. Users can use this feature to get this following information,

    1. OpenMRS Information

    2. Operating System Information

    3. Java Runtime Information

    4. User Information

    5. Memory Information

    6. Database Information

    7. Module Information

    New Features

    1. Divided the existing System Information under different set of categories to increase the usability

    2. Used some new kind of Icons to illustrate the Information Category properly

    3. Modified Module Information Section with some new ideas.

    Manage Scheduler

    This feature will be used to manage the tasks in the OpenMRS reference application. Users can use this implementation for this following functionalities,

    Features of the Manage Modules



    New/Existing/Modified Feature

    1.List all the installed Module

    New Icons and UI used to indicate the module status

    Modified Feature

    2. Schedule Task

     No Modifications

    Existing Feature

    3. Shutdown Task

    Confirmation Pop up will be shown to alert the user

    Modified Feature

    4. Reschedule Task

    It will reschedule the existing task in the system

    New Feature

    5. Delete Task

    Confirmation Pop up will be shown to alert the user

    Modified Feature

    6. Reschedule All Tasks

    It will reschedule all the tasks in the system

    New Feature

    7. Shutdown All Tasks

    It will shut down all the tasks in the system

    New Feature

    8. Startup Tasks

    It will reschedule all the tasks in the system

    New Feature

    9. Refresh Tasks

    It will refresh the list of registered tasks

    Existing Feature

    10. Add New Task Definition

    Used to create new Task Definition

    Implemented new UI for this functionality

    Modified Feature

    11. Edit Task Definition

    Used to edit existing Task Definition

    Implemented new UI for this functionality

    Modified Feature

      More Info here  wiki  and this blog

  • OWA  included in RA - System Administration, Add-on Manager and Cohort Builder

    See this RA-1427
  • Biometrics Support in Registration App

    See These Tickets  ( RA-1406 ,RA-1407 ,RA-1391 ,RA-1395 ,RA-1397 )
  • Sticky Note on the Patient Dashboard

    See RA-1287  
  • Ability to edit implementation forms  

    See Ticket and try it out at  qa-refapp
  • Pre-built Reporting Tools

    See RA-1257  and  RA-1258

OpenMRS Atlas

New to the OpenMRS 2.1 user interface is the OpenMRS Atlas  configuration.  When the implementation is first established, you must link ownership with an OpenMRS ID.  Click “Sign in with your OpenMRS ID” and provide your OpenMRS ID and password.  If your browser is already logged in to OpenMRS ID, it will use that account automatically when you click "Sign in". 

The main map view is then displayed.


Select your existing site, or click the user menu with your name that appears. Choose “Add New Site”.

You can then drag your marker to the physical location of your site.  Double-clicking on the site will allow you to view the details.  Clicking the pencil icon will allow you to edit the details.

You can then choose to turn on Automatic Updates.  This will allow the world to see the progress your uses are making with data entry; specifically the number of patients, encounters and observations you have entered into your system. Rest assured, no patient identifiable information is shared.

Invite your friends to visit to see everywhere that OpenMRS is in use around the world!

You can manage the Atlas after initial configuration under System Administration - OpenMRS Atlas.

Other Releases