Wiki Spaces


Get Help from Others

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


Page tree
Skip to end of metadata
Go to start of metadata

OpenMRS has a collection of administration pages used to manage system settings, administer data, manage modules, etc (System Administration > Advanced Administration in the Reference Application). Remarkably, these OpenMRS administration pages haven’t changed in over 15 years. On October 5, 2005, Ben Wolfe committed administration pages using Java Server Pages (JSP) that are still in 2021 being used in nearly every instance or distribution of OpenMRS, in most cases through the Legacy UI module that allows the original administration pages to run within OpenMRS 2.x.

They've gotten the job done for over 15 years, why change now?

The OpenMRS community needs to move away from server-side rendering of web pages (like JSPs) and toward contemporary development of client-side applications leveraging data via web services (FHIR whenever possible; otherwise our bespoke REST API). Now, with the work of the Micro Frontend Squad, we have a framework in which to build contemporary administration functions.

This is the perfect time to rebuild our administration functions:

  • We have a new frontend framework with clear conventions to follow (React, ESM, Carbon Design System).
  • As OpenMRS embraces micro frontends, we need administration pages from this decade.
  • New micro frontend-based administration functions would allow many OpenMRS implementations and distributions to migrate away from the legacy UI framework.
  • Most importantly, a micro frontend-based module for administration functions that's more attractive than the Legacy UI (a low bar) would allow any OpenMRS implementation to switch to it and, in so doing, take an easy step into the future of frontends for OpenMRS.

What will it take?

  • An Admin Framework. The administration page provides a suite of built-in administration functions along with the capability for modules to add to the list. We'll need a basic framework (i.e., an main admin screen along with conventions for how administration features are navigated and behave, so there's some consistency for users). The micro frontend framework already supports extension points similar to our legacy UI, so the ingredients exist.
  • Components or ESMs for built-in administration functions. Before anyone will consider switching from the legacy administration functions to a new option, we must have parity (at least support the existing functionality). This means each of the 15 sections of our legacy administration page will need a counterpart in the new administration functions.
  • Not just frontend development. While several administration functions have RESTful endpoints for their features, there are plenty of administration functions that do not. So, we will need to build REST endpoints to support the necessary features (using FHIR whenever possible and extending our REST web services module when necessary).
  • An admin 3.0 module. We'll want to bundle these new admin functions (presumably one or more ESMs) into an Admin 3.0 module that implementations can be installed to serve up the new administration functions in place of the current legacy administration page.

Additional Thoughts

  • Some aspects will be heavier lift
    • Encounter management includes editing any type of observation, which is basically like writing a generic encounter form UI.
    • Concept management is non-trivial.
  • We'll need coordination to ensure consistent approaches (e.g., listing/paging, searching, person search, etc.).
  • For each administration section "sub-project", we will want to consider:
    • Adopting a "FHIR first" approach. Wherever we can use or migrate to FHIR resources, we should, since our goal is to eventually only use our bespoke API for those resources that are not covered by the FHIR specification.
    • Adopt the Carbon Design, Localization, and general conventions provided by frontend development led by the Micro Frontend Squad.
    • Several administration functions will first need to be exposed within REST API calls (in FHIR if possible/appropriate; otherwise, in the OpenMRS REST API) before a UI can be built to leverage them.

Built-In Administration Functions


These functions provide the fundamental tools to manage users within OpenMRS. See System Administration > Manage Accounts in the Reference Application.

Manage Users

List and search users, add/edit user form

  • OpenMRS User extends Person, which means creating a user can create a new Person or link to an existing Person
  • In OpenMRS, people provide care for patients through a Provider account (also linked to Person). Many (but not all) users are also providers, so Provider creation is incorporated into user management.
  • New users are auto-assigned a system ID, but may create their own username (must be unique, discourage use of email address)
  • Configurable password requirements must be followed
  • Many of these functions should already be available via the REST API

Extra credit

  • Migrating provider and person management to FHIR (Practitioner and Person)
  • Incorporate (optional) user email address
Manage Roles

List, search, add, edit, and delete roles. Prevent system roles from being edited/deleted.

Extra credit:

  • Improving role management experience
Manage PrivilegesList, search, add, edit, and delete privileges. Prevent system privileges from being edit/deleted.
Manage AlertsCreate system-wide messages.


These functions provide administrative functions for patient records within OpenMRS. Ideally, wherever possible, these functions would be performed via FHIR API calls.

Manage Patients

List and search patients, add/edit patient form.

  • All patients should have one preferred identifier and may have other identifiers
  • Patients can have multiple names and addresses
  • Collect (optional) cause of death when marking a patient as deceased

Extra credit:

  • Make it easier to record patient contact information (e.g., telephone number, email) using implementation-configured person attributes
Find Patients to Merge

Search and list potential patients to merge.

  • Most likely, will require adding new REST API endpoints accessible with appropriate privilege(s).
  • First pass could use existing process/UI for merging patients and focus on new UI for selecting patients for merge.

Extra credit:

  • Update UI for merge process
Manage Identifier Types

List/search and add/edit form for patient identifier types. Ability to retire or purge a patient identifier type.

  • Purging a patient identifier type should not be possible once it has been used (database foreign key constraints will prevent deletion)

Extra credit:

  • Provide some support for users in crafting a regular expression format
Manage Patient Identifier Sources

List/search, add, and configure patient identifier sources. 

  • REST API endpoints will need to be created to manage patient identifier sources
Auto-Generation Options

Manage auto-generation features for identifier types.

  • REST API endpoints will need to be created to manage auto-generation options
View Log Entries

Search patient identifier generation logs.

  • REST API endpoints will need to be created to access patient identifier log entries


These functions provide administration for Person entries and associated metadata within OpenMRS. In OpenMRS, a Person is used to store demographic and other person-specific information for Patients, Users, Providers, and people related to patients (children, relatives, caretakers, etc.)

Manage PersonsList/search, add/edit Person form, and delete persons.
Manage Relationship Types

List/search, add, edit, retire, and delete Relationship Types. Relationship Types define the types of relationships between Persons. Also manage how relationship types are show to the user (which types are shown by default and in which order).

  • REST API endpoints will need to be created to manage relationship types.
  • Relationships have two directions. Some relationships differ depending on the direction; for example, is A is related to B as "Parent", then B is, by definition, related to A as "Child". Other relationships are the same either direction (e.g., the reverse relationship of "Sibling" is also "Sibling").
Manage Person Attribute Types

List/search, add, edit, retire, and delete Person Attributes. These are local (implementation-specific) extensions of a Person. Also control how person attributes are displayed to users.

  • Some REST API endpoints already exist for managing person attribute types
  • REST API endpoints may need to be created for managing how person attribute types should be displayed to users


Provides functions for managing visits resources within OpenMRS as well as configuring how visits are used. A visit can contain 0-to-n encounters.

Manage Visit TypesList/search, add, edit, retire, and delete visit types.
Manage Visit Attribute TypesList/search, add, edit, retire, and delete visit attribute types.
Configure Visits

Control visit behavior within the system (e.g., auto-closing of visits and how encounters are assigned to a visit).

  • REST API endpoints will need to be created to configure visit behavior.


Provides functions for managing clinical encounters within OpenMRS.

Manage EncountersAllows the creation and editing of clinical encounters. These are relatively complex resources comprising encounter details (patient, location, date, type, associated visit), provider(s) involved in the encounter, and any observations collected within the encounter. There are several types of observations, so making an interface to view and/or edit any observations is non-trivial.
Manage Encounter Types

List/search, add, edit, retire, and delete encounter types.

  • REST API endpoints exist
Manage Encounter Roles

List/search, add, edit, retire, and delete encounter roles.

  • REST API endpoints exist


Provides functions for managing Provider accounts within OpenMRS. Provider accounts are used to record who provided clinical care (e.g., within encounters). While provider accounts often refer to users within the system (people who are logging into OpenMRS like doctors & nurses), they can refer to people who are not users of the system (have no User account) and even to providers from other institutions (in which case they may not refer to a Person). There is also a Provider Management module that implements some of these features.

Manage Providers

List/search, add, edit, retire, and delete provider accounts. Providers may optionally be linked to a Person.

  • REST API endpoints exist
Manage Provider Attribute Types

List/search, add, edit, retire, and delete provider attribute types.

  • REST API endpoints exist


Provides functions to manage location metadata within OpenMRS.

Manage Locations

List/search, add, edit, retire, and delete locations. This includes tagging locations and the ability to create a hierarchy (parent/child relationships between locations).

  • REST API endpoints exist
Manage Location Tags

List/search, add, edit, retire, and delete location tags.

  • REST API endpoints exist
View Location Hierarchy

Configure how locations are displayed in the application (e.g., as Tree or Selector).

  • This feature may not be needed or may need to be implemented differently in the new frontend.
Manage Location Attribute TypesList/search, add, edit, retire, and delete location attribute types.
Manage Address TemplateXML editor textarea


Provides features for system administration of clinical observations collected within OpenMRS.

Manage Observations

Find observations by person & concept OR by encounter, then redirects to Encounter management for editing.

  • We might be able to provide these features under Encounter management.


Provides the functions to manage scheduled (background) processes within OpenMRS. Implemented in System Administration > Manage Scheduler as well as within the Advanced Administration pages.

Manage SchedulerList/search, add, edit, start, stop, run, and delete scheduled tasks.


Provides functions to manage programs within OpenMRS. Programs represent treatments programs or studies. A program can have associated workflows and each workflow can have states. Patients placed in a program can be assigned any state within a workflow in that program. This allows, for example, to identify all patients in the "HIV Program" in the "On active treatment" state. Programs, workflows, and states are all concepts.

Need to confirm the extent to which these functions are actively used and which features are (still) important for implementations

Manage Program

List/search, add/edit program form, and ability to retire programs. Programs can have one or more workflows and each workflow can have states a list of valid states within that workflow. 

  • REST API endpoints will need to be created to manage programs, workflows, and states
Manage Triggered State Conversions

Define concepts (presumably an observation) that should automatically trigger conversion of a patient from one state to another within a workflow.

  • Need to confirm if this is being used in production by implementations
  • REST API endpoints would need to be created to manage triggered state conversions


View Concept Dictionary

Manage Concept Drugs
Manage Proposed Concepts
Manage Concept Classes
Manage Concept Datatypes

Manage Concept Sources

Manage Concept Stop Word

Manage Reference Terms
Manage Concept Attribute Types


Manage Forms
Manage Fields
Manage Field Types
Merge Duplicate Fields

HL7 Messages

Manage HL7 Sources
Manage Queued Messages
Manage Held Messages
Manage HL7 Errors
Manage HL7 Archives
Migrate HL7 Archives


Provides some key miscellaneous administration functions for OpenMRS, including access to fundamental configuration settings.

Set Implementation Id

System Information
View Quick Reports
Advanced Settings
View Server Log
View Database Changes
Manage Locales and Themes
View Logged In Users
Search Index


Provides functions to install, start & stop, configure, and remove OpenMRS modules. Implemented in System Administration > Manage Modules as well as within the Advanced Administration pages. These features should respect the runtime setting module.allow_upload=false to disable module management from the web interface.

Manage ModulesList/search, install, start, stop, and remove modules.
Module PropertiesConfiguration settings for modules.


Modules can add their own administration section. The Legacy UI module renders each as a new section (header and links) in the third column. Admin 3.0 should render these as additional sections as well with links the same as provided by the Legacy UI module for backwards compatibility.

There are some popular modules that we would want to make sure are supported such as:

  • REST Web Services
  • HTML Form Entry
  • ID Generation
  • Reports
  • Address Hierarchy
  • Atlas Module