Converting from HTML Form Entry (HFE Forms) to O3 Forms

Many implementers who have previously been using “O2”, also known as the OpenMRS 2 RefApp, have their previous forms encoded as HTML Form Entry (“HFE”) Forms.

This can feel intimidating especially if you have many (e.g. dozens!) of HTML-encoded forms which you need to move over to the O3 form schema, which is in JSON.

The good news is, implementers have several options to help them in their transition from HFE:

1. Schema Converter Script: This script contributed by community members helps you convert HTML forms into the O3 JSON schema, or at least gets you ~50% of the way there, so you at least have the skeleton of your usual HFE forms more automatically. Then from there you can finish filling them out using the O3 schema.

   1. GitHub repo for the Conversion Tool: https://github.com/openmrs/hfe-o3-form-schema-converter

   2. Video recording from 2023 with a helpful, early-days deep-dive into this HFE to O3 Schema migration tool:

      https://iu.mediaspace.kaltura.com/media/t/1_vdwpylj0?st=371 ; and accompanying Talk thread here.

   3. Note: this Conversion tool was originally written with a focus on converting forms to the early-days O3 Forms engine which was an Angular-based tool. The React Form Engine with O3 forms now use has a few specific schema deviations which as of July 2024 may not yet be 100% accounted for by the Conversion Tool.

2. Frankenstein Model: Since both O3 and O2 share the same database, you can actually allow your users to switch from the O3 interface to the O2 one. Some implementers do this to allow for a more gradual transition from O2 to O3, such as when a team in Kenya used the O3 Appointment and Queues features, but still used their previous O2 UI (with HFE forms) for patient care. This allowed them to get started with O3 without having to first transition all their forms.

3. Open HFE Forms in a new modal: Some work done by community members allows O3 systems to open forms in HFE view in a new tab, outside of the O3 UI. Read more here: https://talk.openmrs.org/t/o3-support-for-html-form-entry-in-3-x/35797/8

O3 form schemas conform to a standard JSON schema. Forms that match this schema can be used with the Form Engine that it ships with. This means that if you have a form that doesn't match this schema, you'll need to convert it to a JSON representation that is compatible O3 schema before you can use it with O3.

Many implementers have forms built using the HTML Form Entry module. To make it easier to migrate these forms to O3, the Palladium Kenya team built a tool that helps you convert your HTML Form Entry forms to O3 schema. This HFE to O3 schema converter tool helps you migrate your forms by taking care of some important aspects, including:

• Handling obs with defined answerConcepts and where the answers should be inferred from the dictionary

• Handling of obs styling for radio, checkbox, dropdown

• Handling obs fields that are marked as required

• Handling of diagnosis answerClass

• Handling of custom labels as defined in answerLabel/answerLabels

• Schema generation for the obsgroup tag. The logic can group questions within an obs group. It also generates a schema for groups marked as repeating

• Exporting the HFE schema to a configurable directory. This is helpful in cases where the HFE schema requires further updates to generate the correct JSON schema

• Provide labels for grouped obs. A new attribute labelText is supported for that

• Grouping of related checkboxes

While this won't get you all the way there in terms of migrating your forms, it should get you far along enough that you can use O3's built-in form builder to make the remaining changes to your schemas.

If you wish to contribute to improving the tool, feel free to read through the project README to see what the feature roadmap looks like. We'd love to have you on there!

You can also read through the related talk post on OpenMRS Talk.