Making a Transaction bundle using the Mapping Language

In the previous post we created a bundle of Patient resources for sending to a FHIR server. However, if you take a look at the Bundle generated by executing the transform, you’ll see that it has a type of ‘transaction’ but the entry elements only contain a ‘resource’ element (that contains the actual resource) – it’s missing the ‘request’ element that tells the server what to do with that resource, and so is not a valid transaction.

Let’s fix that.

Here’s what the map group that creates the entries currently looks like (It’s the first group in the map so will be invoked by the engine):

After setting the bundle id and type, it iterates over the ‘patient’ elements from the source file, pulling out the id element from the source and setting the whole patient element to a variable for use in the Patient resource. Next it creates an entry element in the Bundle for each patient, then creates a blank Patient resource (with id) which is set to the entry.resource element and finally populates the Patient resource via a call to the makePatient group.

What we need to do is to change it to this:

What we’ve done is that after creating the resource and setting its id we do a couple of extra things.

We set the entry.fullUrl property (line 13) using the evaluate function. This function is described as follows:

Execute the supplied FHIRPath expression and use the value returned by that. The 2nd parameter – FHIRPath expression – is evaluated in the context of the first parameter, and the result used as the value. In the concrete syntax, there is a short hand for this operation, by supplying () around the parameter. In this case, there is no context for the FHIRPath expression, and it must start with a reference to one of the defined variables

So basically, it takes the id that we created as the context (it will become the $this in the FHIRPath expression) and prepends it with the resource type (‘Patient/’). If you look at the result, you’ll see that the engine also adds the mapping engine path to make it an absolute rather than a relative path (I’m not sure if this is specific to this implementation or not)

Lines 14 and 15 create the entry.request element (as a Backbone datatype), sets the method to ‘PUT’ and sets the url to what the PUT API operation expects. Here’s what it looks like in the result bundle after execution:

You can see the entry.fullUrl and entry.request elements below the entry.resource element (quite legitimate in Json).

So now, we have a legitimate transaction bundle and we can send it to a FHIR server for processing – right? Absolutely! And there are a couple of ways that we can do that…

If you look at the upper right on the Results tab, you’ll see a link ‘Copy to clipboard’ link. Clicking that link copies the result bundle to the clipboard (surprisingly enough) so it’s straightforward to load your favourite REST client (like POSTMan), set it to POST to the server root, paste in the bundle and execute the query.

However, if this something that you’re going to do quite often, there’s an easier way. First, in the configuration for the app (click the gear icon in the navbar at the top of the screen) set the ‘target’ server to the one you want to send the bundle to – like this:

After you’ve done that, the sub tab labelled ‘Send to target server’ appears in the results tab (alongside the clipboard link). That tab will allow you to send the bundle to the target server, displaying the response from the server as shown in this screenshot:

This can be quite a time saver! Note also the ‘Validate’ link so you can check the bundle before sending it to the server – or for situations where you just want to validate the output and not send it to a server. Like the target server, you set this in the app configuration.

So now we can create a transaction bundle of Patient resources from an simple input, and send that to a FHIR server which will process it and save the Patient resources. But we’re assuming that the server allows the client to specify the patient id, and that we have an appropriate id in the input file. These are big assumptions that won’t always be true.

In the next post, we’ll consider a slightly more realistic scenario, where we have an identifier for the patient (like a Medical Records Number) rather than a resource id…

And to acknowledge the work of Vadim in this post (and the others) – I used his example from devdays quite extensively…