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": [
        "json"
    ],
    "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’:

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).

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:

• 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!