Questions about migrating from 2.x to 3.0

People are asking for help in how to approach migration from OpenMRS 2.x (or their bespoke distribution based on an OpenMRS 2.x world) to 3.x. Here are some imperfect responses for some of the questions I’ve heard. Hopefully people will find them useful or others in the community can improve on my responses.


-Burke :burke:

/cc @grace @jdick @bistenes @ibacher @dkayiwa @raff @mksd @jennifer @mayanja @wanyee

We’re trying to adopt a front-end development process and migrate toward OpenMRS 3. Where do we start?

Review docs referenced from, including the OpenMRS 3 dev guide.

The documentation says one can start from from openmrs-esm-template-app but still, it’s unclear how to make changes to this repo and integrate it with the OpenMRS 3.0 interface. Is it possible to build a custom module using the template tell openmrs-esm-core to focus on it instead of the default OpenMRS module (one with the same functionality)?

A primary goal of OpenMRS 3 is to provide a frontend framework that can be shared across distributions & implementations to try to address problems with the current state of affairs – i.e., when every country/organization/distribution is building their own custom frontend, then it is nearly impossible to share functionality across sites. To this end, everyone adopting OpenMRS 3 is strongly encouraged to adopt core features (e.g., login, basic navigation, patient chart review, ordering) provided out of the box with OpenMRS 3 and add custom features through modules leveraging extension points in the framework.

The OpenMRS 3 frontend is built using an import map and extension points within the framework are used to make it aware of custom modules which can add or replace functionality within the framework. For more technical details that are unclear from existing documentation, I would suggest reaching out to other OpenMRS 3 developers. The framework is very much in development using a design-first approach as it is just starting to get deployed into live environments. The closer developers can track and be involved with the community development process, the further we can all go and the more countries and organizations can ensure their use cases are being covered by core features and reduce the amount of functionality they have to maintain by themselves. Questions on frontend development can be directed to the #openmrs3-helpme channel on Slack (OpenMRS Slack can be joined using

What’s the best way to integrate existing 2.x custom modules with the 3.0 UI?

There are a few options for migrating modules that use 2.x or custom server-rendered frontends, since the OpenMRS 3 frontend framework can run alongside 2.x.

  • Refactor the modules to expose their data through REST and write ESM(s) following OpenMRS 3 conventions to replicate or improve on the legacy frontend. This is the ideal approach, but will take the most work, so may not be the best short-term option in all cases.
  • Send the users to the 2.x or custom frontend for those features ± tweak the legacy module to provide a link to get users back to the 3.x frontend. For features that are fairly isolated, this can be a very viable workaround. It’s not as pretty user experience, but can help maintain functionality while a frontend is being transitioned from 2.x to 3.x. In fact, PIH has flipped this a bit and provided a link within their 2.x to see the same patient’s chart in the new 3.x frontend (i.e., users can continue to use the legacy UI and use the 3.0 version of the chart as features become available & more desirable).
  • Embed existing 2.x functionality inside an OpenMRS 3 frontend through an iframe. This may require tweaking the existing module to support a view that’s easier to embed or better matches the 3.0 UX. It’s less than ideal, but, for modules that are primarily rendering data for review, can provide a quick solution while a more long term solution is being developed.

We’ve got a system deployed to many sites and are managing our concepts and metadata within a central OpenMRS system, distributing it through SQL dumps. What would be the best strategy for distributing metadata going forward?

For concepts management, we are working on ensuring that OpenConceptLab (OCL) can adequately meet the needs for managing concepts across distributed systems. CIEL is being published within OCL and organizations like PIH and distributions like KenyaEMR are spearheading the work to get OpenMRS dictionary management features realized within OCL Online. Dictionary exports from OCL can be included as metadata for the initializer (iniz) module for distribution.

For the distribution of concepts and other metadata, we strongly recommend moving toward using the initializer (iniz) module. Centrally managed metadata can be placed into simple CSV files and included in distributions. Concepts can be managed in CSV files as a workaround for now while OCL capabilities are being realized.

We have several modules, some are community modules and others are custom modules. What would be the best way to bundle all of these packages/modules into a single distribution that can be versioned & deployed as a package?

We are actively working out the conventions for packaging and distribution of systems that include some combination of the OpenMRS platform, Reference Application (2.x and/or 3.x), backend modules (whether custom or community), frontend modules, and metadata. The 3.x branch of openmrs-distro-referenceapplication is being adapted as we develop these conventions. The OpenMRS SDK will be adapted as well to help make it easier to automate packaging, building, and deployment. In this process, we expect to be moving away from hot-loading of modules and toward a build & deploy approach, since hot-deployment of features is a risky venture for production systems and a build & deploy approach can not only mitigate that risk, but also vastly improve the development process.