Building forms using the O3 Form Builder

O3 comes out of the box with a built-in form builder that you could leverage to build your form schemas. The Form Builder uses the React Form Engine (opens in a new tab) to render form previews and validate schemas. To access it, click the app switcher icon in the navigation bar and click the System Administration link. You'll get navigated to the System Administration page where you'll see a list of cards for apps. Click on the Form Builder card and you'll be navigated to the Form Builder UI.

5 Minute Demo Video (Explained in Detail Below)

Intro to Using the O3 Form Builder (opens in a new tab)

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 publish status. You can also click on the Edit icon 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 (opens in a new tab) library. Changes made to the schema editor have to be synced over to the Form Preview by clicking the Render changes button at the top of the editor. JSON code typed into the editor should match the standard O3 form schema (opens in a new tab). Read the React Form Engine documentation (opens in a new tab) to learn more about what schema properties are available.
- Form Preview - a live form preview that renders the form schema using the React Form Engine (opens in a new tab) as you would see it within your EMR. The Form Preview responds to changes made to the Schema Editor and the Interactive Builder.
- 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 Form Preview as you build your form. You can use the Interactive Builder to add pages, sections, and questions to your form.
- Audit details - a UI that displays audit information related to a form, including the form's name, description, version, and published status.

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

Validate fields - the O3 Form Builder has rich validation capabilities powered by the React Form Engine. To learn more about what's possible, read the React Form Engine documentation (opens in a new tab).
Save your form to the server - saving your schema to your own database is the best way to guarantee persistence. The O3 server is ephemeral at best and should not be relied upon for persisting your schemas. We recommend maintaining a local backup of your schemas to avoid losing them when working with the O3 server.
Publish or unpublish your form - Once you've saved your form, you can choose to publish it. Only published forms are accessible to the forms workspace in the patient chart. We recommend maintaining some kind of versioning scheme so you can control which forms are accessible to users and which ones aren't. In addition to publishing forms, you can also unpublish existing published forms. This can be useful if, say, you want to deprecate an older version of a form and replace it with a new version but wish to maintain some kind of version 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:

Text inputs: text, textarea, number
Date/time: date, datetime
Selection: select, radio, checkbox, checkbox-searchable, toggle
Special: drug (for medication orders), file (for attachments), problem (for diagnoses), workspace-launcher (to open other workspaces)
Structural: group (for obs groups), repeating (for repeatable sections), markdown (for read-only content)

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
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 (opens in a new tab).

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 (opens in a new tab), 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 Input Dummy 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",
                    "conceptMappings": []
                  },
                  {
                    "concept": "yet-another-system-defined-concept-uuid",
                    "label": "Choice 2",
                    "conceptMappings": []
                  },
                  {
                    "concept": "yet-one-more-system-defined-concept-uuid",
                    "label": "Choice 3",
                    "conceptMappings": []
                  }
                ]
              },
              "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 at the top of the Form Editor. A confirmation modal will appear asking whether you want to update the existing version or save as a new form. Click the Update existing version button to update the current form. Any details entered from either the Schema Editor or Interactive Builder should get picked up here automatically. If you've made significant changes, you might consider updating the version of your form, as well as describing what changed in the description field. Fill in the form details (name, version, encounter type, description) and click the Save button 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. To do so, click the Publish form button at the top of the Form Editor to publish the form and make it available in the patient chart.

Useful resources

React Form Engine documentation (opens in a new tab) - comprehensive guide to the React Form Engine that powers the Form Builder's preview and rendering
Form Builder app repo (opens in a new tab)
React Form Engine library repo (opens in a new tab)
Video tutorial: Form Builder demo (old version)

ℹ️

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

Feature flags Convert HTML form entry forms to O3