Skip to Content
DocsForms in O3Convert HTML form entry forms to O3

Converting HTML Form Entry forms to O3

Overview

O3 form schemas conform to a standard JSON schema . Forms that match this schema can be used with the React Form Engine that powers O3’s JSON form rendering. If you want an HTML Form Entry form to run as a React Form Engine form, you’ll need to convert it to a JSON representation that is compatible with the O3 schema.

ℹ️

To learn more about the various properties that make up the schema, read the React Form Engine documentation .

ℹ️

The patient chart can still render configured HTML Form Entry forms through @openmrs/esm-patient-forms-app. Use this conversion guide when you want those forms to become O3 JSON forms that can be edited in the Form Builder and rendered by the React Form Engine.

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 answerConceptId or answerConceptIds, and obs whose answers should be inferred from the dictionary
  • Handling of obs styling for radio, checkbox, dropdown
  • Handling diagnosis-style obs that use answerClasses="Drug"
  • 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

Using the converter tool

Prerequisites

Before using the converter, you need to configure a global property:

  1. Install the HFE to O3 schema converter  module in the backend where your HTML Form Entry forms are available.
  2. Set the htmlformmigration.resources global property to an absolute path of a writable directory where HTML form schemas will be exported.

Accessing the converter

  1. Navigate to <OpenMRS base url>/htmltojson/htmlFormToJsonHome.page in your browser
  2. The converter will display a list of all forms in your system

Conversion workflow

The conversion process involves two steps:

  1. Export HTML forms: Click the “Export HFE forms schema” button to export all HTML Form Entry schemas to the configured directory. This step is required before conversion can happen, as the converter reads from these exported files.

  2. Convert to JSON: After exporting, click on a form in the list to view its converted JSON schema. You can:

    • View the generated JSON schema in a modal dialog
    • Open the “View and copy” dialog, which provides a JSON editor for copying or adjusting the generated schema
    • Copy the generated JSON into a file and continue refining it in the O3 Form Builder

Important notes

  • Default structure: The converter generates a default “Starter page” with a single “Starter section” containing all questions. You’ll need to manually organize questions into appropriate pages and sections using the O3 Form Builder.

  • Version placeholder: The generated schema includes a placeholder version ("version": "xxx"). You must update this to a proper version number (e.g., "1.0") before using the form.

  • Repeating groups: Some converter versions emit questionOptions.rendering: "repeat" for repeating obsgroup fields. Current O3 schemas should use "repeating", so update that value before validating or publishing the form.

  • File-based conversion: The converter reads HTML forms from the exported files in the configured directory, not directly from the database. Make sure you’ve exported the forms before attempting conversion.

Limitations

The converter tool has some limitations:

  • Supported tags: Only obs and obsgroup tags are currently supported. Other HTML Form Entry tags are not converted automatically.
  • Pages and sections: The converter generates questions but does not automatically create pages and sections. You’ll need to manually organize the converted questions into pages and sections using the O3 Form Builder.
  • Rendering aliases: Review generated rendering values against the Form Builder’s current field types. In particular, change repeat to repeating for repeating groups.
  • Validation rules: Validation support is limited. The converter detects required="true" on obs tags, but current generated question JSON does not reliably emit those required flags, so review the source HFE form and add required validation rules manually.
  • Manual adjustments: After conversion, you may need to manually adjust the generated schema, especially for complex forms or forms using unsupported features.

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.

Last updated on
Build forms using the O3 form builderUsing forms in applications