Building forms using the O3 Form Builder

O3 comes out of the box with a built-in form builder that you can use to build form schemas. The Form Builder is provided by @openmrs/esm-form-builder-app and uses the React Form Engine to render form previews. When validation is enabled, the builder also runs schema checks against configured rendering-type mappings, dictionary concepts, answer concepts, patient identifier types, and person attribute types. To access it, go to ${openmrsSpaBase}/form-builder, or click the app switcher icon in the navigation bar, open System Administration, and select the Form Builder card. The app expects the backend to provide FHIR2 >=1.2 and REST Web Services >=2.2.0.

5 Minute Demo Video (Explained in Detail Below)

Intro to Using the O3 Form Builder

Features of the O3 Form Builder

The main pages in the O3 form builder are:

The Forms Dashboard - where you’ll see a tabular list of form schemas saved in your server. You can search through the available forms and filter them by Active, All, Published, Unpublished, or Retired status. The dashboard defaults to Active. You can also click on a form name or the edit action next to each form to launch it in the form editor, where you can make changes to it.
The Form Editor - where you can create a new form schema or edit an existing one. The Form Editor consists of the following things:
- Schema Editor - contains an embedded JSON editor that uses the React Ace library. You can import a schema, load a sample schema when creating a new form, copy or download the current schema, and click Render changes to sync manual JSON edits to the preview. JSON code typed into the editor should match the standard O3 form schema . Read the React Form Engine documentation to learn more about what schema properties are available.
- Preview - a live form preview that renders the form schema using the React Form Engine as you would see it within your EMR. The preview updates automatically from the Interactive Builder and after you click Render changes for Schema Editor edits. You can also choose the preview language when the form has translations.
- Interactive Builder - an interactive UI that enables you to build out your form schemas without writing JSON code. Changes to your schema get synced over to both the Schema Editor and the Preview as you build your form. You can use the Interactive Builder to add pages, sections, and questions to your form.
- Translation Builder - a UI for adding and editing schema translations that can be previewed from the language selector in the editor.
- Audit Details - a UI that displays metadata related to a saved form, including the form’s name, description, UUID, version, encounter type, creator, last editor, published status, and retired status.

Once you’ve built out your form schema to fit your requirements, you could choose to:

Validate form - when @openmrs/esm-form-builder-app is configured with enableFormValidation: true, the editor shows validation actions that check the schema against concepts and configured rendering rules. By default this validation workflow is disabled, and the form can be published with the regular publish action. The related blockRenderingWithErrors setting controls whether schema errors block the preview from rendering when you click Render changes; it is false by default.
Save your form to the server - saving your schema persists it in your OpenMRS database. Shared demo or test servers can be reset, so keep version-controlled backups of important schemas and avoid relying on a demo server as the only copy.
Publish or unpublish your form - once you’ve saved your form, you can choose to publish it. Only published O3 JSON forms are shown in the default React Form Engine workflow in the patient chart. If form validation is enabled, the publish action becomes Validate and publish form; otherwise, it appears as Publish form. You can unpublish existing published forms when you want to remove an older version from clinical use while preserving its history.

Key Form Engine Capabilities

The React Form Engine that powers the Form Builder supports a wide range of features for building complex clinical forms. Here are some of the most important capabilities:

Form Structure

Forms are organized hierarchically:

Pages - Top-level containers that group related sections
Sections - Groups of related questions (can be expanded/collapsed)
Questions - Individual form fields that collect data

Common Rendering Types

Questions can be rendered in various ways depending on the rendering property in questionOptions:

Basic inputs: text, textarea, number
Date, time, and encounter metadata: date, datetime, encounter-location, encounter-provider, encounter-role
Selection: select, select-concept-answers, radio, checkbox, checkbox-searchable, content-switcher, toggle, ui-select-extended
Clinical and specialized inputs: drug (for medication orders), problem (for diagnoses), file (for attachments), workspace-launcher (to open other workspaces), extension-widget (to render a custom extension)
Structural and read-only content: group (for obs groups), repeating (for repeatable sections), markdown, fixed-value

Advanced Features

Conditional rendering - Show/hide fields based on other field values using hide.hideWhenExpression
Calculated fields - Automatically compute values using calculate.calculateExpression
Validation - Validate field values with custom validators
Historical expressions - Pre-fill fields with values from previous encounters
Data sources - Populate fields from external data sources
Subforms - Embed reusable forms within other forms
Translations - Store translations in the schema and preview the form in a selected language
Post-submission actions - Execute actions after form submission (e.g., program enrollment)

For comprehensive documentation on all available features, rendering types, validation options, and advanced capabilities, see the React Form Engine documentation .

Configuring the Form Builder

@openmrs/esm-form-builder-app exposes configuration for the builder UI and schema validation workflow:

questionTypes controls the question types available in the Interactive Builder. The default set includes control, encounter metadata types, obs, obsGroup, patientIdentifier, personAttribute, testOrder, and programState.
fieldTypes controls the rendering types available for questions. The default list matches the common rendering types above.
dataTypeToRenderingMap maps concept datatypes to suggested rendering types when the builder is working from dictionary concepts. For coded concepts, the default map includes the legacy multiCheckbox alias; the Form Engine normalizes that to searchable checkbox behavior, so new schemas should use checkbox-searchable.
showSchemaSaveWarning defaults to true and controls the dashboard warning about saving schemas outside demo or resettable servers.
enableFormValidation defaults to false. When set to true, the editor shows validation actions and the publish action changes to Validate and publish form.
blockRenderingWithErrors defaults to false. When set to true, schema errors prevent the preview from rendering after you click Render changes.

Using the Form Builder

ℹ️

If you’re starting from a point where you have forms built using the HTML Form Entry module that don’t match the standard O3 form schema , you might want to begin by reading the conversion guide.

Creating a new form

To create a new form, do the following:

Step 1

Launch the form builder and click the Create a new form button. You’ll be directed to the Form Editor.

Step 2

Here, you can choose to type JSON code into the Schema Editor or to build your form dynamically using the Interactive Builder.

To use the Schema Editor:

Click on the Schema Editor tab (if not already selected)
Press the Load sample schema button (this button only appears when creating a new form with no existing schema) to get a scaffold in your editor where you can begin editing from. Amend the scaffold by deleting or replacing the values of the properties highlighted below with your own content:
After making changes to your schema, click the Render changes button (located at the top of the Schema Editor) to sync your changes to the Form Preview


{
  "encounterType": "",
  "name": "Sample Form",
  "processor": "EncounterFormProcessor",
  "referencedForms": [],
  "uuid": "",
  "version": "1.0",
  "pages": [
    {
      "label": "First Page",
      "sections": [
        {
          "label": "A Section",
          "isExpanded": "true",
          "questions": [
            {
              "label": "A Question of type obs that renders a text input",
              "type": "obs",
              "questionOptions": {
                "rendering": "text",
                "concept": "a-system-defined-concept-uuid"
              },
              "id": "sampleQuestion"
            }
          ]
        },
        {
          "label": "Another Section",
          "isExpanded": "true",
          "questions": [
            {
              "label": "Another Question of type obs whose answers get rendered as radio inputs",
              "type": "obs",
              "questionOptions": {
                "rendering": "radio",
                "concept": "system-defined-concept-uuid",
                "answers": [
                  {
                    "concept": "another-system-defined-concept-uuid",
                    "label": "Choice 1"
                  },
                  {
                    "concept": "yet-another-system-defined-concept-uuid",
                    "label": "Choice 2"
                  },
                  {
                    "concept": "yet-one-more-system-defined-concept-uuid",
                    "label": "Choice 3"
                  }
                ]
              },
              "id": "anotherSampleQuestion"
            }
          ]
        }
      ]
    }
  ]
}

To use the Interactive Builder:

Click on the Interactive Builder tab
Click the Start building button
Enter a form name and an optional form description
Click the Create form button
Click the Add Page button to add a new page
Click the Add Section button to add a new section
Click the Add Question button to add a new question

Editing an existing form

Follow the steps below to edit existing forms:

Step 1

Launch the form builder and click the Pen icon next to a form schema. You’ll be directed to the Form Editor.

Step 2

Here, you can choose to use either the Schema Editor or the Interactive Builder to edit your schema. Follow the steps above for guidance.

Step 3

Ultimately, when you’re done editing your form, you’ll want to save it. Click the Save form button in the Form Editor. A confirmation modal will appear asking whether you want to update the existing version or save as a new form. Click Update existing version to update the current form, or Save as a new form to preserve the existing version and create a new one. Any details entered from either the Schema Editor or Interactive Builder should get picked up here automatically. If you’ve made significant changes, consider updating the version of your form and describing what changed in the description field. Fill in the form details (name, version, encounter type, description) and click Save to persist your changes to the server.

Step 4

At this point, if your form is ready for use, you can choose to publish it. Click Publish form, or Validate and publish form when validation is enabled, to make the form available in the patient chart.

Useful resources

React Form Engine documentation - comprehensive guide to the React Form Engine that powers the Form Builder’s preview and rendering
Form Builder app repo
React Form Engine library repo
Video tutorial: Form Builder demo (older UI wording, still useful for the core flow)

ℹ️

Note: For the ID, please use a Unique ID (eg generate one here ) rather than re-using the Concept ID as is shown in the video.