A simple app to help using the Mapping Language

So I’ve just been at the FHIR devdays in Amsterdam which was really interesting (of course – attending a devdays is a ‘must do if possible’ for FHIR implementers). One of the presentations I attended was on the FHIR mapping language – more specifically an implementation of the FHIR mapping language by Firely and Healex   (currently in a ‘technical preview’ state).

I’ve always been interested in the mapping language, and its ability to create portable mapping files – allowing specialists to create the mapping instructions, which can then be used by any compliant engine, as the following image illustrates:

Note that there is no requirement that either input or output should be FHIR resources (though they commonly will be). Note also that I’m using the term ’message’ to indicate the input and output – not a Message in the FHIR sense

So, there’s 2 main steps to setting this up:

• Create the Mapping instructions and associated artefacts
• Execute the transform using those instructions

There’s a reference implementation available from the FHIR community which you can download and use, but I’ve had difficulty using it, as it is a command line tool with a number of switches that I’ve found it complex to set up and use.

What the firely folk have done though is to move all that complexity behind a couple of FHIR operations, meaning that you don’t need a local setup – which is super cool! And they’ve created documentation and samples that is always useful when you’re starting out…

This approach nicely ties in with the idea of ‘server types’ that I use in clinFHIR, and I think reflects an ecosystem approach. Currently we have:

• The Data server – where actual information is stored
• The Conformance server that holds conformance resources like profiles and extension definitions
• The Terminology server that has terminology resources (eg ValueSets, CodeSystems) and terminology operations

And so now we have the Mapping server that can perform transformations using the mapping engine.

The firely approach uses 2 operations.

• StructureMap/$convert which takes in a text based mapping file (that contains the actual instructions and references to structure definitions that describe the inputs and outputs) and converts that to a StructureMap resource, which is the format that the mapping engine uses. You use a specific HTTP header to indicate the type of mapping that you want as $convert can be used for a number of purposes. The operation returns a StructureMap resource (if the conversion succeeds) which you subsequently save.
• StructureMap/{id}/$transform – which takes in the file to be transformed (eg a FHIR resource, ad-hoc json message or v2 message), executes the transform defined by the StructureMap resource instance and returns the result (which can be pretty much anything). All the dependant resources (StructureDefinitions, Terminology resources etc. must have copies on the mapping server).

Creating the StructureMap, and setting up the Mapping server to execute the transforms does involve a number of steps.

• Get a sample (or samples) of the input that we will use.
• Create a Logical Model (represented as a StructureDefinition resource) that describes the input structure. Save the model to the Mapping server.
• Decide what the output will look like. Commonly it will be a bundle of resources. For each resource in the bundle, ensure that the appropriate StructureDefinition is on the Mapping server. This may be a core resource type or a profiled type – or even a non-FHIR artefact.
• Create the mapping file (aka ‘map’). This will very likely be an iterative process of creating something, then executing a sample message against it to discover bugs and make enhancements. Use the $convert operation to create the StructureMap resource – which also validates that the map is syntactically correct.
• Ensure all terminology resources and StructureDefinitions needed by the map are on the Mapping server. For example, if there are terminology conversions you’ll need the ConceptMap and associated ValueSets / CodeSystems.

Once the map is created and converted, sample data can be executed against it.

To make this process a bit easier, I’ve created a simple application that allows the maps and samples to be edited in a browser, then converted and executed against the mapping server. You can select the servers to use – though currently only Vonk supports the required operations.

Note that this is a sandbox – there is no guarantee of availability, nor that the maps you create will be saved indefinitely – in fact it’s almost certain that it will be cleared from time to time. There’s a download / upload built into the tool – make sure you use it for anything you want to save! (e.g. when you show off your work to a colleague…). For the same reason, don’t use real data. Planning on simplifier integration as well…

The application can be accessed here, and there’s more detailed documentation here.

Here’s an example of the main UI, showing a sample file to the left and the map to the right.

and here’s the output – in this case represented as a graph of resources, though there are other views available, as well as validation and FHIRPath (using the excellent javascript library). You can also send the output directly to a FHIR server if you wish to save the resources directly.

This is very much a work in progress (even over the holiday break 🙂 so there will be bugs!). If you do have a play and have issues / ideas then use the FHIR chat to discuss them.

I’ll write some follow up posts in the new year discussing some real maps, but in the meantime hope you all have a great break over the festive season!