O3: Major Upgrade to Improve Performance

Summary: O3 recently had a major release to the underlying technology that:

  • (A) resolves the vast majority of known performance issues in O3; and,
  • (B) significantly reduces the exposed complexity of the O3 framework.

The release contains some breaking changes for O3 implementers. We know this can be intimidating - here are some resources to help folks with this process.

We do strongly recommend that O3 implementers upgrade to this version of the O3 Framework, specifically, esm-core-v5.1.x. If you haven’t already migrated to esm-core-v5.0, we advise you migrate directly to v5.1 (esm-core-v5.0 had some bugs in the patient chart that v5.1 fixes, so we want to save you those headaches).

Support with the O3-Core Migration

If your organization would like support with this upgrade, we recommend these 2 steps:

  1. :open_book: Must-Read Migration Guide: Have your technical team review this Migration Guide written for exactly this scenario! Migrating to Core v5 – O3 Docs

    • :clapper: Optional Additional Video: Walkthrough by engineers explaining the current state of the foundational technology, and the abstractions that we have hidden to reduce complexity for feature developers: O3 App Shell Deep-Dive Recording
  2. :telephone_receiver: Daily O3 Dev Support Hours: Have relevant engineering members from your team join any of the O3 Dev “Coffee Chat” calls (like office hours for O3 developers) for 1:1 support from the OpenMRS Global Product Support Team. These are every Monday-to-Thursday at 2:30pm EAT / 5:00pm IST / 7:30am EDT on Zoom at https://om.rs/o3coffee - See it on the OpenMRS community calendar at https://om.rs/cal

And, if you have even more detailed questions or want a 1:1 session, please reach out to our Community’s Frontend Engineering Lead @dennis. We know this breaking change is intimidating for some teams and he’s very happy to help!

Code Links

Find the release details of esm-core-v5.1.0 here, as well as for previous releases including v5.0: https://github.com/openmrs/openmrs-esm-core/releases

Review the changelog for esm-core-v5.10: https://o3-docs.vercel.app/docs/changelog

The OpenMRS 3 RefApp will soon be updated to include v5.1.x, (as part of the 3.0.0-beta.10 release, planned for this week) so then you will be able to also grab the updated docker image here: https://hub.docker.com/r/openmrs/openmrs-reference-application-3-frontend


A huge thank you to @ibacher and @dennis who spent many painfully long hours in the last 2 months working on this very difficult release. Thanks also to SingleSPA founder and maintainer @joeldenning who helped us check through our work so we could benefit from lessons from the wider SingleSPA community and pro-actively check for any unintended future consequences. Thanks @raff for also tackling backend and API-related issues during this process. Thanks to the teams at @PalladiumKenya, @PIH, and @UCSF for being some of the first guinea-pigs to try out esm-core-v5.0 and share with us the issues you ran into. And thanks to our QA Support Team with @jayasanka and @piumal1999 and @anjisvj for the work they’re doing to firm-up our release pipeline - we are currently in the process of updating the automated smoke-tests that run against O3 PRs to adapt them after these breaking changes. Thanks team!!!

CC: @slubwama @frederic.deniger @jesplana @gsluthra @mksrom @jobby @ggomez @dagimm (please CC anyone else whose team you think may be interested!)


In order to benefit from improved performance of API requests please upgrade the FHIR module to the 1.10.0 version. It’s also recommended to enable query caching as explained here.

1 Like

My apologies, I wrote the Coffee Chat time wrong. It is now corrected above, and I’ve added the zoom link for easy access for folks :slight_smile:

And, excellent point above, @raff!! Perhaps you could add that to the Migration Docs linked above?

The migration docs are for esm-core-v5.10. The info about the FHIR upgrade doesn’t seem to fit in there. Do we have O3 general upgrade guide?