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.
- 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.
List and search users, add/edit user form
List, search, add, edit, and delete roles. Prevent system roles from being edited/deleted.
|Manage Privileges||List, search, add, edit, and delete privileges. Prevent system privileges from being edit/deleted.|
|Manage Alerts||Create 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.
List and search patients, add/edit patient form.
|Find Patients to Merge|
Search and list potential patients to merge.
|Manage Identifier Types|
List/search and add/edit form for patient identifier types. Ability to retire or purge a patient identifier type.
|Manage Patient Identifier Sources|
List/search, add, and configure patient identifier sources.
Manage auto-generation features for identifier types.
|View Log Entries|
Search patient identifier generation logs.
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 Persons||List/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).
|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.
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 Types||List/search, add, edit, retire, and delete visit types.|
|Manage Visit Attribute Types||List/search, add, edit, retire, and delete visit attribute types.|
Control visit behavior within the system (e.g., auto-closing of visits and how encounters are assigned to a visit).
Provides functions for managing clinical encounters within OpenMRS.
|Manage Encounters||Allows 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.
|Manage Encounter Roles|
List/search, add, edit, retire, and delete encounter roles.
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.
List/search, add, edit, retire, and delete provider accounts. Providers may optionally be linked to a Person.
|Manage Provider Attribute Types|
List/search, add, edit, retire, and delete provider attribute types.
Provides functions to manage location metadata within OpenMRS.
List/search, add, edit, retire, and delete locations. This includes tagging locations and the ability to create a hierarchy (parent/child relationships between locations).
|Manage Location Tags|
List/search, add, edit, retire, and delete location tags.
|View Location Hierarchy|
Configure how locations are displayed in the application (e.g., as Tree or Selector).
|Manage Location Attribute Types||List/search, add, edit, retire, and delete location attribute types.|
|Manage Address Template||XML editor textarea|
Provides features for system administration of clinical observations collected within OpenMRS.
Find observations by person & concept OR by encounter, then redirects to Encounter management for editing.
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 Scheduler||List/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
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.
|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.
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 Field Types|
|Merge Duplicate Fields|
|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
|View Quick Reports|
|View Server Log|
|View Database Changes|
|Manage Locales and Themes|
|View Logged In Users|
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 Modules||List/search, install, start, stop, and remove modules.|
|Module Properties||Configuration 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
- Address Hierarchy
- Atlas Module
- Admin page on demo server (username: admin, password: Admin123)
- OpenMRS REST API documentation at rest.openmrs.org
- FHIR R4 API and the OpenMRS FHIR module