Building a set of resources in FHIR

One of the primary goals for clinFHIR is to help people who are new to the standard understand how it works – and increasingly these are clinicians whose interest is less in the technology and more about how FHIR can be used to represent the clinical information they wish to exchange.

While the current app does allow this, it has been aimed more at the people actually developing the resources than the casual user, and so can be time consuming to develop sets of resource instances that represent real world scenarios.

The component described by this post (called a simple builder – though a better name is needed!) is intended to allow someone completely new to FHIR to build sets of resources that represent clinical scenarios, to help them understand how the resources can be linked together – rather like Lego is used to build a complete model.

Before we get into the details – there are a number of caveats with the current version.

  • The resources that you create are not saved as individual resources on the server (yet). Rather they are packaged in a bundle and saved as a group. This means that the only references you can create are to resources within the set you are working on, and you cannot query for them directly off the server.
  • There are limits to the structured details that can be entered against each resource. Because it’s intended as a training tool, the focus has been on the ‘bigger picture’ of creating the ‘web’ of resources, rather than the individual details of the resource, so in many cases you just enter the text that describes the resource, rather than the coded elements.
  • The only resource types you can select are the ones defined in the spec – profiled resource types and logical models are not (yet) supported.

The intention (if there is interest) is to remove the limitations – it’d be great to store the resources individually on the server for example, and support profiles, logical models and resource updating. It just takes time 🙂 ).

Let’s work with an example – representing a patient’s medication list, which is something we’ve talked about before. The resources that we’ll need include:

  • The Patient who is the subject of the list
  • The Practitioner who created the list (it could also be the Patient in real life of course)
  • A List resource to represent the list itself
  • Multiple MedicationStatement resources for the individual medications.

To start the builder, load clinFHIR and log in (You can easily create an account based on your email address). Select the servers to use (I generally use the HAPI STU-3 servers for data & Conformance and Grahames server for terminology). Click the ‘gear’ icon to the upper right and select the builder from the menu that appears. The builder will open in a new page.

Here’s what the front screen looks like:


At the top of the screen is a navbar with the name of the current FHIR servers in use, some Library commands (that we’ll talk about later) and an icon for the user to the upper right – it is display only at this stage.

There are 3 main panes:

  • To the left is the list of sets that you are working with (you can have multiple sets at any one time).
  • In the middle are a number of views of the currently selected set. These are:
    • A list of all the resources in the set
    • A summary of the set (url, name, description, author and so forth)
    • A ‘graph’ view showing the references between resources
    • A ‘document’ view that appears when you are creating a FHIR document (more on this later).
  • To the right are the details of the currently selected resource – whether selected in the list of graph view. It also has 3 tabs:
    • Structure and Reference where you can add specific elements to the resource including (especially!) references to other resources
    • Resource Summary which shows the current references and allows you to remove them
    • A JSON representation of the resource for those interested in such things.

Create a new set by clicking on the ‘New Set’ at the top of the left pane. You’ll be prompted for a name for the set, and a description of its purpose. After saving, the new set will appear in the left hand list. (btw – in testing, I noted that sometimes it doesn’t appear but does after the page is refreshed. I’ll fix that eventually…)

To add a new resource, click on the ‘Add Resource’ button at the top of the middle pane. The right pane then shows a drop-down of all the resource types defined in FHIR. Select the one you want (say, Patient) and then enter a textual description of the resource (name, date of birth, gender etc.) into the text box that appears.

Finally, click the ‘Add’ button to add the resource to the set. After a brief delay (while the app retrieves the resource definition from the Conformance server) the details of that resource type will be displayed, including a tree view of the resource structure.

Repeat the process for all the resources identified above. You should end up with a display similar to the screen shot above.

To ‘wire up’ the references between the resources, you select the resource that the reference is from, then the source element within that resource, and finally the target resource. You’ll notice that when you select an element that is a reference type, the app will show a list of all the types of resource that that element can reference, plus a list of all the resources in the set that match any of those types.

For example, select the List resource, then the subject element. You’ll see to the right of the tree:

  • The textual description of the resource. To the right of the text field are icons that will allow you to edit the resource – or to remove it from the set.
  • A list of the potential resource types (Patient, Group, Device etc.). Each type has a ‘globe’ icon that will load the specification for that type in a separate page.
  • A list of the potential resources currently in the set that can be referenced from that element. Clicking the ‘plus’ symbol to the right of the resource actually creates the reference.
  • The description of the purpose of that element.

Here’s a screen shot:


And that’s all there is to it! If you select the graph view in the middle pane, you’ll see a line drawn between the referenced resources (from source to target). The graph updates in real time as you create the references, which is kind of fun! Here’s what the Medication list looks like after all the references have been established:


To remove a resource, select the Resource Summary tab in the right pane, which will show all the resources that are linked to/from this resource. There’s an ‘X’ icon against each reference that will remove that reference.

If you want to enter the data for an actual element, select the element in the Structure pane. This will show the data element types that can be used for that element, and clicking on the datatype will display a dialog where the value can be entered. This is much the same as in the clinFHIR resource builder, though in a modal dialog. Note that not all datatypes are currently supported.

If the datatype is coded and there is a ValueSet binding (which should always be there) then you can browse the ValueSet – again, much like clinFHIR.

Here’s a sample screen shot:


And a reminder of the caveat around entering structured data – this doesn’t work all that well for more complex resource types (like care plan) – with deeply nested structures. It really  only works properly for elements directly off the root of the resource. This is a work in progress.

The sets you create (and you can have as many as you want) are saved locally (in the browser) as you make updates so there’s no explicit ‘save’ option needed. You switch between different sets simply by selecting the set in the left pane.

To save the sets you create to the FHIR server (actually the Data Server) you use the ‘Library’ function. We’ll talk about that – and creating proper FHIR Documents – in the next post.

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.

10 Responses to Building a set of resources in FHIR

  1. Pingback: Simple Builder: Library and Documents | Hay on FHIR

  2. Hi David. Do you know any FHIR profile for Anesthesiology?

    We can say that the FHIR, as in openEHR, the development takes place in two layers, one for the clinicians (resource construction-> FHIR, archetypes-> openEHR)?

    Is there a tool that can be used to map FHIR resources to openEHR archetypes?

    Will a FHIR server be able to access the CKM and import archetypes by converting them to features and templates for FHIR profiles?

    Great work! Thank you!

  3. Pingback: Creating documents in clinFHIR  | Hay on FHIR

  4. Lin Zhang says:

    Hi David,

    Is this Builder currently called “Scenario Builder”?


  5. I am interested in developing resources for radiation oncology. In particular I would like to model the process of radiation therapy. Your blog is about the only source of practical knowledge that I have found, so thank you.

    In general, do you have any advice on how to model a complex process in some detail. For example, radiation therapy involves several complex procedures and important details. From my reading of the resources (not deep, let me assure you) it would seem that I would need to have many nested careplans, but some of these can have several activities, each with one detail (procedure). Would this be how one models this, or am I not understanding a more applicable resource.

    Thanks for an insight,
    Mark Phillips, Ph.D.
    Professor of Radiaton Oncology, University of Washington

    • David Hay says:

      Hi Mark – Thanks for the kind comments! You’re right that your process sounds rather complex and will doubtless require a number of resources to model properly – as well as Task Management (take a look at workflow in the spec) and some of the clinical reasoning resources to describe the protocols of treatment as well as individual careplans. I’ve been working on how to represent some of information models in clinfhir (the more resent posts talk about some of this stuff) which might help to start identifying some of the data requirements but I suspect you’re going to need more direct help to do this. Can I suggest that you take a look at the FHIR chat ( to get a feel for how others are approaching this kind of problem – and maybe a way to get in touch with others who may be looking at this.

      I googled ‘FHIR radiation therapy’ and came up with a number of links that might be of interest – including some from IHE which would also be worth exploring. If you’re not familiar with IHE ( it’s an organization that creates ‘profiles’ (not the same as FHIR profiles) which describe how to use standards like FHIR to meet business use cases – this is another source of information well worth following up. I also found this one: which looks promising. IHE and the FHIR community are working closely together to represent health care processes.

      Good luck!

      • Hi David,
        Thanks for your reply. I hadn’t appreciated the Task Resource before. I see know that it is quite powerful. Which leads me to a general sort of question: how difficult is it to establish one accepted way of using FHIR for an application? Given the flexibility of the resources, it seems like there may be multiple approaches.

        I am a member of the IHE-RadiationOncology (IHE-RO) committee. I have been pushing for the use of FHIR, but so far, the discussions have centered on using HL7 V2 for the existing and proposed profiles. I think this is due to the fact that the actual solutions to profiles are driven by the vendors and they all have V2 interfaces.

        Onward and upward!

Leave a Reply

%d bloggers like this: