Wiki Spaces


Get Help from Others

Q&A: Ask OpenMRS
Discussion: OpenMRS Talk
Real-Time: IRC Chat | Slack


Page tree

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents


OpenMRS 2.1 is the latest 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 2.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

Try It Out!

Hosted Demo Server 

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


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.


If you want to install the latest released version of the Reference Application yourself, you can download it as a standalone, which is a complete package with an embedded Tomcat and MySQL database. When you first start a standalone, you can pick one of 2 install options.


If you are already running OpenMRS 2.0 Standalone you can follow the Step-by-step guide to upgrade Standalone OpenMRS 2.0 to OpenMRS 2.1.

Legacy OpenMRS vs. Reference Application

The Reference Application is built on top of the OpenMRS 1.10.0 Platform. You can still download and use the legacy application. See the download page. We will continue to provide support and release new versions of the legacy OpenMRS.

The Reference Application is a set of modules that are installed on the legacy OpenMRS. 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 - Advanced Administration - Manage Users - Add User to add a new user. Remember to assign them appropriate privileges. Next go to System Administration - Advanced Administration - Manage Providers - Add Provider and add a new provider for the previously created person.


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 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.


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 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. 


If you want to change or add more fields to the form, you can go to System Administration - Advanced Administration - Settings - Layout and edit Address Template.

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.


Right below the header you can see boxes DIAGNOSIS, VITALS 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:


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

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.


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.


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.


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

Configure Metadata

There is now a new App called Configure Metadata on the main apps screen.  If you want to configure a custom form to appear in the new UI, this is where you go.

Manage Forms

Under the Configure Metadata screen, there is now a new app to "Manage Forms".  This is a new feature in OpenMRS 2.1.  It is now 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.


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' ".

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 also manage concepts and forms through this link.  

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". 


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


New functionality can be added by creating apps which requires coding skills. It also means that you can only add new forms by creating apps. The provided apps are configurable to the extent mentioned in the features chapter.