O3 Form Engine Strategy in 2023

In the past month, 6 different active community organizations have asked me to help clarify our O3 Form Engine Strategy. Here we go:

Strategy Explained

Short-Term Solution = Angular Form Engine: We recommend folks needing production-ready instances of O3 use the Angular Form Engine (code here).

Longer-Term Solution = React Form Engine: We hope to transition to a React Form Engine, for all the reasons expressed here, which remain true today. First, a minimum feature parity is required. To follow along on the work to get the React Engine to this required state, you can see the Jira Epic and/or the GitHub repo.

Key Points, Rationale, & Next Steps

  • Most production implementations of O3 are currently using the O3 Angular Form Engine. A smaller number are in early-days of trialing the O3 React Form Engine.
  • However, Parity ideally should also focus on supporting the widely used features in the HTML Form Entry Module, since most users are still using HFE, not either O3 Engine. Next Step #1: We need to do a detailed review of those to ensure we are headed in that direction. (@eudson’s team at UCSF has this on their list and we will use the HTML Reference wiki page to drive that analysis.)
  • Back in February we agreed via TAC community members that all the reasons to transition to a React-based engine made sense; then, with reps from several orgs, we scoped out together what that “feature parity” needed to look like - basically, implementers need ~90%+ of what the Angular Eng currently offers. Detailed requirements here. We remain strategically aligned with the need for a React-based form engine.
  • The React Form Engine is not yet at the feature-parity with the Angular Form Engine needed in order for folks to switch.
  • Thus, for the moment, until that parity is reached we will continue as an O3 community to recommend the Angular Engine for production implementations.
  • In the meantime @UCSF via the OHRI project, as the original creators of the React Engine project, is committed to improving the React Form Engine and hope to achieve this parity by September 2023.
  • Consistency is a problem to address in the O3 RefApp: Currently in O3, the Form Builder GUI tool uses the React Engine, whereas the actual Form Entry is using the Angular Engine. So an O3 RefApp user can build a form, preview it, think it looks perfect, then see unexpected behavior. Next Step #2: We need to be consistent in the meantime so a simple next step is for us to hook up the new Form Builder GUI admin tool to the Angular Form Engine.

Reasons not to worry

  1. If you are already using either engine: Likely no imminent action is required from your team. It is reasonable to add to either engine whatever functionality you need for your clients - it would be unreasonable for us to enforce a code-freeze on either engine at this time.

  2. The form schema is the same; so in the event we switch engines, translations will work the same, etc.

  3. Some of the O3-related work on forms is actually not Angular-specific, and that’s work we will continue to use even if we switch to the React engine.

  4. The goal here is not “we think this technology is neat, so we’re adopting it”; it’s “we have this code (in Angular) that we have fewer members of the community able to work on and we’d like to make it easier to work with (via eventually a React-based option)”.

  5. “Smell” tools exist. When your team is ready to see what would happen if you switched engines, you can paste existing form(s) into a tool like the OHRI Form Render Test app here (admin/Admin123) or even the O3 Form Builder to see if your form would render as expected using the new engine.

We are headed in the right direction, even if in the meantime there are practicalities to work around :slight_smile: Thank you so much to the entire community for your patience and ongoing contributions - our progress is and will be thanks to all of you!

CC: @aojwang @dkibet @minimalist @fanderson @mogoodrich @mseaton @cioan @ddesimone @ball @dagimm @samuel34 @slubwama @eudson @burke @dkayiwa @ibacher @dennis @alaboso @pirupius @jesplana @delphinep @frederic.deniger


until that parity is reached we will continue as an O3 community to recommend the Angular Engine for production implementations. - # We should discuss this topic during the OpenMRS conference. The React form engine will be moved to its desired state only with the help of the community. To achieve strategic alignment, we need to allocate resources accordingly.


Thanks @grace ! This makes sense to me… I have been planning to try to dive deeper into the React Form engine to see how I can help out, but I keep getting distracted by other pressing needs. I’m opening this will change in the coming weeks/months.

1 Like