/
Metadata Export

Metadata Export

1. Problem

 Setting up a new OpenMRS instance today requires painstaking manual reconfiguration. When a deployment team has a fully working, configured OpenMRS site and needs to replicate it .for a new clinic, a staging environment, or disaster recovery there is no clean, automated path to do so.

The OpenMRS Initializer (Iniz) module allows teams to load configuration into OpenMRS via structured CSV files. However, the reverse process does not exist: there is no tool to extract the existing configuration out of a live OpenMRS instance in a reusable format.

2. User Stories

  • As a deployment engineer, I want to export the configuration of a live OpenMRS instance so that I can replicate it on a new instance without manual reconfiguration.

  • As a system administrator, I want to generate Iniz-compatible CSV files from an existing OpenMRS setup so that I can use them as a baseline for staging or disaster recovery environments.

  • As an OpenMRS implementer, I want to extract metadata from a reference site so that I can bootstrap new clinic deployments consistently.

 

3. Market Analysis

Current State

The OpenMRS Initializer module (Iniz) is the standard mechanism for loading structured configuration into OpenMRS via CSV files. It is widely adopted across OpenMRS deployments. However, it only solves the loading side there is no corresponding tool for the extraction side.

Gap

No existing OpenMRS module or tool supports automated, structured export of instance configuration into Iniz-compatible CSV format. Teams currently rely on manual documentation, direct database queries, or ad-hoc scripts. none of which are standardized or reusable.

Who Benefits

  • Deployment teams managing multiple OpenMRS sites

  • Teams performing disaster recovery or instance migrations

  • OpenMRS implementers onboarding new clinics at scale

Value Delivered

This tool directly reduces the time and risk involved in OpenMRS rollouts by making configuration portable, reproducible, and compatible with the existing Iniz ecosystem.

 

4. Technical Considerations & Dependencies

Technology Stack

  • Java (aligned with OpenMRS core and the Iniz module)

  • Maven for build management

  • OpenMRS service layer / REST APIs for reading configuration data

Approach
The tool reverses the Iniz loading process. Instead of reading CSVs into OpenMRS, it queries a live OpenMRS instance and writes structured CSVs out one per domain in a format directly consumable by the Initializer module.

Currently supported domains:

  • Concepts (names, descriptions, class/datatype/version, numeric, complex, answers, mappings, attributes)

  • Concept sources (name, description, HL7 code, unique ID)

  • Encounter types (name, description, view/edit privileges)

  • Privileges (name, description)

  • Concept classes (name, description)

  • Roles (name, description, privileges)

  • Patient identifier types (name, description, required, format, format description, validator, location/uniqueness behavior)

  • Visit types (name, description)

  • Relationship types (name, description, a_is_to_b, b_is_to_a, preferred, weight)

  • Attribute types (name, description, Min occurs, Max occurs, Datatype classname, Datatype config, Preferred handler classname, Handler config)

  • Global properties (property, value) — written as XML, since Initializer loads this domain from XML rather than CSV

  • Encounter Roles (name, description)

  • Person Attribute Types (name, description, searchable, format, foreign uuid, edit privilege)

  • Location Tags (name, description)

  • Locations (name, description, parent location, tags, address fields) — parent locations and tags are pulled in via cross-domain closure

  • Drugs (name, description, strength, concept drug, concept dosage form, ingredients, mappings) — drug/dosage-form/ingredient concepts are pulled in via cross-domain closure

  • Order types (name, description, java class name, parent, concept classes) — parent order types and concept classes are pulled in via cross-domain closure

  • Flags (name, criteria, evaluator, message, priority, enabled, tags, description)

  • Order frequencies (frequency per day, concept frequency) — the referenced concept is pulled in via cross domain closure

  • Programs (program concept, outcomes concept) — the referenced concepts are pulled in via cross domain closure

  • Program workflows (program, workflow concept) — the referenced program and concept are pulled in via cross-domain closure

  • Concept reference ranges (concept numeric, absolute/critical/normal low and high, criteria) — the referenced concept numeric is pulled in via cross domain closure

  • Concept sets (parent concept, member concept, member type, sort weight) — the referenced parent and member concepts are pulled in via cross domain closure

  • Program workflow states (workflow, state concept, initial, terminal) — the referenced workflow and state concept are pulled in via cross domain closure

  • Procedure types (name, description) — requires the emrapi module (3.4+)

 

Domains contributed by other modules (supportable, but depend on the module being present; not yet covered):

  • Metadata sharing / mapping (metadatasharing, metadata sets, metadata set members, metadata term mappings)

  • Identifier generation (idgen, auto-generation options)

  • Address hierarchy (address hierarchy entries, location tag maps)

  • Forms (Bahmni forms, AMPATH forms, AMPATH form translations, HTML forms)

  • Billing / cashier (billable services, payment modes, cash points, cashier item prices)

  • Appointment scheduling (specialities, service definitions, service types)

  • Queues

  • Cohorts (cohort types, cohort attribute types)

  • FHIR (FHIR concept sources, FHIR patient identifier systems)

  • Data filter mappings

  • Dispositions

  • OCL

Non-exportable Initializer domains (Liquibase, JSON key-values, system tasks) are out of scope.

Key Dependencies

  • OpenMRS Core (service layer access)

  • OpenMRS Initializer (Iniz) module: CSV format specifications per domain

  • Local or remote OpenMRS instance for testing extraction

Considerations

  • CSV output must strictly conform to Iniz domain specifications to ensure compatibility

  • The tool must handle large concept dictionaries and deeply nested configurations gracefully

  • Design should be extensible so additional domains can be added in future iterations

 

Engineering Notes