Vitals Data Mapper Service

Relevant source files

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

• openmrs-esm-patient-chart-main/packages/esm-patient-vitals-app/src/vitals/vitals-data.mapper.ts
• openmrs-esm-patient-chart-main/packages/esm-patient-vitals-app/src/vitals/VOICE_VITALS_IMPLEMENTATION.md
• readmes/FINAL_SUMMARY.md
• readmes/ARCHITECTURE_OVERVIEW.md
• readmes/IMPLEMENTATION_SUMMARY.md

The Vitals Data Mapper Service is a critical utility within the Voice Vitals Recording feature of OpenMRS. Its primary purpose is to translate structured JSON data received from AI extraction services (such as Google Gemini) into the specific form schema required by the OpenMRS frontend. This service ensures that extracted medical data is correctly formatted, validated, and prepared for auto-population into clinical forms.

Sources: readmes/FINAL_SUMMARY.md, readmes/IMPLEMENTATION_SUMMARY.md

Core Functionality and Logic

The service operates as a transformation layer between the backend AI response and the React-based form management system. It handles complex data parsing, specifically for composite vitals like Blood Pressure, and ensures that only valid, non-null data is passed to the form state.

Sources: openmrs-esm-patient-chart-main/packages/esm-patient-vitals-app/src/vitals/vitals-data.mapper.ts, openmrs-esm-patient-chart-main/packages/esm-patient-vitals-app/src/vitals/VOICE_VITALS_IMPLEMENTATION.md

Data Transformation Workflow

The mapping process follows a structured flow from raw extraction to form-ready objects:

The diagram above illustrates how the mapper filters incoming data and splits specific strings into multiple form fields.
Sources: readmes/ARCHITECTURE_OVERVIEW.md, openmrs-esm-patient-chart-main/packages/esm-patient-vitals-app/src/vitals/VOICE_VITALS_IMPLEMENTATION.md

Key Transformation Rules

• Null Handling: The mapper explicitly ignores null or undefined values. This prevents the auto-population logic from overwriting existing form data with blank values or setting numerical fields to zero.
• Blood Pressure Parsing: The AI provides Blood Pressure as a single string (e.g., "120/80"). The mapper identifies the "/" delimiter and splits this into systolicBloodPressure and diastolicBloodPressure.
• Type Safety: The service uses TypeScript interfaces to ensure that the output matches the VitalsBiometricsFormData schema.

Sources: openmrs-esm-patient-chart-main/packages/esm-patient-vitals-app/src/vitals/vitals-data.mapper.ts, readmes/IMPLEMENTATION_SUMMARY.md

Technical Architecture

The mapper is implemented as a standalone utility function, mapVitalsToFormData, which is utilized by the vitals-biometrics-form.workspace.tsx component through a callback mechanism.

Sources: readmes/ARCHITECTURE_OVERVIEW.md, openmrs-esm-patient-chart-main/packages/esm-patient-vitals-app/src/vitals/VOICE_VITALS_IMPLEMENTATION.md

Data Structure Mapping Table

The following table details how backend fields are mapped to frontend form schema fields:

Backend Field (AI)	Frontend Form Field	Transformation / Logic
Temperature	temperature	Direct mapping (assumes °C)
Blood Pressure	systolicBloodPressure	Parsed from string before "/"
Blood Pressure	diastolicBloodPressure	Parsed from string after "/"
Heart rate	pulse	Direct mapping
Respiration rate	respiratoryRate	Direct mapping
SpO2	oxygenSaturation	Direct mapping
Weight	weight	Direct mapping (assumes kg)
Height	height	Direct mapping (assumes cm)
BMI (calc.)	computedBodyMassIndex	Direct mapping
MUAC	midUpperArmCircumference	Direct mapping
Notes	generalPatientNote	Direct mapping

Sources: readmes/IMPLEMENTATION_SUMMARY.md, openmrs-esm-patient-chart-main/packages/esm-patient-vitals-app/src/vitals/VOICE_VITALS_IMPLEMENTATION.md

Integration Sequence

The mapper service is invoked during the "Extract Vitals" phase of the clinical workflow.

Implementation Details

The mapper is designed to be non-destructive and type-safe. It is located in the src/vitals/ directory of the esm-patient-vitals-app package.

Sources: readmes/FINAL_SUMMARY.md, openmrs-esm-patient-chart-main/packages/esm-patient-vitals-app/src/vitals/VOICE_VITALS_IMPLEMENTATION.md

Unit Conversion Context

While the mapper itself performs structural transformation, it relies on the backend AI service (vitals_gemini_test.py) to have already performed unit conversions (Fahrenheit to Celsius, lbs to kg, inches to cm). The mapper treats the incoming numerical data as standardized units ready for OpenMRS storage.

Sources: readmes/IMPLEMENTATION_SUMMARY.md, readmes/ARCHITECTURE_OVERVIEW.md

Code Structure Overview

The primary export is mapVitalsToFormData(vitals: VitalsData), which returns a partial VitalsBiometricsFormData object. The internal logic uses a conditional check for the existence of "Blood Pressure" to execute the string split operation using .split('/').

Sources: openmrs-esm-patient-chart-main/packages/esm-patient-vitals-app/src/vitals/vitals-data.mapper.ts, openmrs-esm-patient-chart-main/packages/esm-patient-vitals-app/src/vitals/VOICE_VITALS_IMPLEMENTATION.md

Summary

The Vitals Data Mapper Service provides a necessary abstraction between AI-generated transcripts and the OpenMRS data model. By handling the complexities of Blood Pressure parsing and ensuring null-safety, it allows for a seamless "Extract and Populate" user experience for clinicians, maintaining the integrity of the medical record while reducing manual data entry.

Sources: readmes/README_VOICE_VITALS.md, readmes/FINAL_SUMMARY.md