FHIR transactions: the Search functionality

FHIR supports transactions by POSTing a bundle of resources to the root of a server. The server processes them separately as if they had been sent as individual requests – except that the entire group of updates either succeeds or fails as a group (which is what a transaction is, after all…)

It’s one of the more complex processing that a server has to do – particularly as it needs to manage references between resources for new and existing resources within the bundle.

But there’s one particular aspect to this, and that is what if you don’t know if the resource already exists on the server?

For example, we’re working on a project to import glucose data from a personal device. Our current thinking is to create a bundle containing a Patient resource, a Device resource and Observation resources for each of the glucose results we want to save. (We’re probably not using the DeviceObservationReport as it doesn’t add anything extra for us in this scenario).

So when the client creates the bundle, what does it use for the Patient ID – and the Device ID for that matter? (The Observations will always be new, so cid: IDs are appropriate for them). We do have an identifier for both, but that’s not the same as the ID – and having to look up the resources before putting them in the bundle kind of defeats the purpose. And if we include the resource anyway with a cid: ID , then the server will always create a new one – not what we want.

The answer to this is a couple of paragraphs in the spec that talks about how a server can manage this. Here it is (it’s in the transaction description):

The application constructing a bundle may not be sure whether a particular resource will already exist at the time that the transaction is executed; this is typically the case with reference resources such as patient and provider. In this case, the bundle should contain a candidate resource with a cid: identifier, and an additional search parameter using an Atom link:

<link href="http://localhost/Patient?[parameters]" rel="search"/>

A search link with a root of http://localhost means to search the local resource store for a match as specified in the parameters (which must conform to the servers capability for searching as specified in its conformance statement). If the search returns no matches, the server process the resource normally. If the search returns one match, the server uses this matching resource instead, and ignores the submitted resource. If more than one resource is found, the transaction SHALL be rejected.

 This means that we can include the identifier of the Patient and the Device in the bundle, and the server will locate the resource if it exists – and create it if it does not.

So here’s a sample of a patient resource in a bundle:

    <title>Patient details</title>
    <link href="http://localhost/Patient?identifier=PRP1660" rel="search"/>
    <content type="text/xml">
        <Patient xmlns="http://hl7.org/fhir">
                <status value="generated"/>
                <div xmlns="http://www.w3.org/1999/xhtml">Joe Bloggs</div>
                <value value="PRP1660"/>
                <text value="Joe Bloggs"/>

Note the <link> element where we specify that the search parameter is an identifier with the value of PRP1660. (and, of course, we have this identifier in the candidate resource – otherwise it will never work!)

This is incredibly useful! In fact it does raise the issue of whether a server claiming to be able to process transactions in its conformance statement SHALL be able to implement this functionality. I don’t think the spec is clear on this – and probably needs to be.


FHIR resource browser

FHIR resource browser

A simple tool from Dan Gottlieb that browses FHIR resources…

He’s interested in feedback and comments – I’ll pass on any comments.

New Zealand FHIR Seminar

Yesterday we (HL7 New Zealand) gave a full day presentation on FHIR (and some related standards) to a local audience. We had over 40 people present – which is pretty good for a seminar on Informatics Standards in New Zealand!

And for those who did attend – thank you for giving up your time for this! I do hope you found it useful…

We had a couple of objectives in giving this presentation.

  • Firstly, to educate and raise awareness of the value of FHIR to healthcare Interoperability in New Zealand.
  • Secondly, we are planning some FHIR related sessions at our upcoming HINZ conference at the end of the year, and wanted to encourage people to participate.

I think we succeeded on both counts. The audience was engaged and we had a large number of questions (most of which I could answer <s>) – except towards the end when I was running out of time and had to talk fast! (note to self – must manage time better…). Oh, and thanks to Richard (Blaze server author) for helping when my brain went on hold…

Thinking now about the HINZ conference, what we’d like to do is to have real demonstrations from multiple vendors (and others) showing how FHIR can be used to facilitate access to healthcare information – similar to the example I gave at the seminar where Josh Mandel had organized a SMART demonstration at HIMSS this year.

We’re thinking of a ‘showcase’ of applications showing how FHIR can support an ecosystem of information exchange, and we’ll provide support to participants over the rest of the year in the lead-up.

We’re planning on establishing a set of sample services (Patient/Provider lookup, XDS style Document Registry, Document Store, Clinical data, Profile registry and the like, which will be supplied by the Orion Health Blaze server). This will have sample data in it, and we’ll encourage anyone – vendors and individuals – to write applications that use those services.

There will also be a number of existing systems that have shareable data who could expose that as FHIR services – and we’ll be reaching out to them to participate as well.

The idea is to show those holding the purse strings both how FHIR can facilitate interoperability with orders of magnitude less effort than the current alternatives – and also how vendors can work together to achieve that interoperability (which is something that we did when working on the GP2GP project).

And as the purpose is to show functionality, we won’t concern ourselves with security for the moment. All going well, that will be something that we can look at more seriously when we deploy real applications next year.  FHIR does have recommendations for security, but implementing it does raise the bar for participation considerably, so that can be the next step.

I may be overly optimistic – but, nothing ventured…

Talking to people between the presentations, there are a few vendors who are interested in participating, which is great – and we’ve got the rest of the year to recruit others!

So, any New Zealanders (or overseas readers for that matter) who are interested in participating – just click on the ‘Contact’ button at the top of the blog and send me a message. We’re looking for anyone interested – client or server, desktop or mobile, and any scenario that has value to clinicians or patients.

As promised, I’ve uploaded the presentations to slideshare, and the links follow. And, although mentioned in the presentations, I’d like to acknowledge and thank Lloyd, Ewout and Grahame as many of the slides were adapted from presentations they have made.

Again – to those who did come along – thank you for your support!

I had intended to provide links to slideshare rather than embedding content – but can’t seem to get that to work. (If anyone does know how, then let me know!). The list of presentations is:

  • Introduction to FHIR (David hay)
  • FHIR for architects and developers (David hay)
  • Archetypes and FHIR (Koray Atalag)
  • Please don’t spell SNOMED with a w (Alastair Kenworthy)
  • Possible uses for FHIR in New Zealand (Peter Jordan)

If you do want to download a presentation then click the ‘share’ icon in the top right hand corner of the presentation. The link is shown in the dialog that is presented. Copy and paste it into a browser which will show the presentation in slideshare. You can download it from there.

Sorry about that…

Introduction to FHIR (David hay)

FHIR for architects and developers (David hay)

Archetypes and FHIR (Koray Atalag)

Please don’t spell SNOMED with a w (Alastair Kenworthy)

Possible uses for FHIR in New Zealand (Peter Jordan)



A presentation from Ewout about using FHIR to represent DICOM references (Like Ewout – I don’t know a lot about DICOM – though he knows more than me now!)

I especially like how it shows FHIR working with other SDOs…

Thanks to Rene for sending the tweet through (Oh – and theres another link on his blog about DICOM) …