OpenMRS Metadata Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
OpenMRS Metadata Configuration refers to the systematic definition and deployment of clinical and administrative entities—such as concepts, encounter types, person attributes, and patient identifiers—required for the AI-powered EHR system. In this project, metadata serves as a rigid contract between the backend database, the OpenMRS 3.0 frontend, and AI services (FastAPI), ensuring that every component references the same medical data points using deterministic, fixed UUIDs. Sources: README.md, deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:204-209
The configuration is designed for stability and portability, particularly for deployment in Indian public hospitals. It utilizes an automated "Metadata Init" process to synchronize 326 custom medical concepts, 27 encounter types, and various attribute types via the OpenMRS REST API. This ensures that every deployment, from local development to hospital production, maintains an identical data structure. Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:144-150, openMRS-main/setup_medical_documentation_concepts.py:12-25
Metadata Architecture and Initialization
The system employs a one-shot initialization container (metadata-init) that executes during the initial deployment of the production stack. This service ensures all required metadata is present before the clinical applications become operational. Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:52-54, README.md:252-258
Initialization Workflow
The metadata-init service follows a strict dependency chain:
- Wait for OpenMRS: The service polls the OpenMRS API until it is fully authenticated and exits "setup mode".
- Execute Idempotent Scripts: It runs Python scripts that check for the existence of each resource before attempting creation.
- UUID Enforcement: Resources are created using UUIDs from a master configuration file.
- Verification: The service verifies critical concepts (e.g., "Background History") before exiting.
Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:154-170, openMRS-main/setup_medical_documentation_concepts.py:101-140
The diagram shows the logic flow of the initialization service, emphasizing the idempotent check against the OpenMRS REST API.
Configuration Components
The metadata configuration is divided into several categories, each managed by specific setup functions in the automation scripts.
Encounter Types
Encounter types categorize clinical interactions. This system defines specific types for medical documentation tabs, such as "Demographic Profile", "Chief Complaint", and "Systemic Examination". Sources: openMRS-main/setup_medical_documentation_concepts.py:177-200
Person Attribute and Patient Identifier Types
These extend the patient profile with identifiers like "CR Number" and attributes like "Father Name" or "Occupation", which are critical for hospital registration workflows in India. Sources: openMRS-main/setup_medical_documentation_concepts.py:228-245, openMRS-main/setup_medical_documentation_concepts.py:277-295
Concept Management
The system defines a hierarchy of concepts using specific datatypes and classes.
| Component | Description | Example Entities |
|---|---|---|
| Coded Answers | Predefined responses for medical questions. | Yes, No, Present, Normal, Grade A |
| History Concepts | Textual data points for patient history. | Chief Complaint, Treatment History |
| Lab Concepts | Numeric results for investigations. | Hemoglobin, ALT, Creatinine, INR |
| Concept Sets | Groupings of related concepts (ConvSets). | Past Medical History, LFT, CBC |
Sources: openMRS-main/setup_medical_documentation_concepts.py:444-480, openMRS-main/setup_medical_documentation_concepts.py:716-740, openMRS-main/setup_medical_documentation_concepts.py:794-810
Master UUID Mapping
The file medical_documentation_config.json acts as the "source of truth" for the metadata contract. It contains a flat mapping of resource names to their fixed UUIDs. Sources: README.md:213-219, deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:204-209
ER diagram illustrating the relationship between the configuration file and the instantiated OpenMRS entities.
Code Implementation: Deterministic Creation
The following Python logic demonstrates how the setup scripts prioritize existing UUIDs from the configuration file to maintain environmental consistency:
# openMRS-main/setup_medical_documentation_concepts.py:355-364
wanted_uuid = (desired_uuids.get("concepts") or {}).get(concept_name) or \
(desired_uuids.get("codedAnswers") or {}).get(concept_name)
if wanted_uuid:
concept_data["uuid"] = wanted_uuid
# API request
response = requests.post(url, json=concept_data, auth=(...) )
Sources: openMRS-main/setup_medical_documentation_concepts.py:355-364
Metadata Deployment Methods
While the primary method is via Python automation, the system also supports the OpenMRS Initializer module. This allows metadata to be deployed via CSV files located in the configuration/ directory of the OpenMRS app data folder. Sources: deployment/openmrs-initializer/README.md:1-20
Key files for Initializer deployment include:
concepts-ehr.csvencountertypes-ehr.csvpersonattributetypes-ehr.csv
The system provides a utility to regenerate these CSVs from the existing Python-defined UUIDs to ensure both deployment methods remain synchronized. Sources: deployment/openmrs-initializer/README.md:22-26
Summary
The OpenMRS Metadata Configuration provides the structural foundation for the entire EHR system. By using deterministic UUIDs and idempotent automation scripts, it eliminates the risks associated with manual database configuration. This centralized management ensures that AI extraction services and frontend clinical forms can reliably interact with medical data across diverse hospital deployments. Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:144-150, README.md:222-226