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.

Learn more:

General Options

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.

Code Libraries

The following code libraries implement a transform engine based on the FHIR Mapping Language:

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).

Web Services

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 AuthoringPhase 2: Mapping Execution
  1. Define mapping instructions to transform the source content to the target content.
  2. Use the mapping engine to create a machine-readable representation of the mapping instructions ($convert) in the form of a FHIR StructureMap resource.
  1. Store the source FHIR StructureMap resource on the FHIR Server.
  2. Execute transformations - $transform - The mapping engine requires:
    1. The source content to transform.
    2. The machine-readable representation of the mapping instructions previously created.
  3. Store the generated target content (optional)

These two phases are illustrated in the FHIR Mapping Language Workflow below.

Publicly available test servers:

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).
  • Grahame Grieve - FHIR Mapping Language | DevDays 2018 Boston video slides
  • clinFHIR Mapping Language designer 

Other Tools

.. todo

https://confluence.hl7.org/display/FHIR/FHIR+Tooling+Ecosystem#FHIRToolingEcosystem-ConversionTooling

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://github.com/hapifhir/org.hl7.fhir.core/releases/latest/download/validator_cli.jar

Notes:

  • You need a current version of Java installed to run the validator.
    • Windows: 64bit Java is preferred - 32bit has not quite enough memory.

Execute a Transform

 java -jar validator_cli.jar [source] -output [file] -transform [map] -version [ver] -ig [package|file|url] -tx [url]

Parameters:

  • 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.  Note - a filename can reference a FHIR Mapping Language file, not just a StructureMap instance.
  • -tx: the terminology server to use (optional, single - defaults to http://test.fhir.org).

Compile a Transform

To turn a FHIR Mapping Language file into a StructureMap resource, invoke the validator as follows:

 java -jar validator_cli.jar  -ig [file] -compile [map] -version [ver] -output [file]

Parameters:

  • -ig: in this case, the ig parameter must be a reference to text file containing the FHIR Mapping Language content to convert. (required, single).
  • -compile: the url of the structure map to process (required, single).
    • Note that this must be the URL of the FHIR Mapping language file passed as an input.
  • -version: the FHIR version for the StructureMap to produce (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.
  • -output: the filename for the compiled StructureMap (required, single).

GUI Wrapper

There's a Convenient GUI interface for this in the FHIR toolkit:

  • No labels