Form Engine & Renderer

Relevant source files

The following files were used as context for generating this wiki page:

• openmrs-esm-patient-chart-main/packages/esm-form-engine-app/package.json
• openmrs-esm-patient-chart-main/packages/esm-patient-vitals-app/src/vitals/VOICE_VITALS_IMPLEMENTATION.md
• openmrs-esm-patient-chart-main/packages/esm-patient-medical-documentation-app/src/discharge-summary/discharge-summary-form.workspace.tsx
• openmrs-esm-patient-chart-main/packages/esm-patient-vitals-app/src/vitals/vitals-data.mapper.ts
• readmes/FINAL_SUMMARY.md
• openmrs-esm-patient-chart-main/packages/esm-patient-orders-app/README.md

The Form Engine & Renderer serves as the core infrastructure for capturing clinical data within the OpenMRS 3.0 (O3) ecosystem. It is designed as a wrapper microfrontend for the O3 React Form Engine, providing a standardized way to render complex clinical forms, manage their state, and handle data submission to the OpenMRS backend.

This system supports diverse clinical workflows, ranging from basic vital sign collection to complex medical documentation like discharge summaries. It integrates advanced features such as AI-powered auto-population and voice-to-vitals transcription to improve provider efficiency.

Sources: openmrs-esm-form-engine-app/package.json, openmrs-esm-patient-chart-main/packages/esm-patient-vitals-app/src/vitals/VOICE_VITALS_IMPLEMENTATION.md:3-8

System Architecture

The form architecture is modular, separating the UI representation (Renderer) from the underlying logic (Engine) and data mapping utilities. It utilizes react-hook-form for state management and zod for schema-based validation.

Core Components and Dependencies

Component	Responsibility
@openmrs/esm-form-engine-lib	The underlying library providing the core logic for form definition parsing and state management.
Form Workspace	Container components (e.g., DischargeSummaryFormWorkspace) that manage the lifecycle of a specific form within the patient chart.
Data Mappers	Utility functions that transform external data (like AI-extracted vitals) into the schema required by the form fields.
Validation Schema	Zod-based definitions ensuring data integrity before submission to the REST API.

Sources: openmrs-esm-form-engine-app/package.json:44, openmrs-esm-patient-medical-documentation-app/src/discharge-summary/discharge-summary-form.workspace.tsx:6-8, openmrs-esm-patient-vitals-app/src/vitals/vitals-data.mapper.ts

Form Data Flow

The following diagram illustrates how data flows from user input or external AI services into the form engine and finally to the OpenMRS backend.

The Form Engine acts as the central orchestrator, validating input from multiple sources before finalizing the encounter.
Sources: readmes/FINAL_SUMMARY.md:124-142, openmrs-esm-patient-vitals-app/src/vitals/VOICE_VITALS_IMPLEMENTATION.md:83-113

Clinical Documentation Workflows

The engine supports specialized workspaces for different types of clinical documentation. A primary example is the Discharge Summary, which involves complex data aggregation and multi-section rendering.

Discharge Summary Workspace

The DischargeSummaryFormWorkspace manages the transition between a list view of existing summaries and a form view for creation or editing. Key features include:

• Auto-fill Integration: Pulls data from Chief Complaints, Diagnosis, and Lab Results encounters.
• PDF Generation: Uses jspdf to generate professional medical documents directly from form state.
• AI Summarization: Integrates with external LLM services to generate clinical narratives based on daily notes.

Sources: openmrs-esm-patient-medical-documentation-app/src/discharge-summary/discharge-summary-form.workspace.tsx:28-60, openmrs-esm-patient-medical-documentation-app/src/discharge-summary/discharge-summary-form.workspace.tsx:162-212

Order Management Forms

The system also handles laboratory and medication orders. Lab forms are dynamically generated based on concept metadata:

• Concept Numeric Table: Ranges (hiAbsolute, lowAbsolute) and units are derived from the OpenMRS concept dictionary.
• Validation: Real-time decimal restrictions and range checks are applied based on the underlying concept configuration.

Sources: openmrs-esm-patient-orders-app/README.md:65-71

Advanced Data Entry: Voice and AI

To streamline documentation, the Form Engine integrates with a "Voice Vitals" system. This allows nurses to speak vitals, which are then transcribed and mapped to form fields.

Voice-to-Form Mapping Logic

The vitals-data.mapper.ts utility is critical for converting unstructured AI output into structured form data.

// Mapping logic example for Blood Pressure and Units
export const mapVitalsToFormData = (vitals: VitalsData) => {
  const formData: any = {};

  if (vitals['Blood Pressure']) {
    const [systolic, diastolic] = vitals['Blood Pressure'].split('/');
    formData.systolic = systolic;
    formData.diastolic = diastolic;
  }
  
  // Handles unit conversion and null checks
  if (vitals.Temperature) formData.temperature = vitals.Temperature;
  return formData;
};

Sources: openmrs-esm-patient-vitals-app/src/vitals/vitals-data.mapper.ts, openmrs-esm-patient-vitals-app/src/vitals/VOICE_VITALS_IMPLEMENTATION.md:139-160

AI Integration Sequence

The following sequence shows the interaction between the form component and the AI backend during voice extraction.

The integration ensures that all AI-populated fields remain fully editable by the clinician before the final "Save & Close" action.
Sources: openmrs-esm-patient-vitals-app/src/vitals/VOICE_VITALS_IMPLEMENTATION.md:115-135, readmes/FINAL_SUMMARY.md:124-142

Configuration and Customization

Implementers can customize form behavior through configuration schemas. This includes setting default encounter types, defining which concepts are orderable, and toggling UI features like print buttons.

Key Configuration Points

Parameter	Description
orderEncounterType	UUID for the encounter type used for orders.
clinicianEncounterRole	The role assigned to the provider during form submission.
showReferenceNumber	Boolean to toggle accession/reference number fields in order forms.

Sources: openmrs-esm-patient-orders-app/README.md:38-45, openmrs-esm-patient-medical-documentation-app/src/discharge-summary/discharge-summary-form.workspace.tsx:216-220

Conclusion

The Form Engine & Renderer is a robust, extensible framework that bridges the gap between clinical intent and data persistence. By combining standard React patterns with specialized medical logic and emerging AI capabilities, it provides a high-performance environment for clinical data entry in OpenMRS.