Metadata Initializer Packages
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Metadata Initializer Packages provide a versioned, portable method for deploying OpenMRS clinical metadata across different environments. These packages contain CSV-based configurations for concepts, encounter types, person attribute types, and patient identifier types, ensuring that the frontend applications and AI backend services have a consistent set of clinical definitions to interact with.
The system relies on a "UUID contract," where clinical resources (like the "Chief Complaint" encounter type) use deterministic UUIDs. This stability is critical because the OpenMRS 3 patient chart and the FastAPI-based AI services reference these specific IDs to read and write clinical data.
Sources: deployment/openmrs-initializer/README.md, README.md:105-115
Metadata Architecture and Components
The metadata ecosystem is divided into source-of-truth scripts and the generated Initializer package used for production deployment.
Component Overview
| Component | Purpose | Location |
|---|---|---|
| Setup Scripts | Python scripts that create metadata via REST API during development. | openMRS-main/setup_medical_documentation_concepts.py |
| Master UUID Config | A JSON file acting as the central contract for all deterministic UUIDs. | openMRS-main/medical_documentation_config.json |
| Initializer Package | CSV files and a metadata inventory used by the OpenMRS Initializer module. | deployment/openmrs-initializer/configuration/ |
| Metadata-Init Service | A Docker container that runs initialization scripts on startup. | deployment/metadata-init/ |
Sources: README.md:25-35, deployment/openmrs-initializer/README.md, deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:151-160
The Metadata Lifecycle
The lifecycle follows a path from script-based creation in development to containerized initialization in production.
The metadata-init service handles the automated loading by waiting for the OpenMRS backend to be healthy before executing scripts like setup_medical_documentation_concepts.py to ensure all 326 custom concepts and 27 encounter types are present.
Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:151-170, deployment/openmrs-initializer/README.md
Data Structures and Configuration
The metadata is categorized into several distinct types required for Indian public hospital OPD intake workflows.
Types of Managed Metadata
- Concepts: Clinical definitions (e.g., Hemoglobin, Hypertension, Social History).
- Encounter Types: Categories for clinical interactions (e.g., Chief Complaint, General Examination).
- Person Attribute Types: Additional patient data fields (e.g., Father's Name, Occupation).
- Patient Identifier Types: Unique hospital IDs (e.g., CR Number).
Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:151-155, openMRS-main/setup_medical_documentation_concepts.py:16-25
Configured UUID Stability
Deterministic UUIDs are used to prevent breakage in the Patient Chart frontend. For example, numeric concepts are explicitly configured to allow decimals to support precise lab results.
# Example of numeric concept synchronization for decimal support
sync_numeric_concepts_allow_decimal([
"Hemoglobin", "Total Bilirubin", "Creatinine", "MELD Score"
])
Sources: openMRS-main/setup_medical_documentation_concepts.py:650-670, openmrs-esm-patient-chart-main/packages/esm-patient-orders-app/README.md:95-100
Implementation Logic
Idempotency and Verification
The metadata-init service uses idempotent logic. Before attempting to create a resource, the system checks if a resource with the same name or UUID already exists via the REST API.
Deployment Workflow
In a production environment, the configuration/ directory containing the CSV files must be mounted into the OpenMRS application data directory.
| Directory | Contained Metadata |
|---|---|
configuration/concepts/ | concepts-ehr.csv |
configuration/encountertypes/ | encountertypes-ehr.csv |
configuration/personattributetypes/ | personattributetypes-ehr.csv |
configuration/patientidentifiertypes/ | patientidentifiertypes-ehr.csv |
Sources: deployment/openmrs-initializer/README.md, deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:65-75
Summary
Metadata Initializer Packages serve as the backbone for clinical data consistency in the OpenMRS AI EHR system. By utilizing deterministic UUIDs and idempotent Python scripts within a Dockerized metadata-init service, the project ensures that hospital deployments are reproducible and that custom frontend modules for medical documentation and vitals remain functional across environment migrations.
Sources: README.md:12-20, deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:151-160