ConceptMap is a FHIR resource that allows you to establish a one-way map between codes. We'll use latter as an example in this tutorial to demonstrate how two concepts can be related (mapped) to each other and how their equivalence (or lack of) can be specified.
ContentsStep 1: About ConceptMap Step 2: Sample data mapping Step 3: Sample resources Step 4: Advanced features Step 5: $translate operation
Step 1: About ConceptMap
Metadata describes general information about the mapping - who made it, what version it is, copyright...etc.
Source is a reference to the ValueSet that you are mapping from. Remember that ConceptMap is a one-way mapping so there's always a clear source and a target.
Target is similar to source - it is a reference to the ValueSet you are mapping to.
Mappings are the translations themselves, organised in groups. Each mapping (called an 'element' in the data) can have one or more target elements, which specify a connection between a code from one ValueSet to code(s) in another ValueSet. The type/strength of connection is described by the equivalence property. The equivalence expresses that the two elements are exactly the same, wider than, narrower than or the two concepts aren't related at all. The full list of equivalence values is available in the ConceptMap Equivalence ValueSet.
Step 2: Sample data mapping
As an example, let's say you have a (very poorly designed) ValueSet based on a CodeSystem representing employee presence at work with just three codes: present, not-present, and sick which is in use by your system. You start importing data from a new system which has finer granularity:
|Current valueset||New system's valueset|
Your task is to create a FHIR ConceptMap translating the codes your receive to codes you already have, making use of the available equivalence values. You come up with this sample mapping that maps in the direction from the new system to your system's ValueSet:
|New system's valueset||Current valueset||Equivalence code|
Step 3: Sample resources
Press the button below to upload these resources to the FHIR server!
The ConceptMap resource will be available at this URL:
Once uploaded, it'll look something like thiswhen you GET the ConceptMap via Postman.
Step 4: Advanced features
ConceptMap is actually pretty powerful, and besides the basic code-to-code mapping described above, it also supports the following usecases:
- Mapping one code to many codes at once given the same equivalence property (by utilising multiple target properties within one element property)
- Having a dependency for a mapping, a mapping could only be applicable if a selected element exists in the data and has the specified value (see dependsOn)
Step 5: $translate operation
The $translate operation allows you to utilise a FHIR terminology server to get an equivalent code as specified by a ConceptMap mapping. To use it, you need to provide the ConceptMap you'd like to use, the input code and its CodeSystem, and the valueset you'd like to get a translation from. Try the $translate operation on the four sample resources uploaded above (a CodeSystem, two ValueSets, and a ConceptMap) via Postman using this template:
Here's a sample code you could try, once you've uploaded your conceptmap to a terminology server of choice:
That's it! You're done for now.