GSOC 2021: Modernizing Administration functions for OpenMRS

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

Users

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 Privileges	List, search, add, edit, and delete privileges. Prevent system privileges from being edit/deleted.
Manage Alerts	Create system-wide messages.

Patients

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

Person

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

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

Visits

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.

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.

Encounters

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.

REST API endpoints exist

Manage Encounter Roles

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

REST API endpoints exist

Providers

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

Locations

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 Types	List/search, add, edit, retire, and delete location attribute types.
Manage Address Template	XML editor textarea

Observations

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.

Scheduler

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.

Programs

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

Concepts

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

Forms

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

Maintenance

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

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

Modules

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.

Extensibility

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

Resources

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

Wiki Spaces

Get Help from Others

Projects

Page tree