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 (ie. LOINC, SNOMED, ICD-9, ICD10, RxNORM, etc), but the concept source can also be a custom (ie. org.openmrs.module.mdrtb, PIH, AMPATH, MVP, etc.). Every concept can define a string for its mapping in any "concept source" defined in the database.

Some concepts are included with the installation demo data.   It is not necessary 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.

Managing concept mappings 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

Managing reference terms in OpenMRS version 1.9 and later

To Create a new term:

1. Go to the admin page
2. Click 'Manage Reference Terms' , you are taken to the reference term index page
3. Click 'Add New Reference Term'
4. Enter the required fields(Code and Source), it highly recommended to enter the name too.
5. Click save

To edit an existing term:

1. Go to the admin page
2. Click 'Manage Reference Terms'
3. Enter the first 3 characters of the term's code or name, if there are any search results, select the term that you wish to edit
4. Edit the fields you wish to change and click save

To retire a term:

1. Go to the admin page
2. Click 'Manage Reference Terms'
3. Enter the first 3 characters of the term's code or name, if there are any search results, select the term that you wish to retire
4. Click the 'retire' button at the bottom of the form, a pop up dialog is displayed, enter the reason for retiring the term and then click retire

To restore a term:

1. Go to the admin page
2. Click 'Manage Reference Terms'
3. Make sure the 'Include Retired' is checked, enter the first 3 characters of the term's code or name, if there are any search results, select the term that you wish to restore
4. Click the 'restore' button near the top of the form.

To delete a term:

1. Go to the admin page
2. Click 'Manage Reference Terms'
3. Enter the first 3 characters of the term's code or name, if there are any search results, select the term that you wish to delete
4. Click the 'delete forever' button at the bottom of the form, a confirmation dialog is displayed, click the 'Yes' button

Managing concept mappings 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 (If the term you wish to use for the mapping already exists, skip steps 1 and 2).

1. If the term doesn't exist otherwise , 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

To remove a concept mapping, just click the remove button on the right of the mapping you wish to remove.

Note: Super users and those with the 'Create Reference Terms While Editing Concepts' privilege can create new reference terms on the fly from the concept form.

Managing reference term mappings in OpenMRS version 1.9 and later

See above for how to create new reference terms in case the term you wish to use for the mapping is none existent.

1. Go to the admin page
2. Click 'Manage Reference Terms'
3. Enter the first 3 characters of the term's code or name, if there are any search results, select the term that you wish edit
4. Click 'Add Mapping'
5. Select a relationship type, select a source, enter the first three letters of the code or name of the term you wish map to, select the term you wish to map from the results. Is you wish to add more repeat steps 4 and 5
6. Click save.

To remove a mapping, click the remove button on the right of the mapping you wish to remove.

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:

(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:

• Concept map
• Concept source

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

To get a concept by its mapping using the API:

OpenMRS Concept Collaborative (OCC)

The OpenMRS Concept Collaborative (OCC) 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.