Assigned to: Mikko Suniala

Mentor: Rafal Korytkowski


OpenMRS has a mechanism to map concepts to external sources (concept_map tables); however, OpenMRS does not yet have a means to map metadata to external sources. We have tried using UUIDs to uniquely (and globally) specify metadata across systems; however, this has failed us in several ways: (1) UUIDs end up needing to be manually entered by developers and implementers; (2) there are many cases where metadata created separately (with different UUIDs) are actually referring to the same thing; and, (3) modules introducing their own metadata have a difficult time properly working with existing metadata.


The goal of Metadata Mapping is to solve many of the problems around metadata management by providing an easy & explicit way for metadata within a system (encounter types, location, etc.) to be mapped to external vocubularies.

Use case examples:

A "1.0" version of Metadata Mapping would include a MetadataService within openmrs-core (could be introduced by a module initially or for the foreseeable future) and REST API endpoints to manage & search metadata mappings.


Data Model Design

The following design is based on the proposal of the Design Forum 2015-06-22:

Notes on data model design:

API Design

The common operations for metadata mapping will include these use cases:

API Call examples:

Fetch a location with the given source and code:
Location location = metadataService.getItem(Location.class, "SOME-SOURCE", "CODE");
// should be implemented as: generic <T> getItem(T type, String source, String code);
Fetch all visit types from the given source:
List<VisitType> visitTypes = metadataService.getItems(VisitType.class, "SOME-SOURCE");
// should be implemented as: generic <T> getItems(T type, String source);
Fetch all visit types for the given set:
List<VisitType> visitTypes = metadataSerivce
  .getItems(VisitType.class, "SOME-SOURCE", "CODE");
// should be implemented as: generic <T> getItems(T type, String source, String code); 
// source =, code = metadataSet.code
Retire term:
List<MetadataTermMapping> termMappings = metadataService.getMetadataTermMappings(location);
metadataService.retireMapping(termMappings.get(0), "some reason");
Create term: 
MetadataSource source = metadataService.getSourceByName("SOME-SOURCE");
MetadataTermMapping termMapping = new MetadataTermMapping(source, "CODE", location);
Create terms in bulk:
List<MetadataTermMapping> termMappings = Arrays.asList(mapping1, mapping2, mapping3);
Get term by source and code:
MetadataTermMapping termMapping = metadataService.getMetadataTermMapping(mappingSource, "CODE");
Get terms by source:
List<MetadataTermMapping> termMappings = metadataService.getMetadataTermMappings(source);
Get term by uuid:
MetadataTermMapping termMapping = metadataService.getMetadataTermMappingByUuid(String uuid);
Get source by uuid:
MetadataSource source = metadataService.getMetadataSourceByUuid(String uuid);
MetadataTermMapping, MetadataSource, MetadataSet should support all CRUD operations.