GSOC 2021: Modernizing Administration functions for OpenMRS

tl;dr – OpenMRS is moving from legacy server-rendered pages to React using Carbon Design within a micro frontend framework. To help implementers make this transition, we need to port our administration functions from the legacy approach to the new framework. This requires a combination of frontend and backend work that we've divided up into several GSoC projects.

OpenMRS is used in over 40 countries, including several large scale national deployments, supporting the care of people with HIV, tuberculosis, malaria, and cancer as well as helping maternal child health programs. Over the past 15 years, organizations and countries have adopted OpenMRS to meet local needs. In some cases, this has resulted in different distributions (“flavors”) of OpenMRS, including Bahmni, KenyaEMR, UgandaEMR, NigeriaMRS, etc. As frontend technologies have evolved quickly over the past 5 years, many sites have started making their own frontends for the platform. It’s exciting to see how many developing countries can adapt OpenMRS to meet local needs; however, these developments have made it harder for different sites & different countries to share functionality across implementations. The OpenMRS community has embraced micro frontend architecture to help bring these diverse efforts into a unified frontend framework. In the meantime, all of these various flavors of OpenMRS still share two features: (1) they all use the same OpenMRS platform/backend and (2) they all still rely on the original administration screens (built in 2005 by Ben Wolfe, the first programmer for OpenMRS) to manage their settings, user access, and other metadata. As it turns out, one of the most widely used OpenMRS modules worldwide is our Legacy UI module – created during GSoC 2015 – that allowed the legacy administration functions to run in OpenMRS 2.x.

You could make a valuable contribution to OpenMRS by helping us port these legacy administration functions into our new micro frontend framework.

Since there are dozens of administration functions and a good chunk of these functions do net yet expose REST endpoints for a React app to use, so this larger goal has been divided into several GSoC projects.

• Admin Dashboard. Creating the admin dashboard with extension point to allow other admin frontend modules to add admin pages. Also will need to create a REST API to expose the list of admin links for installed modules and the frontend code needed to automatically add these links to the admin dashboard. Bundle the dashboard into an Admin 3.0 module that can eventually replace our Legacy UI module (i.e., legacy administration pages).
   
• People Management. This project will focus on porting User/Person/Patient/Providers administration functions to the Micro Frontend framework.
   
• Clinical Data Management. This project will focus on porting Visits/Encounter/Observations administration functions to the Micro Frontend framework.
   
• Metadata Management. This project will focus on porting Locations/Programs/Scheduler/Maintenance functions to the Micro Frontend framework.
   
• System Management. This project will focus on porting OpenMRS system management functions (global properties, scheduler, module management) to the Micro Frontend framework.
   
• The REST of Administration. Focused on backend (Java) to implement missing endpoints for REST/FHIR APIs needed to be able to implement admin features through client-side app.

As part of the micro frontend framework, projects that build frontend assets will need to follow the conventions of this framework (e.g., React with TypeScript and using Carbon Design).

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

Questions & Answers

Do these projects depend on each other?

While these projects will all work together toward the goal of porting our administration functions to our new frontend framework, the modular architecture of micro frontends makes it easier to break the work into pieces and allows them to have minimal direct dependencies. The most significant dependency between these projects will be ensuring REST endpoints are created for administration functions that do not yet have them. While each project could create their own REST endpoints, we have created one project to focus specifically on building these endpoints so the other projects can spend more time on frontend functionality.

What if the other projects are not filled or are unsuccessful?

By its design, the micro frontend framework provides a modular approach to frontend development. Even if some parts of this project were unfulfilled (e.g., if a student had to withdraw due to illness or other unforeseen circumstance), the remaining projects can still stand on their own. We also have a wonderful community of developers around the world (with whom you will soon be interacting if you haven't already), who can help in a pinch. When you're writing code to save lives, we're all in this together!

What's this Micro Frontend framework all about?

Micro frontends leverages the ECMAScript module specification to package and deploy frontend code in a way that allows a frontend application to be built in parts. In fact, some parts can be written in React and other parts in Angular or Vue. In a large project like OpenMRS, where contributors are working around the world, a framework like this makes it easier for work from multiple organizations to be woven together into a single application. It also allows implementations to customize the application to suit their local needs, since there isn't one solution that can meet everyone's needs.

If the admin pages have 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 about Concepts, Forms, and other administration functions not mentioned above?

Given that Google Summer of Code is shorter than prior years, we do not anticipate being able to port all administration functions with this effort. Some functions that are not included are:

• Concept management. The OpenMRS community is working alongside Open Concept Lab (OCL) to provide concept management features within OCL. While we will likely want to implement concept management features within OpenMRS, we will defer them for Google Summer of Code 2021.
• Forms. Since the micro frontend squad is working on incorporating form editing tools within the framework (e.g., support for HTML Form Entry and possibly AMPATH's form builder), we will defer porting form management functions for now.
• HL7 Messages. As OpenMRS is migrating toward FHIR, the administration functions for managing & monitoring HL7 v2 message queues will be deferred for now.

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