Using workflow to track comments

So there’s a requirement that’s come out of the UK profiling work (among others) to be able to gather comments about logical models as part of getting feedback – particularly from Clinicians.

The overall process would go something like:

1. Gather the requirements for a particular purpose – such as representing a medication list.
2. Create the first draft of a Logical model that represents that requirement
3. Circulate the model amongst interested participants – clinicians, informed consumers etc and gather their feedback
4. Update the model based on that feedback
5. Repeat steps 3 & 4 until consensus (or close to it) has been achieved
6. Create the FHIR artifacts (Profiles, ValueSets, Extension Definitions etc.) that represent that model

(This is a slightly abbreviated version of the process that I proposed earlier, and focuses on the modeling aspects of meeting the requirements.There are, of course, other issues to consider such as exchange paradigms, but for now let’s focus on the model.)

So from the perspective of changes required to clinFHIR we have:

• The ability to notify someone that there is a model that they can view and review.
• A way for them to record their comments – and view the comments of others
• A way for the editors to track who has commented – and who has yet to comment so that they know when it’s feasible to update the model based on feedback (step 4 above)

This sounds like a form of workflow to me, so I thought it was a good opportunity to experiment with the new FHIR workflow resources and see if I could do the whole thing (or most of it) using FHIR artifacts.

STU3 has proposed major changes to workflow (which you can read about here) – the most important (to my mind) being the definition of a ‘Task’ resource that co-ordinates the various activities around completing the workflow.   This supports quite a number of different workflow patterns – including our one.

After a bit of thought, I came up with the following pattern of use. When a model review is desired, a Task instance is created that has the Model as it’s ‘focus’ property, the Practitioner who is to perform the review as the owner, and a Communication resource that represents the contents of the review. (I did consider using an Observation resource – or embedding the review as the Task.note property, but Communication did seem the best candidate for now.)

Here’s what it looks like:

With this infrastructure in place, it becomes possible for the authors of a model to track who has made comments (and who has not) for any given model simply by retrieving all the tasks that are focused on the model, and then retrieving the communication resources that contain the comment. The task can either be created ‘up front’ by the model author, or a reviewer can create a task at the same time as they enter the comment.

The details are all hidden behind the UI of course, so let’s see how this plays out in practice.

Start clinFHIR, and select the servers (right now, you need to have the same server for data and conformance, so select the public HAPI-3 server for both). Select the Logical Modeler option from the gear menu to the upper right.

In the modeler, create the first draft of the model (making sure you save it) and then click the ‘Share’ button to the upper right. This will create a url that is a ‘shortcut’ to the model Copy the Url from the dialog box.

Then send the url to anyone you want to perform a review. They can enter it into a browser and the modeler will be displayed with the model selected (and the selection pane hidden to reduce screen clutter).

If they are logged in, then to the right of the screen is a tab panel labeled ‘Comments’. Selecting that tab will display a table of all the comments that have been entered so far. (If not logged in, then it’s easy to do so using the login icon – and they can also create a new user account if needed).

To enter (or update) a comment, select the ‘Add Comment’ tab. There’s a button to click that will enable the comment screen (technically, this is where the task is created). After this a text box is displayed where the comment can be entered. This is actually a simple ‘markdown’ editor to allow more advanced users to create a formatted note. There are buttons in the display that will do the formatting, or they can use the text shortcuts:

• #(space)<text> for a heading (also ## <text>, ### <text> & so forth)
• *(space)<text> for a bulleted item
• **<text>** for bold (note no spaces)

There’s a preview option so you can see what it looks like.

Click the Save link (bottom right of the box) to save.

You may wonder why we set it up that anyone can add a comment, and that the tasks get created automatically on request rather than being pre-assigned. The reason is that we want to make it as simple as possible for people to contribute, and giving them a link that they can paste into a browser is really simple

You might also think that this is a bit overkill for such a simple process – and you’re right, but it’s always good to have an opportunity to learn new stuff – and it does pave the way for more complex workflow in the future, such as the editor creating the Tasks and the reviewer operating off a ‘todo’ list, which could extend to the other artifacts such as ValueSet contents.

So this is very much a first cut of the reviewing functionality. Enhancements could include:

• Right now anyone can edit the models. Preferably, only model editors should be able to make changes to avoid confusion – though it would be nice for a reviewer to be able to make a copy of the model so they can show the editors what they think the model should look like (I think this can be done using FHIR’s versioning ability – though need to think through how that will work)
• The display of comments is rather crude – being a simple table of content and email. This is unlikely to scale well with a lot of reviewers – or with verbose reviews! We also need to allow users to enter their name as well as the email so the display is friendlier.
• Only a single comment per model is supported. Possibly multiple comments – maybe related to a specific model element – will be required
• We need to support multiple iterations of comment. This could require task status’s to be updated (to indicate that the task is complete) and new ones to be created. The display of old comments also requires some thought.
• It may be desirable in some cases to limit the people that can provide feedback – in that case a page where the editor can select the people they wish to perform the review might be needed (though the people must have already registered with clinFHIR for this to work).