Wiki Spaces


Get Help from Others

Q&A: Ask OpenMRS
Discussion: OpenMRS Talk
Real-Time: IRC Chat | Slack


Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

OpenMRS does not want to be a vocabulary standard. There is a lot of up-keep involved with managing universal codes used around the world. Instead, every openmrs installation is free to add new concepts, change concepts, etc in their local installation. That installation's concepts will get concept_ids assigned by the database and are probably unique to that installation.

A concept can have any number of mappings to any number of other vocabularies. Other vocabularies are called "concept sources" in openmrs (these would be like LOINC, SNOMED, ICD-9, ICD10, etc). Every concept can define a string for its mapping in any "concept source" defined in the database.

Openmrs ships with some demo data which includes concepts. It is optional to use this set of concepts. These concepts do not come with any mappings defined to any terminology.

Creating a new Concept Source

  1. Go to the Administration screen
  2. Click "Manage Concept Sources"
  3. Click "Add new Concept Source"
  4. Fill in the specific details.

Creating the Mapping in OpenMRS version 1.8 and earlier

  1. Go to the Concept Dictionary
  2. Go to the edit screen of the concept you want
  3. Scroll down to the "Mappings"
  4. Click "Add Mapping"
  5. Enter the SNOMED code and then choose SNOMED as the source
  6. Click "Save" to save the concept

Creating the Mapping in OpenMRS version 1.9 and later

The way concept mapping was done in versions prior to 1.9 was fairly low-key and didn't allow for looser mapping to other terminologies. The implementation almost assumed a 1 to 1.  (Or a "this is that").  In the real world the mapping is less exact.  We needed to support extra attributes on the concept map to address this. We also needed to specify the relationship between two mapped terms.  We had no way to do that in openmrs prior to 1.9. Below is how you can add new concept mappings.

  1. Go to the Admin page, click 'Manage Reference Terms' under the concepts sections, this takes you to the reference term index page, click 'Add New Reference Term'
  2. Enter the required fields and click save, it is recommended to provide the name for the term.
  3. Go to the Concept Dictionary
  4. Go to the edit screen of the concept you want
  5. Scroll down to the "Mappings"
  6. Click "Add Mapping"
  7. Select a relation or map type (see below for how to manage relationship types), select a concept source, type a value into the code fields, you should be able to see suggested terms including the one you created in step 2 above, select it.
  8. Click "Save" to save the concept

Managing Relationship Types for concept and reference term maps in OpenMRS version 1.9 and later

OpenMRS ships with a set of predefined concept map types that will meet an implementation's needs but in the event where you can't seem to find the appropriate one, you can define new relationship/map types that can be used when mapping concepts to other terminologies or when mapping reference terms to each other, Some of the map types come when they are hidden/disabled, you need to make them active before using them. You can view the complete listing of all the concept map types by going to the admin page and click the 'Manage Concept Map Types' link under the concepts section, this feature is disabled by default so if you can't find the link, you will need to enable concept map type management by setting the value of the global property 'concept_map_type_management.enable' to true. Below  is how you can define new concept map types.

  1. Go to the Admin age, click 'Manage Concept Map Types' under the concepts section, this takes you to the map type listings page, click 'Add New Concept Map Type'
  2. Enter the name and description and click save.

You can active/deactivate a concept map type for use by selecting it from the concept map type listing page to be able to edit it. From the concept map type edit form, check the 'Is Hidden' checkbox and then save.

Receiving HL7 Messages

As of version 1.5, openmrs can receive hl7 ORUR01 messages with mapping codes instead of just internal concept_ids. The hl7_code for the concept_source simply has to be in the hl7 part and the code can be the mapping:

398439443293^WEIGHT (KG)^SNOMED

(Assumes the weight concept has a mapping of "398439443293" to the Snomed "concept source" and that source has the hl7 code of "SNOMED")

Technical Usage

Table Definitions:

To add a concept mapping to a concept using the API:

ConceptSource snomedSource = Context.getConceptService().getConceptSourceByName("SnoMed Source");
ConceptMap mapping = new ConceptMap();
Concept weightConcept = Context.getConceptService().getConcept(5089);

To get a concept by its mapping using the API:

ConceptService service = Context.getConceptService();
Concept c = service.getConceptByMapping("398439443293", "SnoMed Source");


The openmrs concept collaborative uses the mapping tables to facilitate openmrs installations to share data by mapping to each other's concepts. In this case, you would have a concept source named "PIH's Concepts" and then add mappings there.

  • No labels