A tool for commenting on profiles

In a previous post I talked about the seminar that we held at the recent HINZ conference where a group of clinicians discussed how to profile the AllergyIntolerance resource for the purpose of recording Adverse Drug reactions in New Zealand. While the conversation was fruitful, it was evident to us all that we needed a way to continue the conversation ‘virtually’ (ie without needing face to face meetings) and also a way to more easily involve others in the discussion.

To facilitate this, we’ve been working on new functionality for clinFHIR – imaginatively called ‘Profile Commenter’. This post describes the first version of that tool.

First the usual disclaimers – this is very much a ‘first cut’ – I’m aware of areas that need improvement (there’s a list at the bottom of this post) and there are doubtless bugs yet to surface, but hopefully it’s in a state where people can have a play and give feedback. For now, don’t assume that any comments you make in the tool will remain – they may need to be cleared as the tool develops, but hopefully it will be in a stable format reasonably soon.

To access the commenter, there’s a link (labelled Profile Commenter) on the left side of the welcome screen you see when starting clinFHIR. Alternatively the direct url is http://clinfhir.com/commenter.html.

The first task is to select the profile that you wish to view and/or comment on. To do this, click the ‘Find new’ link at the top of the page. This will display the profile selection dialog (it’s the same one used elsewhere in clinFHIR) from which you can select the profile. You will need to select the base type of the profile and optionally other search criteria then click the search button. Select the specific profile you want, then click ‘select’ at the top right.

The profile will be displayed in the commenter. Here’s an example:

Note that the profile will be listed in the dropdown to make selecting it again easier. It’s also cached in the browser to make it faster to load after the first time – use the refresh icon just to the left of the dropdown to clear the cache and force a reload – you’ll need this if the profile is updated. The profile is downloaded from Grahames server – we’ll look to add support for other Conformance servers later on.

The screen is divided into 2 panes:

• A Navigator pane to the left
• A Detail pane to the right

The Navigator pane shows all the elements within the profile, indented to show the hierarchy of the elements. Selecting an element in the Navigator will display details in the right hand Detail pane. In some cases the details of the datatype are shown (generally if the datatype has been profiled – eg made mandatory) – otherwise just the element name is shown.

If the element is required, then it will be red. If it has been removed in the profile (the minimum occurrence has been set to 0) then it will have a strike through. Note that not all removed elements will be shown – this depends on how the profile was constructed.

To the right of each element name are a set of icons that are displayed in specific circumstances. These are:

• An E is displayed if the element is defined by an extension
• A C is displayed if the element is coded and bound to a valueSet
• A lock icon indicates that the profile defines a fixed value to the element (Note that this is not a default – FHIR doesn’t do defaults – it simply indicates that to be conformant to the profile, a resource instances needs to have that value for that element.
• On the far right will be a number that indicates the number of notes that have been made against that element (if any).

The Detail pane shows details of the currently selected element. It has a tab set at the top with 2 tabs:

• Details of the selected element
• All of the notes for the selected profile in a table format

The details tab has sub-tabs:

• Information about the element
• Notes that have been made about the element
• A Json view of the element definition from the profile

The information about the element is modeled on that used in the Profile Designer. It has the following entries:

• The name of the element from the profile. This will be empty if not set in the profile.
• The path of the element within the resource.
• The multiplicity – how often the element can appear in a resource. It has 2 parts separated by ‘…’ – the first is the minimum number, the second the maximum – * means unlimited. A minimum of 1 indicates a required element (which will be red in the navigator), a maximum of 0 indicates disabled – which will have a strike-through.
• The permissible datatypes for the element. If the datatype is directly from the spec, then an ‘eye’ icon appears to the right that will display that datatype in the spec. If the datatype is profiled itself (eg the DAF allergyIntolerance profile has the subject referencing a profiled Patient resource) then a ‘down arrow’ icon appears to the right. Clicking that icon will load that profile in the commenter. A ‘left arrow’ icon is displayed in the right side of the toolbar that will reload the current profile.
• The short description of the element
• The definition of the element
• The requirements met by the element
• Any other comments
• If the element is coded, then the name of the ValueSet and the binding strength is displayed. An ‘eye’ icon to the right will invoke the ValueSet browser for that ValueSet – the same as used elsewhere within clinFHIR.

None of these items can be edited – they are purely for display.

The Notes tab is where you can view and enter notes and comments about the currently selected element. (You need to be logged in to add a comment – anyone can view them). To enter a note, simply enter the note text into the box provided and click ‘Add’. After a short delay (while the note is saved on the server) it will appear in the notes list.

A note can have comments made about it. For example, one person may make a note and others may wish to make observations about that note. To add a comment, click the ‘+’ icon that appears to the right of the note. This will display a text box below the note (and any other comments) where the new comment can be entered. Click the ‘Save’ button to save it.

As described above this notes tab shows only notes for this element – the ‘All Notes’ tab at the top will display all notes for this profile in a table.

If you don’t have an account just enter your email or some user name into the login dialog. Please don’t use any password you use elsewhere – this is really just so the app can associate a name with the comments, it isn’t particularly secure at the moment.

As I said above, there are some known limitations:

• The Navigator pane needs tidying – for example an option to hide all removed elements/datatypes. Nested extensions also look a bit odd…
• If an element has multiple profiles for a single ‘type’, then only the first is displayed
• Not all of the options in the element description are displayed in the UI (you can see them in the Json view however)
• The slicing display is still a bit flaky
• Some way of looking at history of changes to the profile (versions) would be nice
• Some way of finding ‘new’ notes & comments – perhaps new ones since the last time you looked?
• Supporting other Conformance servers – and the furore registry

So please have a play with the commenter and feed back comments / bug reports either as comments against this post or directly to me. I’m particularly interested in profiles that don’t render correctly in the navigator (and what is wrong), as that’s the area that needs the most work.