Server roles in FHIR

As part of the preparation for the connectathon and clinicians challenge at the WGM in October, I decided to update clinFHIR so that it can access different servers for data and ‘conformance’ resources like ValueSet and StructureDefinition. Currently clinFHIR assumes that everything it needs to operate is supplied by a single server – from looking up profiles (StructureDefinition resources), finding and expanding ValueSets through to actually storing and retrieving the resources created for a patient. This is fine when the server is Grahames, as he aims to implement the entire specification (and generally succeeds!) but it’s a big ask for any server to do this.

After some discussion with Grahame and Michael on the Terminology chat, we identified 4 main server roles that you might apply in a real implementation – which could be a single Enterprise or something larger like a Country (eg New Zealand):

  • A Patient server that maintains Patient references. This is equivalent to the EMPI (Electronic Master Patient Index) – a service that can identify patients including duplicated references and the like. (Actually, you might also add Practitioner and other ‘service’ resources in here as well) – maybe this is more of an ‘identity’ service?
  • A Registry server that has copies of all the ‘conformance’ resources needed in a real-world implementation – such as StructureDefinition, OperationDefinition and ImplementationGuide, but perhaps also resources like Questionnaire. This are resources that ‘define’ things, rather than being resources you’d attach to a patient
  • A Terminology server that performs the various terminology related operations defined in the spec. It would need to store ValueSet resources at least – and likely ConceptMap and NamingSystem as well
  • And finally one or more Data servers where patient related (clinical) resource are stored.

Now, this is only a draft list – but as we get past DSTU-2 it may be worth defining these a bit more rigorously – both in terms of what the server roles are, and which resources ‘belong’ to each role (or roles). And do remember that a single physical server can implement multiple roles – indeed, most of the test servers actually do.

To test out the idea – and to make something useful for Connectathon server developers, I added these roles to clinFHIR, and made it possible to select which physical server is in each of the 4 roles.

The idea is that if you are developing, say, a Patient server as part of track 1 of the Connectathon, you can use clinFHIR as a client just for the Patient role, as it can both create and search for Patients thus testing your application. You’d leave the other roles to Grahames server (or any other server you want).

Similarly if you were developing a Terminology server you’d set the Terminology server to your own one and then see if ValueSets were correctly expanded while creating a resource. (To make it a bit easier, if a particular ValueSet doesn’t exist on the Terminology server clinFHIR will offer to copy it across from Grahames server – this is the idea of a ‘master’ server – perhaps another server role)

So far so good, but in the absence of defined roles in the spec, how does a server know what clinFHIR expects of it if it is purporting to be, say, a terminology server? Well, that is actually one of the functions of the Conformance resource. As well as indicating what a server can actually do – it can also be used as a statement of requirements. So clinFHIR exposes a conformance resource for each of the roles that it currently recognizes (or it will do!).

Here’s one for the Terminology Service role.

    "resourceType": "Conformance",
    "id": "1",
    "meta": {
        "versionId": "1",
        "lastUpdated": "2015-09-07T08:05:40Z"
    "date": "2015-09-01",
    "description": "The functionality of a Terminology server required by clinFhir",
    "kind": "requirements",
    "fhirVersion": "1.0.0",
    "acceptUnknown": "both",
    "format": [
    "rest": [
            "mode": "client",
            "resource": [
                    "type": "ValueSet",
                    "interaction": [
                            "code": "read"
                            "code": "create"
                            "code": "update"
                    "searchParam": [
                            "name": "url",
                            "type": "uri"
            "operation": [
                    "name": "expand",
                    "definition": {
                        "reference": "OperationDefinition/ValueSet-expand"

What it is stating is that clinFHIR needs a terminology server to:

  • Support read, create and update of ValueSets (the create and update is because it will copy ValueSets to the terminology server if it doesn’t already have a copy of one it needs).
  • Allow ValueSets to be queried by url. This is important as a ValueSet (as with many of the conformance resources) is identified by its url. This should be directly accessible, but it doesn’t have to be. So in this case, we query the terminology server for a ValueSet based on the url, rather than trying to resolve the url directly. (It’s an interesting question if the server has more than one ValueSet with the same url – it’s probably an error but clinFHIR just takes the first one).
  • Support the $expand operation against ValueSet defined in the spec.

To see how this worked out, start up clinFHIR and with the welcome page displayed click the link in the top right of the navbar labeled ‘Show Servers’:

Screen Shot 2015-09-07 at 4.35.49 pm

This will open up the following dialog where you can select the servers for each role. (You’ll note that as you hover over the link there’s a popup that also shows the current settings – useful if you just want to confirm the current settings).

Screen Shot 2015-09-07 at 4.25.04 pm

For each of the roles you can select the server from the list of known servers using a dropdown, and you can also display the conformance resource for that server. If you click on the label then you’ll see the requirements conformance (or will do once that’s complete as I said above).

To add a new server to the list of known ones, click the ‘Add new server’ at the bottom of the screen. This will display the following dialog, where you can enter the details of the server:

Screen Shot 2015-09-07 at 4.37.33 pm

  • The Role
  • The Display name (keep this short)
  • The full Url to the server. You can also view the servers conformance resource from here.

Clicking the add button will add the server to the known list of servers for that role. Repeat the process if your server is in multiple roles. Note that clinFHIR will check for a conformance resource before it adds the server, and will only add a server that supplies this resource (as every FHIR server should). It doesn’t otherwise examine the resource at this time – though there’s no reason why it couldn’t compare the conformance to the ‘requirements’ conformance for that role and alert if there is missing functionality.

After that, clinFHIR acts pretty much as usual – except that now it will retrieve and store resources to the configured servers. (It’s a bit of a shame that such a simple looking thing took so much work to implement!)

So you could imagine an EMR/EHR hooked up in exactly the same way as clinFHIR is – utilizing common services for terminology and profile structures, and populating shared repositories of data – such as medication lists, conditions & allergies in addition to local data stores.

Take New Zealand – if we stood up a terminology server we’d be a long way towards consistent coding of data. Add in the registry to store our profiles and extensions, place a FHIR interface in front of the NHI (our common patient identity service) and HPI (a Practitioner/Organization service) and a repository for the shared clinical data and we’ve got a pretty comprehensive system for recording high quality clinical information in a way that is easily accessible – a step on the way towards the ecosystem.

So have a play and feel free to feed back any suggestions and bug reports. At the time of writing most of the resource builder is working OK (including the standard profiles as far as I can tell) – though there are a few issues with child nodes, and it doesn’t check the data servers conformance resource to see what resources it supports. The profile builder is still broken though and doubtless plenty of other bugs to squash!

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.

19 Responses to Server roles in FHIR

  1. Juan Tapia says:

    Link broken?

    • David Hay says:

      Hi Juan – Thanks for that! Serves me right for typing it in as opposed to copy/paste. Link updated. Thanks for pointing it out!

  2. Peter B says:

    As always, an excellent post, David. I like the idea of defining roles for a particular server. And as with your clinFHIR app, I anticipated this with my own FHIR client awhile back by adding configuration support for a terminology server. Also, I see particular value in a Patient reference server dedicated to providing an index of patient records across settings of care. In fact, that’s pretty much what the CommonWell project in the U.S. is all about. Cheers.

  3. As always, an excellent post, David. I like the idea of defining roles for a particular server. And as with your clinFHIR app, I anticipated this with my own FHIR client awhile back by adding configuration support for a terminology server. Also, I see particular value in a Patient reference server dedicated to providing an index of patient records across settings of care. In fact, that’s pretty much what the CommonWell project in the U.S. is all about. Cheers.

  4. Pingback: Talking with a Clinician | Hay on FHIR

  5. Pingback: Creating reusable scenarios using clinFHIR | Hay on FHIR

  6. Pingback: Orders in FHIR | Hay on FHIR

  7. Pingback: Orders in different servers | Hay on FHIR

  8. Pingback: Cleaning up clinFHIR | Hay on FHIR

  9. Pingback: clinFHIR and 2.1 | Hay on FHIR

  10. Excellent post, thanks for the info.

    I’m trying to understand how it should be architected a fhir platform following the approach you have described and I would like your opinion regarding the “registry server”. What do you think it should be a good solution:

    1.- Implement a static server where Conformance, StructureDefinitions, Profiles, etc. are hosted as static files (json and/or xml) and every time you have changes, you CRUD those files, maybe “manually”. Search functionalities here would be limited.
    2.- Or implement a dynamic server with a database where you can CRUD definitions and implement better searching functionalities?


  11. jorgemiddleton says:

    Excellent post!!!

    I’m trying you define a FHIR platform and I would like your opinion regarding “registry server”. Having in mind we are not going to have many different profiles or resources (extended resources) and they should not regurarly change, which option do you think is better?

    1.- Implement an static server where we can statically host Conformance, StructureDefinitions, Profiles, etc. We copy all the definitions files (json and/or xml) and when there are changed, we just replace/update the static files. There are some limitation in term of search functionalities with this approach.

    2.- Implement a dynamic server where we can CRUD the resources using the API of the server. Here we would need a Database where we store the definitions. Here we can implement better capabilities in term of searching and maintance, however the platform requires more components (REST Server + Database).

    Thanks in advance,

    • David Hay says:

      Hi Jorge – I guess it depends on what you need to do. If it’s just for reference purposes – ie from a resource instance then static files would be fine – but I suspect that you’d come to miss the other CRUD abilities eventually! You can (should) also use the official registry – ie simplifier from furore – or an instance of one of the reference servers if the load is light (I’m partial to the HAPI CLI server myself! – – though how it would stand up in a high volme production scenario I’m not clear

  12. Pingback: Projects in clinFHIR | Hay on FHIR

  13. Pingback: Setting up your own FHIR server for profiling | Hay on FHIR

Leave a Reply

%d bloggers like this: