Contained resources – MedicationStatement

Continuing our ‘mini-series’ on the SNapp event, one thing you may come across when consuming MedicationStatement resources are ‘Contained’ resources. We’ve talked about them before, but in the interest of having all the SNapp information in the same place let’s take a look at what they are.

Read more of this post

More about contained resources

So this is going to be a really short post.

There was a question on the Implementers chat about the ability for contained resources to reference each other (ie where there are multiple contained resources within the same parent.

Here’s the question (slightly paraphrased):

The FHIR spec states that Contained resources can’t contain other resource (understandable). But I thought I had seen references from those contained resources to other contained resources within the same parent. Is that valid?

eg: a Medication resource is contained within a MedicationStatemement resource. The Medication references other Medication and Substance resources, also contained within the MedicationStatemement.

Read more of this post

Responsibilities of a FHIR client

As we start to do more ‘real’ work implementing FHIR here at Orion Health, we wind up making a number of implementation decisions about the interfaces we develop, and these – of course – influence how clients will use the services we create. Naturally, we will use the Conformance resource to document these, but it got me thinking about the overall responsibilities of a FHIR client. Read more of this post

Thoughts about updating Registries

In New Zealand we are lucky enough to have had a national patient registry for some years which serves as a unique identifier of patients in New Zealand – the National Health Index or NHI. The Registry is an instance of an EMPI (Enterprise Master Patient Index) and currently  exposes a SOAP interface that can be accessed by clients across a protected network.

In order to make it available for more users we are working in a project to expose a FHIR API that will offer similar functionality to the existing SOAP one, be simpler to use, available across the public Internet and so accessible to a wider range of clients in support of the healthcare ecosystem. We’re also looking at similar work for Provider registries.

Read more of this post

Creating a resources model

This is the third post in a mini series on using the Logical modeler. In the first post we talked in generalities of models (admitting that this is very much a work in progress), and then we discussed the Information Model – a model that is used to capture clinical requirements for information exchange. Now, it’s time to think about how we can design real FHIR artifacts from the work so far.

Read more of this post

Supporting SNAPP: Accessing New Zealand Medicines Terminologies With FHIR Terminology Services

A guest post from Peter Jordan – author of the Patients First Terminology server that will be available for use at SNApp, and frequent HL7 FHIR Connectathon attender…

Take it away Peter…

As those developing healthcare applications for the local market are well aware, and overseas developers preparing for the ‘SNAPP’ event at the upcoming SNOMED conference in Wellington, are becoming aware, New Zealand has its own medicines terminology. Interacting with this terminology – broadly known at the NZ Universal List of Medicines (NZULM) – is one of the many challenges facing SNAPP participants.

Read more of this post

Where did that data come from?

This post grew out of a question from one of the Analysts at Orion Health. We’re in the process of embedding FHIR pretty deeply into our product stack – and part of that involves creating FHIR interfaces to our existing data repositories.

This particular repository takes data feeds from a number of sources – mostly in the form of v2 messages, but also including CCDA documents – and from them extracts clinical data of interest such as encounters, procedures, problems and so forth. Because of the varied source of the data, one of the data items in the existing output that is displayed to the user is where it come from – ie which facility and possibly which application. (As much as we’d like to get the clinician, this data is not generally available in v2 messages).

So they question they asked me was – ‘where does this stuff go in FHIR’?

Read more of this post

The FHIR questionnaire: part 2

In this post we’re going to take a closer look at the internals of the Questionnaire.

The Questionnaire resource has 2 main parts:

  • The ‘header’ part that describes the Questionnaire
  • The contents – questions and answers

The Questionnaire has a dual personality. If it only has questions then it is a template (and the status has options of draft, published and retired). If it has answers, then it is a form instance (and the status has options of in progress, completed and amended). It could be argued that this difference should be made explicit with a specific property – for the mean time we’ll refer to these personalities as a template or an instance/form.

In the header is:

  • Status was discussed in the previous post. It actually serves a couple of purposes:
    • It identifies whether the Questionnaire is a template or an instance of a form
    • It indicates the workflow state
  • Authored. This is the date that the Questionnaire was authored – specifically the actual version of this resource – ie the date is updated whenever a new version is created.
  • Subject. Who the instance refers to.
  • Author. The person who recorded the information in the instance. When the instance has been completed by different people (eg the nurse fills in the start of an assessment form and the doctor completes the rest), then different versions of the instance will have different authors, and the version history will tell who entered what into the instance.
  • Source. The person who actually supplied the information (who may not be the same as the subject). For example, a mother may be supplying information about her child. If the subject is supplying the information then this property is not needed. Similarly to the author, this could conceivably be different across versions.
  • Name. This is used particularly for templates, and is the equivalent of the name of a form in the paper world – e.g. ‘Pre-operative assessment’. (The spec talks about a pre-defined list of questions – but it means the same). Interestingly, there is no concept of a ‘version’ of the form (as opposed to the usual FHIR resource versioning). For example, suppose the ‘Pre operative assessment template’ is modified. You have a couple of options:
    • Just update the template (new FHIR version). You do need to be careful about backwards compatibility  if form instances refer to external entities for rendering.
    • Change the status of the original to ‘retired’, and create a new one with the same name (and identifier). It may make sense to have an extension to explicitly state the template version.
  • Identifier.  Also used for templates, this allows a template to be part of a business workflow – e.g. the template has the identifier of “POA-2013/15 revA” – or some such. Potentially you could the identifier.period to specify the date range over which the template was valid – so when you create  or retire the template, you set the identifier.period.start and identifier.period.end properties appropriately.
  • Encounter.  This is an optional reference to the encounter where the form was completed.

The actual content of the Questionnaire is contained in an element named ‘group’. There can only be one top level group in a Questionnaire and it is optional (A Questionnaire with no questions would seem to be a particularly useless beast, but you might want to create the template, and then later add the questions I guess). As an aside – I suspect that a better name for ‘group’ here might have been ‘content’ – and for clarity that is how we’re going to refer to it here.

The content can be quite complex, being a hierarchy of sections (which are represented by groups), questions within the groups and groups within the questions…

Lets start from the bottom by thinking about the Questions.

Each Question has the following properties.

  • Name. A CodeableConcept that contains the code for each question. For example, suppose the question is ‘How many babies have you had (Parity)’, then the code could be the snomed code 118212000
  • Text. The text of the question as shown to the user in the form
  • Answer[x]. The answer to the question – if there is a single answer that is not drawn from a value set (we’ll discuss this in a moment). There is a fixed set of datatypes you can use here, and it isn’t possible in the Questionnaire to dictate what datatype to use – however you could create a profile for this purpose if you needed to. (A possible enhancement to Questionnaire would be to allow this in the Questionnaire as well). The permissible datatypes are: String, Decimal, Integer, Date, dateTime and instant. Obviously, the answer element will only be present in a completed form, not in a template.
  • Options. This allows a question to specify a set of possible answers – as you would use in a ‘picklist’ or ‘autocomplete’ control on a form. The options element refers to a ValueSet resource – which is a very sophisticated resource with many different ways to define the set of answers (I should do a post on this resource some time).
  • Choice. This is the selection that the user made from the defined options. It’s possible to make more than one choice from the list of options.
  • Data[x]. This allows you to refer to a specific resource, or include an answer that is of a datatype not included in the the Answer[x] element.
    • If you are including an answer of a specific datatype – maybe a CodeableConcept –  then the element name will include the datatype – in this case dataCodeableConcept.
    • If you are referring to a resource, then the element name is dataResource, and the contents are the usual resource reference (reference and display)
  • Remarks. Comments that the author of the form wishes to include about the answer – perhaps they feel the answer is incomplete or inaccurate. It should not be used for the answer itself.
  • Group. Allow you to have ‘questions within questions’. For example, the main question could be ‘Are you a smoker’, and the ‘sub-questions’ are only relevant (and possibly only shown) when the answer is ‘yes’.

If you haven’t seen the format ‘ Answer[x]’  or ‘Data[x]’ before (i.e. the [x] bit), then what that means is that the element name includes the datatype. For example, if you used a string as the answer, then the element name is answerString; an instant would be answerInstant, and so on.

As you can see, there are a number of different ways of specifying the possible answers to a question. In fact there are 3, and they are mutually exclusive (you can only have 1 of them):

  • Answer[x] – when there is a single, simple answer
  • Choice – when you select one or more options from a set of possible answers (including a full terminology – or subset of a terminology)
  • Data[x] – when there is a different datatype or a FHIR resource that is the answer. (And this could be constructed from other data entered in the form, or a selected from an existing resource).

A question arises: If you construct a resource based on data entered through a Questionnaire, how can you record both the original data and the resource in the Questionnaire? As of now, I’m not sure what the answer is – presumably you could create a Provenance resource that links the two, though that seems overly complex. Another possibility would be to use the remarks property. Or perhaps an extension on the answer that references the resource is the way to go. I need to think a bit more about the use cases where this would apply.

Here’s an example of a simple form. It’s a pregnancy assessment with 2 questions; one will be a simple text answer and the other is a selection from a pre-defined list. To specify the list, we’ve included a ValueSet as a contained resource and expanded the options to include the name of each option so that they can easily be displayed to the user. (go check out the ValueSet in the spec if these terms are unfamiliar). If this particular set of options was used by multiple Questionnaires then it might make sense to save it as a separate ValueSet resource and reference it from the question rather than containing it.


<Questionnaire xmlns="http://hl7.org/fhir">
     <text>
         <status value="additional"/>
         <div xmlns="http://www.w3.org/1999/xhtml">
             <p>An example of a Questionnaire being used as a template</p>
             <p>Could Place the template HTML Here</p>
         </div>
     </text>
     <contained>
         <ValueSet id="vs1">
             <name value="Parity Options"></name>
             <description value="The list of possible responses for Parity"/>
             <status value="active"/>
             <compose>
                 <include>
                     <system value="http://snomed.info/sct"/>
                     <code value="127364007"/>
                     <code value="127365008"/>
                 </include>
             </compose>
             <expansion>
                 <timestamp value="2014-02-27T12:30:10Z"/>
                 <contains>
                     <system value="http://snomed.info/sct"/>
                     <code value="127364007"/>
                     <display value="Primagravida (First Pregnancy) "/>
                 </contains>
                 <contains>
                     <system value="http://snomed.info/sct"/>
                     <code value="127365008"/>
                     <display value="Second Pregnancy"/>
                 </contains>
             </expansion>
         </ValueSet>
     </contained>
     <status value="published"/>
     <authored value="2014-02-27"/>
     <name>
         <coding>
             <system value="http://orionhealth.com/fhir/questionnaire#templatecodes"/>
             <code value="pregAss"/>
             <display value="Pregnancy Assessment"></display>
         </coding>
     </name>
     <group>
         <name>
             <coding>
                 <system value="http://orionhealth.com/fhir/questionnaire#sectioncodes"/>
                 <code value="subj"/>
                 <display value="Subjective entries - what the patient says"/>
             </coding>
         </name>
         <header value="Subjective"/>
         <text value="Use this section to record the patient history"/>
         <group>
             <question>
                 <name>
                     <coding>
                         <system value="http://snomed.info/sct"/>
                         <code value="127364007"/>
                         <display value="Primagravida (First Pregnancy) "/>
                     </coding>
                 </name>
                 <text value="How many Pregnancies"/>

                 <choice>
                     <code value="53881005"/>
                     <display value="None"/>
                 </choice>
                 <options>
                     <reference value="#vs1"/>
                 </options>

             </question>
             <question>
                 <name>
                     <coding>
                         <system value="http://snomed.info/sct"/>
                         <code value="118212000"/>
                     </coding>
                 </name>
                 <text value="What is the Parity (Number of live births)"/>
                 <answerInteger value="0"/>

             </question>
         </group>
     </group>
 </Questionnaire>

As I was writing this post, there were a number of areas where I wondered if the Questionnaire could be modified to improve its usability (of course, it may simply be that I don’t fully understand the intentions behind it’s use – it’s one of the more complex resources). These are:

  • It would be nice to be able to be explicit about the version of a template. Eg – that this is the second revision of an assessment form. (This is different to the FHIR resource versioning)
  • Should there be an indicator – or a list – when a single form has had multiple authors or sources.
  • Should there be some explicit way of marking a Questionnaire if it is a template, or is inferring this from the status still be best way to go.
  • Should the top level ‘group’ be better named as  ‘content’
  • Allow a question to define the expected answer format (must use a profile at the moment)
  • Does the term ‘section’ make more sense than ‘groups’

This nicely leads me back to the connectathon. One of the key purposes of the FHIR connectathon – and the reason for choosing a theme – is to support implementers as they actually use these resources, and to feed back issues that arise during this  into the resource design process. I think that the Questionnaire is going to be one of the more commonly used resources, so it’s a good time to look at it in detail.

You really should be there!

We aren’t quite done with Questionnaire yet – next time we’ll take a closer look at the grouping structure, and the standard extensions.

Resource References, v2 Messages and Locations

There’s been an interesting conversation today on the Implementers chat about the various ways that one resource can reference another, and there are a number of possibilities! They are all variants of the Resource Reference so, lets’ take a quick look at that before we dive into the details.

The resource reference element has 2 properties:

  • The reference, which is a string
  • The display – also a string.

and both properties are optional.

Read more of this post

Modelling Encounters with FHIR

One of the tasks I’ve been given here at Orion is to look at our internal data stores, and see how we could create a FHIR based service layer that would allow external (and internal) consumers to interact with that store.

I started with the Encounter service, and things went pretty well – but I realized that if this was to make sense to other BA’s (Business Analysts) and Developers then I needed to draw the bigger picture – how the resources would relate to each other when representing an encounter – it’s not quite as simple as it might seem!

The biggest change in thinking is going to be thinking in terms of multiple resources. If we want to retrieve the details of a single encounter, then we’re not going to just call the service and get back a single object that represents the encounter and all the properties of that encounter – rather we’re going to get back an ‘object graph’ – a number of resources related to that encounter contained within an atom bundle.

The client could request that the server return the referenced resources by using the _include parameter to specify the resources that it would like to be included in the returned bundle. (It could also get back just the Encounter and then make separate calls for all the referenced resources – but that’s a bit klutzy, and there are other problems that we’ll talk about in a minute).

I’ve used the New Zealand situation for this discussion to demonstrate the process I used: the actual relationship of entities will be different in different realms of course (HL7 uses the term ‘realm’ to refer to different countries).

OrgLoc

So, from the diagram we can see that:

  • The hospital organization is part of a DHB (District Health Board)
  • A primary care centre is in the catchment area of a hospital (this needed an extension).
  • The hospital location has a number of ward locations
  • An encounter at a hospital refers to the hospital Organization as the service provider, and has relationships within a number of wards within that hospital. It also has relationships with the patient and one or more participants
  • A primary care encounter has exactly the same sort of relationships  – albeit with different resource instances. (Just for fun, I associated the Primary Care Clinician with the hospital encounter to show that the GP was also involved in the patients care while in hospital. This is not uncommon in New Zealand – or at least it was when I practiced medicine a few decades ago…)

So what does this look like on the wire?

Well the snippet below shows a hospital encounter, with the resources within a bundle and appropriate  references between resources for the (It’s not complete of course – in fact there’s just enough in there to allow it to validate).

<feed xmlns="http://www.w3.org/2005/Atom">
    <title>Encounter Resource with all related Resources as separate resources</title>
    <id>urn:uuid:500bee81-d973-4afe-b592-d39fe71e38</id>
    <updated>2013-05-28T22:12:21Z</updated>     <!-- Time the bundle was built -->
    <!-- Author is required by the Atom spec. FHIR doesn't use it-->
    <author>
        <name>Harold House Surgeon</name>
    </author>

    <entry>
        <title>Encounter Resource</title>
        <id>cid:encounter1</id>
        <updated>2013-05-28T22:12:21Z</updated>
        <content type="text/xml">
            <Encounter xmlns="http://hl7.org/fhir">
                <text>
                    <status value="additional"/>
                    <div xmlns="http://www.w3.org/1999/xhtml">An encounter at Ward 10 Middlemore hospital,
                    for John Cardinal from 1st to 3rd January 2014. Dr Marcus Welby attending.</div>
                </text>
                <status value="finished"/>
                <class value="inpatient"/>
                <subject>
                    <reference value="cid:patient"/>
                    <display value="John Cardinal"/>
                </subject>
                <participant>
                    <individual>
                        <reference value="cid:doctor"/>
                        <display value="Dr Marcus Welby"/>
                    </individual>
                </participant>
                <period>
                    <start value="2014-01-01"/>
                    <end value="2014-01-03"/>
                </period>
                <location>
                    <location>
                        <reference value="cid:ward"/>
                        <display value="Ward 10"/>
                    </location>
                    <period>
                        <start value="2014-01-01"/>
                        <end value="2014-01-03"/>
                    </period>
                </location>
                <serviceProvider>
                    <reference value="cid:hospital"/>
                </serviceProvider>
            </Encounter>
        </content>
    </entry>

    <entry>
        <title>Patient details</title>
        <id>cid:patient</id>
        <updated>2013-05-28T22:12:21Z</updated>

        <content type="text/xml">
            <Patient xmlns="http://hl7.org/fhir">
                <text>
                    <status value="additional"/>
                    <div xmlns="http://www.w3.org/1999/xhtml">John Cardinal</div>
                </text>
            </Patient>
        </content>
    </entry>

    <entry>
        <title>Hospital</title>
        <id>cid:hospital</id>
        <updated>2013-05-28T22:12:21Z</updated>

        <content type="text/xml">
            <Organization xmlns="http://hl7.org/fhir">
                <text>
                    <status value="additional"/>
                    <div xmlns="http://www.w3.org/1999/xhtml">Middlemore Hospital</div>
                </text>
            </Organization>
        </content>
    </entry>

    <entry>
        <title>Location (ward)</title>
        <id>cid:ward</id>
        <updated>2013-05-28T22:12:21Z</updated>

        <content type="text/xml">
            <Location xmlns="http://hl7.org/fhir">
                <text>
                    <status value="additional"/>
                    <div xmlns="http://www.w3.org/1999/xhtml">Ward 10</div>
                </text>
            </Location>
        </content>
    </entry>

    <entry>
        <title>Practitioner</title>
        <id>cid:doctor</id>
        <updated>2013-05-28T22:12:21Z</updated>

        <content type="text/xml">
            <Practitioner xmlns="http://hl7.org/fhir">
                <text>
                    <status value="additional"/>
                    <div xmlns="http://www.w3.org/1999/xhtml">Dr Marcus Welby</div>
                </text>
            </Practitioner>
        </content>
    </entry>

</feed>

The query that would retrieve this bundle looks something like this:

GET [root]/Encounter?subject={patientID}&_include=Encounter.subject&_include=Encounter.Location...

Now there’s actually an issue with this representation, and it relates to our old friend the resource identity.

In this bundle all the resources are identified as ‘cid:’ references – meaning that they don’t refer to ‘real’ resources back on the server. (Because our back end is not fully FHIR enabled (yet), we’ve constructed the resources ‘on the fly’ from the data in the Encounter when the query was processed).

But what should the recipient do with the bundle if it wanted to save it locally? It would need to create a new resource locally for each one in the bundle. What would happen if the client made 2 separate queries for encounters, and each encounter referred to the same patient? The client would have no way of knowing this, and so would create another resource for the same patient.

So the more correct way to deal with this is to ‘contain’ the unidentified resources within the Encounter like this:

<feed xmlns="http://www.w3.org/2005/Atom">
    <title>Encounter Resource with all related Resources as contained resources</title>
    <id>urn:uuid:500bee81-d973-4afe-b592-d39fe71e38</id>
    <updated>2013-05-28T22:12:21Z</updated>     <!-- Time the bundle was built -->
    <entry>
        <title>Encounter Resource</title>
        <id>cid:enc1</id>
        <updated>2013-05-28T22:12:21Z</updated>
        <content type="text/xml">
            <Encounter xmlns="http://hl7.org/fhir">
                <text>
                    <status value="generated"/>
                    <div xmlns="http://www.w3.org/1999/xhtml">An encounter at Ward 10 Middlemore hospital,
                        for John Cardinal from 1st to 3rd January 2014. Dr Marcus Welby attending.</div>
                </text>
                <contained>
                    <Patient id="patient">
                        <name>
                            <text value="John Cardinal"/>
                        </name>
                    </Patient>
                </contained>
                <contained>
                    <Practitioner id="doctor">
                        <name>
                            <text value="Dr Marcus Welby"/>
                        </name>
                    </Practitioner>
                </contained>
                <contained>
                    <Location id="ward">
                        <name value="Ward 10"/>
                    </Location>
                </contained>
                <contained>
                    <Organization id="hospital">
                        <name value="Middlemore Hospital"/>
                    </Organization>
                </contained>
                <status value="finished"/>
                <class value="inpatient"/>
                <subject>
                    <reference value="#patient"/>
                    <display value="John Cardinal"/>
                </subject>
                <participant>
                    <individual>
                        <reference value="#doctor"/>
                        <display value="Dr Marcus Welby"/>
                    </individual>
                </participant>
                <period>
                    <start value="2014-01-01"/>
                    <end value="2014-01-03"/>
                </period>
                <location>
                    <location>
                        <reference value="#ward"/>
                        <display value="Ward 10"/>
                    </location>
                    <period>
                        <start value="2014-01-01"/>
                        <end value="2014-01-03"/>
                    </period>
                </location>
                <serviceProvider>
                    <reference value="#hospital"/>
                    <display value="Middlemore Hospital"/>
                </serviceProvider>
            </Encounter>
        </content>
    </entry>

</feed>

This makes it explicit to the recipient that the contained resources only have meaning within the context of the containing Encounter. (And note that the contained resources no longer have a <text> element – the spec discourages this).

As we progress with FHIR, we’ll be able to start to expose ‘real’ resources (with proper identities). For example, once we have a Patient resource endpoint available, then we won’t have to contain the Patient resource in the Encounter – it will be an ‘identifiable’ resource with a ‘real’ URL that points to it – and we can choose to include the resource in the bundle or not. This does mean that the representation will change over time with resources moving from being contained to being ‘real’ resources in their own right, but that’s something that comes with being a FHIR client.

Of course this interface is actually more complex than the one it replaced, and it will take more work server-side to produce it that the previous custom version did. Where there was a single ‘object’ representing the encounter, we now have an object graph. But – and it is an important but – our interface can be used by any FHIR compliant system, which means that we can support – and promote – an international ecosystem of health information exchange.

Further, much of the complexity can be hidden behind libraries that are freely available (or we can write our own if we want to). It’s clean and easy to understand. And, finally, we have a design than has been created by some of the smartest minds in healthcare IT – and it didn’t cost us anything!

What’s not to like?

:)