It’s not uncommon for a document to need to be updated after it has been posted to a repository and registry. Sometimes new information has come to hand that affects the document, or there may be normal workflow where a ‘draft’ document is saved, and is subsequently updated or finalized, or maybe the original was just plain wrong and needs to be retracted.
None of these are unique to a document of course, but there are some ‘quirks’ – for want of a better word – to the DocumentReference resource for a couple of reasons:
- It is a resource whose main role is to refer to another entitity – so there are 2 lifecycles to consider.
- Documents are often summaries of clinical care (e.g. Discharge Summaries, Progress notes, Clinic notes) and it’s very common for clinical decisions to be made on the contents. Keeping an easily accessible (to the end user) ‘audit trail’ of changes is very important for medico-legal reasons.
When thinking about changes to a document, there are 2 ‘types’ of change to consider:
- Changes to the metadata (e.g. the document type was incorrect)
- Changes to the content of the document itself.
We’ll consider these separately.
Changes to the metadata
If the change is only to the metadata – the contents of the DocumentReference resource itself, then it can be updated it in the usual way – i.e. retrieve the existing version, make the changes, and PUT the document back. The standard FHIR versioning process will manage the update of the resource. (Resource versioning is not required by FHIR – but highly recommended). There are some caveats to this approach, as mentioned in a minute…
Changes to the document.
This is more tricky. What we need to do is:
- Update the document in it’s location (e.g. as a binary resource on a FHIR /Binary endpoint)
- Update the existing DocumentReference resource that points to it, setting the status property to ‘superseded’
- Create a new DocumentReference resource that references the updated document (and if it’s a FHIR server that we may want to make this a version specific reference), setting the relatesTo.code to ‘supercedes’, and the relatesTo.target as a reference to the original DocumentReference resource
- We might also want to create a provenance resource to indicate who has made the change.
Because this needs to be managed as a transaction, we’ll use a FHIR bundle and we’ll use the same pattern as when we submitted the document in the first place – i.e. have the repository server manage the updating process. (Other patterns are possible of course).
So our bundle will contain:
- The updated document as a base-64 encoded binary resource. It will have a real ID so the server knows to update it
- The original DocumentReference resource, with updated status. It will also have a real ID so the server knows to update it
- The new DocumentReference resource – largely a copy of the original with the relatesTo property set. It will have a ‘cid:’ ID so the server knows to add it as new.
- Optionally a provenance resource with the details of who made the change – and when. The provenance resource refers to the resource being changed (not the other way around) so it will have 2 targets – the 2 DocumentReference resources that are effected in this transaction. It also has a cid: ID.
The repository server will process the bundle as described above.
Although this second approach is more complex, it does make it quite obvious that a significant change has occurred. For this reason, some metadata changes – such as a change of subject or author – might be better managed this way rather than a simple update to the DocumentReference resource. It’s up to you…
All of this does raise an interesting point that we didn’t think about when considering how to query the registry for documents (i.e. a query against /DocumentReference) – the response will include DocumentReference resources that have been superseded as well as current ones.
If we don’t add the status parameter in the query, then we will get back all DocumentReference resource’s – so we will need to check this value when assembling the list of documents for the consumer (Of course, we may want to do this anyway so that we can place some visual indication in the display that changes have occurred – it’s up to the implementer, as it should be…)
Otherwise we can be explicit that we only want current documents, so the examples we gave in the previous post becomes:
GET http://registryserver/DocumentReference?subject= 100&status=current&period > 2013-01-01
and
GET http://registryserver/DocumentReference?subject= 100&status=current&type= http://loinc.org|34108-1
And as a last word, and following on from the post that Keith Boone made about task orientated services, we may choose to define specific service end points for this functionality (and even for the ‘add document’ scenario), perhaps:
- /service/document/new
- /service/document/update
both of which receive the bundles we’re described.