HL7 developed a FHIR Mapping Language to solve a requirement to map content from one structured source data format to a different one.
Use cases include:
- Map FHIR resource between different FHIR versions
- Map HL7 C-CDA CCD document sections to multiple FHIR resources
- Map HL7 V2 messages to multiple FHIR resources
- Map any structured data format to any other structured data format, including to multiple FHIR resources
The specification of the FHIR Mapping Language can be found here.
There are many ways to use the FHIR Mapping language. In general, the mapping language can be executed directly, or can be translated to some other language.
All transformations are executed by a mapping engine, which can be implemented using the options listed below.
Mapping Engine Implementations
Implement a mapping engine using one of the options listed below.
The following code libraries implement a transform engine based on the FHIR Mapping Language:
- Java: org.hl7.fhir.r4.utils.StructureMapUtilities (or service wrapper: [org.hl7.fhir.r4.validation.NativeHostServices]) (generally: org.hl7.fhir.rX.utils.StructureMapUtilities)
- C#: FHIR Mapper (closed-source)
- Pascal: FHIR.R4.MapUtilities (generally: rX/FHIR.RX.MapUtilities)
Command Line Tools
- The official Java FHIR validator can perform transforms using the FHIR Mapping Language (see below - Running Transforms via the Java Validator Jar).
FHIR servers can choose to implement special operations to execute a transformation using the FHIR Mapping Language. In general the workflow can be split into two phases:
|Phase 1: Mapping Authoring||Phase 2: Mapping Execution|
These two phases are illustrated in the FHIR Mapping Language Workflow below.
Publicly available test servers:
- C# FHIR Mapper: https://vonk.fire.ly
- Java FHIR Mapping: http://test.ahdis.ch/r4/StructureMap/$transform
Available Online Tutorials About the FHIR Mapping Language
- The official tutorial is covered as part of the FHIR specification.
- Example StructureDefinition and StructureMaps for the tutorial mentioned above can be found here and shows how to use it with the Java Validator or server based (work in progress).
- A tutorial on how to map a FHIR LogicalModel to FHIR is provided by Firely.
- Grahame Grieve - FHIR Mapping Language | DevDays 2018 Boston video slides
- clinFHIR Mapping Language designer
Run Transforms via the Java Validator Jar
The validator includes all the code to execute the transforms; there is no need to create and maintain a separate jar.
Download the Validator
Download the validator from: https://storage.googleapis.com/ig-build/org.hl7.fhir.validator.jar
- The instructions below assume that the validator jar is named org.hl7.fhir.validator.jar but the actual downloaded jar has a name like org.hl7.fhir.validation.cli-[ver]-[date].[time]-[id]-standalone.jar.
- Either rename the jar after downloading it, or replace the file name in commands.
- You need a current version of Java installed to run the validator.
- Windows: 64bit Java is preferred - 32bit has not quite enough memory.
Execute with a Transform
java -jar org.hl7.fhir.validator.jar [source] -output [file] -transform [map] -version [ver] -ig [package|file|url] -tx [url]
- source: A filename or URL for the content to transform (this isn't a named parameter like all the rest of the parameters).
- -output: the filename for generated output (required, single).
- -transform: the url of the structure map to execute (required, single).
- Note that this is a reference to one of the loaded StructureMap resources (see the -ig parameter) - the StructureMap will not be loaded explicitly.
- -version: the FHIR version in use (optional, single - defaults to the current version).
- Use a full version, or just the major.minor, e.g. 1.0.2, or 1.0 (3.0, 4.0). note: although this is optional, it's a good idea to always specify this.
- -ig: a source to load profiles, value sets, concept maps, and structure maps (etc) from (required, repeating, always need at least one).
- This can either be a package id, a canonical URL, a filename, a local directory, or a URL.
- -tx: the terminology server to use (optional, single - defaults to http://test.fhir.org).
There's a Convenient GUI interface for this in the FHIR toolkit:
- Download the FHIR Toolkit from http://www.healthintersections.com.au/FhirServer.
- Run it, and choose "Transformation" from the bottom of the home page.
- Choose the packages, source and output, and then specify the url of the StructureMap to run.
- Click "Transform".