OpenMRS 3 (O3) vs OpenMRS 2.x

What differs between O3 and 2.x across the stack

This table compares the two OpenMRS generations layer by layer, from the user interface to authentication. Where the supplied facts cover a difference, the cell says so; where they do not, the cell tells you what to confirm in the OpenMRS community or your own test environment before committing to a plan.

Licensing, support and update terms for each version

Both OpenMRS 3 (O3) and the 2.x platform sit under the same MPL 2.0 license and the same nonprofit and community model, so licensing does not separate them. What differs is the support you buy, from implementers and internal staff, and the update path each version requires. The cards below cover what is documented and what you need to confirm before committing.

How the O3 frontend sits on top of the OpenMRS backend

Which OpenMRS deployment package fits which situation

What form migration to the O3 schema involves for legacy HTML forms

What an O3 move costs in staff time, testing and support

This table breaks down the cost components of three paths: staying on OpenMRS 2.x, moving to O3, or running both during transition. Software licensing is zero under MPL 2.0, so the differences come from people, testing and support, and the table shows who is paid for each item and what drives it up. Use it to build a quote request, since the main takeaway is that effort scales with your form inventory, modules, integrations and sites.

How an existing 2.x implementation should plan the move to O3

The sequence turns an existing 2.x deployment into a tested O3 plan, with a documented inventory, a non-production proof, validated clinical workflows and a rollback path that stays open until the move is confirmed. Each step produces evidence the team can review before the next one starts.

1. Inventory modules, forms, integrations and custom code

   Start by listing everything the 2.x instance depends on: installed modules and their versions, legacy HTML forms, concept dictionaries, reports, scheduled tasks, interfaces to laboratory, billing or imaging systems, and any custom Java or database changes. The implementation lead and the clinical informatics owner should own this list together, because clinical forms are usually the largest source of hidden work. The step is done when every item has an owner and a disposition: keep, migrate, replace with an O3 or standard capability, or retire. Ask the implementer which of these items they can verify against your own system rather than from documentation alone.

2. Check O3 compatibility for each dependency

   For each module and integration on the inventory, confirm whether an O3 equivalent exists, whether the 2.x module is still maintained, and whether the O3 frontend relies on backend APIs that your custom modules do not expose. Review the O3 reference application and the current OpenMRS Platform release notes against your list, and check the FHIR2, SMART-on-FHIR and OAuth2 Login modules if your identity or interoperability design depends on them. The output is a compatibility register that names which items are ready, which need development, and which need a decision from the governance group. Confirm each conclusion with the implementer or the OpenMRS community, since module status changes over time.

3. Stand up a non-production O3 environment

   Build a separate O3 environment that is isolated from production and loaded with de-identified or synthetic data. The OpenMRS download page lists the O3 Reference Application container stack, which runs MariaDB, the OpenMRS backend, an Nginx frontend and an Nginx gateway, with an optional Certbot service for SSL. Use it as a starting point, or pair a matching backend with your own database and hosting standards, and record every deviation from the reference setup. The environment is ready when a clinician test user can log in, open a patient record and complete a basic encounter, and the team can rebuild it from configuration files alone.

4. Migrate and test forms against clinical workflows

   Convert legacy HTML forms to the O3 form schema, using the migration tool that Palladium Kenya built and the community adopted, or by rebuilding forms manually where the tool does not cover a form's structure. Then test each form against real clinical workflows such as intake, triage, consultation, admission and discharge, with clinicians who use them daily. Log each defect, confirm the fix, and retest the full workflow rather than the single form. The step closes when the clinical sign-off sheet lists every workflow, the tester, the date and any accepted differences from 2.x behavior. Expect this to be the step where the timeline is most uncertain, so confirm the scope and effort with the implementer in writing before committing.

5. Validate data, integrations and reporting

   Run a full data migration rehearsal into the O3 test environment and compare record counts, concept mappings, patient identifiers and reports between the 2.x source and the O3 target. Test every interface, including laboratory, billing and imaging connections, and confirm that scheduled jobs and access roles behave as documented. Keep a reconciliation log that records each difference and its resolution. The step is complete when two consecutive rehearsals produce matching reconciliation results and the data owner signs off on the mapping. Ask the implementer how they handle identifier conflicts and free-text fields, since those usually need case-by-case decisions.

6. Plan user training and cutover

   Prepare role-based training for clinicians, registration staff, pharmacy and administrators, using the O3 test environment and the forms that were validated in the earlier steps. Agree a cutover window with clinical leadership, set a freeze on changes to the 2.x instance during the final migration, and publish a go or no-go checklist that names the person who makes the decision. The step is done when every user group has completed training, the support rota is staffed for the first days after cutover, and the checklist has been rehearsed at least once. Confirm the cutover plan with your implementer and with the OpenMRS community resources before the window is fixed.

7. Execute cutover and keep the 2.x rollback path

   On the agreed date, freeze the 2.x instance, take a verified backup of its database and configuration, run the final migration, and reconcile the results against the rehearsal log before opening O3 to users. Keep the 2.x instance and its backup intact for a period the governance group defines in advance, so the team can return to 2.x if a critical defect appears. The step closes when the reconciliation is signed off, users confirm access to live workflows, and the rollback procedure has been written down and tested against the backup. Do not decommission the 2.x instance until the agreed review period has passed without a rollback decision.

8. Document the new baseline and retire the old one

   Update the system documentation to describe the O3 deployment, the configuration files, the module versions, the integrations, the backup schedule and the support responsibilities. Record what changed from 2.x and why, so future upgrades and audits can trace decisions. Once the rollback window has closed without use, archive the 2.x instance under access controls, record its retirement and remove any credentials or interfaces that still point to it. The step is done when a new team member can rebuild the O3 environment from the documentation and the retirement record is filed with the governance group.

Questions implementers ask before moving from OpenMRS 2.x to O3