OpenMRS ESM Fast Data Entry App

The Fast Data Entry App is a module for the OpenMRS healthcare platform which allows for a natural workflow when entering many pre-recorded forms at a time. It is not meant for point-of-care workflows, but rather as a way to do retrospective data entry. For more detailed information, see the FDE Wiki Documentation.

Overview

Currently the app consists of three main parts, a Forms Page to list available forms, Fast Data Entry which allows the rapid input of forms, and Group Sessions which enable recording information about a group session as well as individual forms for the session participants.

Forms Page

The Forms page lists all forms able to be seen by a user, filtered by that user's permission to edit the given form. Additionally implementors are able to customize the page by creating form categories and listing the forms inside of each category. These categories can then be shown or hidden using configuration (see more here). From these lists forms are able to be opened in the Form Workflow using the 'Fill form' button.

Fast Data Entry

Forms can be entered quickly with the Form Entry Workflow. This workflow depends on a state machine managed by the FormWorkflowReducer.

See the video below of a normal workflow.

fde-workflow.mov

State diagram for the Form Workflow.

Group Sessions

Group Sessions can be recorded with use of the Group Session Workflow. This workflow depends on a state machine managed by the GroupFormWorkflowReducer.

See the video below of a normal workflow

NormalGroupSessionWorkflow.mov

At the end, data from the group session will be visible on the patient's chart

Group Builder

This app also contains a Group Builder for quickly putting together a group of patients and storing them as a cohort. While this feature arose to meet the needs of the workflow the concept is valid for the broader platform and could, some day, be moved to a more central location so more apps could make use of it. AddGroupModal was created in a way to reduce external dependencies so this eventual transition would be easier.

GroupSearch.CreateGroup.mov

Pre-Filled Questions

In many retrospective workflows, certain fields on a form may have the same value across multiple patients (e.g., session date, facility name, or session type). Rather than forcing the data clerk to re-enter these values repeatedly, the Fast Data Entry (FDE) app supports pre-filled questions.

These are configured in the specificQuestions schema. The schema allows you to:

• Identify which forms the question applies to.
• Point to the question ID within the form schema.
• Optionally define a default answer.
• Optionally limit the set of answer choices (for coded inputs).

Example Schema

"specificQuestions": [
  {
    "forms": [
      "547c0814-eb78-3280-91a8-8d7c574e0301",
      "0f5d1e6c-8f8e-3d5c-ac50-f0db0c74d7d8"
    ],
    "questionId": "placeOfConsultation"
  },
  {
    "forms": [
      "547c0814-eb78-3280-91a8-8d7c574e0301",
      "0f5d1e6c-8f8e-3d5c-ac50-f0db0c74d7d8"
    ],
    "questionId": "practitionerAffiliation"
  },
  {
    "forms": [
      "547c0814-eb78-3280-91a8-8d7c574e0301",
      "0f5d1e6c-8f8e-3d5c-ac50-f0db0c74d7d8"
    ],
    "questionId": "typeOfSession",
    "defaultAnswer": "9bc5ecea-7c82-11e9-8f9e-2a86e4085a59",
    "answers": [
      "9bc5ecea-7c82-11e9-8f9e-2a86e4085a59",
      "3a826502-6d4a-4e84-82e2-13deb0a5f958"
    ]
  },
  {
    "forms": [
      "547c0814-eb78-3280-91a8-8d7c574e0301",
      "0f5d1e6c-8f8e-3d5c-ac50-f0db0c74d7d8"
    ],
    "questionId": "sessionFormat"
  },
  {
    "forms": [
      "547c0814-eb78-3280-91a8-8d7c574e0301",
      "0f5d1e6c-8f8e-3d5c-ac50-f0db0c74d7d8"
    ],
    "questionId": "targetGroupProgramType"
  }
]

Schema Keys

• forms: Array of form UUIDs. The pre-fill rule applies only to these forms.
• questionId: The field identifier in the form schema to pre-fill. Must exist in the published form schema.
• defaultAnswer (optional): A concept UUID or value to use as the default answer.
• answers (optional, for coded inputs): Array of concept UUIDs to restrict the available answer options.

Use Cases

1. Shared Values Across Patients

   • Example: “Date of Consultation” is the same for all 20 patients in a session. Instead of retyping it 20 times, pre-fill once.

2. Default Answers

   • Example: “Type of Session” defaults to Counseling. Users can override if necessary.

3. Restricting Options (multi-select)

   • Example: A schema defines four session formats, but only two are relevant in this workflow. The answers array limits options to those two.

4. Multiple Forms, One Rule

   • A single pre-fill definition can target the same field across multiple forms.

Important Notes

• Forms must be published before pre-filled values will display.
• The questionId must match an existing field in the form schema.
• Concepts used in defaultAnswer or answers must exist in the database; otherwise, the UI will show empty values

Integration with Form Engines

Since all forms in OpenMRS are submitted via a form engine, FDE relies on one of two wrapper modules:

• Form Engine App
• Form Entry App

⚠️ Important: The Fast Data Entry (FDE) feature is supported only by JSON schema–based form engines (e.g., the React Form Engine or the Angular Form Engine).
A distribution can activate only one wrapper module at a time.

👉 For example, the O3 Reference Application uses the React Form Engine

Adopting a Form Engine with FDE

1. Add the wrapper module (Form Engine App or Form Entry App) to the frontend modules in your distribution.
2. Do not add both wrappers at the same time. They depend on the same OpenMRS extension framework resources (e.g., extension-slots), and will conflict.
3. Once the wrapper is loaded, FDE automatically integrates with the form engine.

Why This Works

Because the form engines themselves have been extended to support FDE, the FDE module remains generic and independent. Its flexibility comes from the OpenMRS extension system, particularly:

• form-widget-slot → provide an entry point for rendering forms.
• ampath-form-action event → used by both form engines to synchronize form operations with FDE.

Running this code

Clone the repo locally, then install and run using

yarn  # to install dependencies
yarn start  # to run the dev server

To customize your development build pass other arguments to yarn start (which under the hood is running npx openmrs develop). For example to point to a backend other than dev3 specify the --backend option. See the full example below for running against an ICRC backend.

yarn start --importmap "https://spa-modules.nyc3.digitaloceanspaces.com/import-map.json" --backend "https://openmrs-dev-v2.test.icrc.org/" --add-cookie "MRHSession=abcdefghijklmnop012345678910" --spa-path "/ui"

To see more options run npx openmrs --help

To run end-to-end tests, run:

yarn test-e2e

Read the e2e testing guide to learn more about End-to-End tests in this project.