Converting v2 to FHIR

At the recent Working Group Meeting in Montreal, I participated in the ‘v2 to FHIR’ stream – focused on how can the HL7 community give advice to implementers about converting v2 messages into FHIR bundles.

Broadly there are 2 approaches to this conversion:

  • The creation of a FHIR message bundle that mirrors the contents of the v2 message, and is intended to be an equivalent representation, behaving in the same way as v2 messages
  • Using the contents of the v2 message to update a FHIR server – perhaps extracting Encounter resources or creating a Bundle that is intended to act as a ‘transaction’ bundle against a FHIR server. I think this will be a much more common use case.

In either case, it’s desirable that HL7 should provide the mappings (insofar as that is possible in v2) from v2 to FHIR.

The decision made by the stream was to document these mappings using a highly structured spreadsheet – the idea being that data could be extracted from the spreadsheet and manipulated algorithmically – whether as the basis of direct conversion routines, or converted into ‘intermediate’ resources (StructureMap, StructureDefinition, ConceptMap) and processed by engines. At some point there may be specific tooling to maintain these mappings – but right now the spreadsheet approach seems the simplest to start with.

Most of the time was spent considering what the structure of this spreadsheet would be – the actual work of populating this will be on-going…

I did a couple of extra things over the weekend (and before):

  • I created a simple conversion function using Node-RED (and simple Javascript functions) that produced FHIR transaction bundles suitable for updating a FHIR server. It’s very simple at this stage, and really intended more as a proof of concept.
  • More interestingly (to me at least) I created a simple UI that takes in a v2 message, sends it to a transformation engine via a RESTful interface and then has a number of ways of displaying/validating the returned bundle. I see that this could be a useful tool in testing out both the mappings and the function of transformation engines – especially if we can agree on a defined operation for this (Keith Boone proposed this, though we didn’t have time to discuss this in detail).

In this post I’ll give more detail about that UI. Treat this very much as a ‘Work in Progress’ – as with all things clinFHIR 🙂

It can be accessed at When you access that url, you’ll get this interface:

1. Start

To the left is a list of known sample messages (right now it’s a fixed list – I’ll be hooking it up to the git-hub repository of sample messages that the community is maintaining before too long)

In the middle is a textual representation of the selected v2 message (I’ve added a space between segments for clarity). The tool does assume that there are line-feeds at the end of each line.

Selecting one of the segments displays the individual fields on the right side (only those fields that have data in them). Hovering over a field will display a popup with the individual components displayed separately.

It’s also possible to directly paste in a v2 message – click the ‘Paste v2’ link to the upper left to do this. It will display a dialog into which the v2 message can be posted.

To actually process (convert to FHIR) a message, click the ‘Convert’ button to the upper right. This will send the v2 message (via an HTTP POST) to the selected conversion engine, and display the resulting bundle as shown here:

2. json bundle

The conversion engine can be selected using a dropdown in the navbar. Currently, the only one that works is my (very simple) Node-RED engine, but I’m hopeful that vendors will make their engines available (even if incomplete) so that we can have a variety to choose from – and maybe compare the outputs (remembering that the whole purpose of this is to advance the mapping definitions – not to criticize or advertise specific vendor implementations. (What happens in vegas…). Please contact me if you have an engine you’d like to include – all it needs to do is to expose an HTTP POST that accepts the message, and return a FHIR Bundle in Json format (XML is not supported at this time).

There are a number of Bundle visualizations available. The one shown above is a straight dump of the Json that was received back. For example, as you can see in this case I’m using a ‘conditional create’ on the Patient. (So it’s the ‘send to FHIR Server’ type of conversion)

Another visualization lists the entries in the bundle, and allows you to select one to view the entry details. In the example below the patient has been selected – as you can see the identifier system is undefined – a bug in the engine!

3. list

Selecting the Graph tab shows how the resources are inter-related (the resource references). The tool uses the ‘fullUrl’ property in the bundle to work this out – not the resource id. The number that appears alongside the resource type is the number of validation errors – more on that in a moment. The example below is a very simple graph – much more complex ones are expected! Selecting a resource will display the corresponding entry.

4. graph

The final thing that the tool does is to perform a validation on the returned Bundle. It simply calls the $validate operation on a Bundle endpoint (currently the HAPI R4 server) and displays the resulting errors and warnings. The screen shot below shows an example. Selecting an error/issue displays the corresponding entry.

5. errors

I think this validation in particular is going to be very helpful in getting transforms working. There are limitations of course – but the validation is getting better and better as time goes on.

The final tab lists the mappings currently described in the spec, for all the resource types that were in the bundle. Once we get the mapping spreadsheets under way, I’ll be able to display those as well…

So there you have it. Feel free to have a play and let me know what you think (the clinfhir chat stream is probably the best channel to use – or the v2 to FHIR channel). As I said above, it’s under active development so the UI will likely change significantly – but hopefully will still remain simple to use!

And – if you are building a processing engine and want it included as a potential engine, drop me a line…




About David Hay
I'm an independent contractor working with a number of Organizations in the health IT space. I'm an HL7 Fellow, Chair Emeritus of HL7 New Zealand and a co-chair of the FHIR Management Group. I have a keen interest in health IT, especially health interoperability with HL7 and the FHIR standard. I'm the author of a FHIR training and design tool - clinFHIR - which is sponsored by InterSystems Ltd.

6 Responses to Converting v2 to FHIR

  1. xiao says:

    Hello David! Thanks for this article! I think it is great! And may I ask a silly question? Could you please tell me which tool can I use if I want to convert HL7 v2 to FHIR by myself. I really want to have a try by myself. Thanks for the help.

    • David Hay says:

      Hi Xiao – thanks for that 🙂

      Conversion between v2 & FHIR is something that the community is working on – there’s a chat stream here: where you can get engaged. The mapping between the 2 standards will take some work to define, and there will be variances in implementations but the goal of the project is to define a ‘base’ mapping as a starting point. The relationship between v2 and FHIR is reasonably close, but there are considerable issues to work through…

      There’s no single way to actually perform the conversion – it will depend on the technology you have to hand. For example in the post I was using simple javascript in NodeRED – though just as a proof of concept. I imagine that most integration engine vendors will have offerings in this space.

      hope that helps…

  2. Pingback: FHIR Bundle Visualizer | Hay on FHIR

  3. Hi David, thank you for the help. I tried to paste a sample of HL7 v2 message and clicked the convert button. I keep getting this error message: “There was an error with processing the message:null”. Am I missing anything here?

    • David Hay says:

      My apologies, this was written for a connectathon several years ago and I haven’t maintained it. I’ suggest the v2tofhir stream on the FHIR chat for assistance with v2 conversion. Sorry about that…

Leave a Reply

%d bloggers like this: