FHIR Collaborative Review Implementation Guide
- 1 Introduction
- 2 Overview
- 3 FHIR Resources
- 4 Actors
- 5 Steps
- 5.1 1. a user (the 'editor') initiates a review cycle on a 'target resource'
- 5.2 2. other users ('reviewers') are invited to participate in the review
- 5.3 3. reviewers are presented with a form that allows them to comment on the contents of the resource
- 5.4 4. the editor is notified of reviewer's progress in the review
- 5.5 5. the reviewers and the editor is able to see a summary of user comments on the review, and respond with a comment of their own
- 5.6 6. reviewers are notified of the editor's comments, and all users are able to see the final outcome
- 5.7 7. the editor updates the target resource
This Implementation Guide describes a how a FHIR Server can provide a set of services that allows for a team to review a resource instance, comment on it's contents, and then provide a response by a collator, following which, the original resource will be updated.
This Implementation Guide is intended to be suitable for supporting the collaborative review process on conformance resources (profiles, extensions, value sets, translations, conformance statements etc).
Note: The process that this IG supports may also be useful and applicable to other kinds of FHIR resources (e.g. clinical review of a medications list), or some variant of the process may be needed, but this is out of scope of the first round of this implementation guide.
Fundamentally, the review process follows this general pattern:
- a user (the 'editor') initiates a review cycle on a 'target resource'
- other users ('reviewers') are invited to participate in the review
- reviewers are presented with a form that allows them to comment on the contents of the resource
- the editor is notified of reviewer's progress in the review
- the reviewers and the editor are able to see a summary of user comments on the review, and respond with a comment of their own question: do we anticipate a 'threaded' discussion?
- reviewers are notified of the editor's comments, and all users are able to see the final outcome
- the editor updates the target resource
I think we also need to support a more informal process, whereby -for some longer period- anyone (users, developers, ...) can submit comments about the resource.
The following FHIR resources are used in the review process:
- Practitioner- all the registered users (see below) involved in the process are exposed as Practitioner resources that represent their possible roles to the system
- Group - the Group resource allows users to identify their review interests
- Encounter - each review cycle is represented by an encounter dh: would this be better represented as a task?
- Questionnaire - generated to collect comments from the reviewer or editor
- QuestionnaireResponse - records the input made be reviewer or editor
- StructureDefinition & ValueSet - used by the server when generating questionnaires for steps 3 and 5
- Communication/CommunicationResponse - used to track invitations and notifications through the process
- AuditEvent - used to record all the steps in the process
The heart of a good Collaborative Review Process is the ability to generate good questionnaires from the underlying resource definitions and the target resource.
The following services are described that act in concert to provide a Collaborative review. Note that any single server may provide more than one of these. It is assumed, for the purposes of this service, that all the services share the same set of authorised users (and user SMART on FHIR to authorize them).
- Orchestration Server - this provides the workflow support, tracking the overall process. Resources: Communication/CommunicationResponse/AuditEvent/Practitioner/Group
- Target Server - this hosts the resource that is being reviewed
- Presentation Server - this takes a reference to the target profie, and generates a nicely formatted questionnaire asking the user about it's content
- analysis server - this takes user submissions as QuestionnaireResponses, and stores them, and is capable of collating the output to a single.... something
- Conformance Server - this provides a FHIR Tooling Eco-system conformance service that supports the Presentation and Analysis servers
- Display server - takes a profile and generates a display of that profile. The profile could be similar to that used in the spec,or something more custom
- User server - the server hosting the Practitioner resources representing the users
- Example server - generates samples of resources conformant to the profile being tested. Either automatically generated or via a UI. Needs to work with a sample user with other referenceable resources
1. a user (the 'editor') initiates a review cycle on a 'target resource'
Editor logs into the Target server to select one or more conformance resources that will be reviewed. This creates a new Encounter resource on the Orchestration server. (How to make an Encounter point to the resources under review - I think it's a bit far fetched to use Encounter for this - ek). The editor may associate a specific Questionnaire with this round of comments and thus this Encounter, so the Questionnaire can be tailored to fit the review process for these conformance resources (actually, you may want a different Questionnaire per type of conformance resource - ek)
2. other users ('reviewers') are invited to participate in the review
The Editor invites the users by selecting one or more from the list of Practitioners (representing the users involved in the review process) from the Orchestration server. These are added to the Encounter as participants. The users are notified by the creation of a Communication resource. Subsystems watching the creation of such Communication resources are involved to signal the reviewers, e.g. by e-mail.
3. reviewers are presented with a form that allows them to comment on the contents of the resource
Reviewers either have a direct url to get to the presentation server (e.g. from the email), or find a list of reviews they are currently participating in on the Orchestration server, from which they may select one of the resources to review. The presentation server fetches the Questionnaire that is relevant for this review and conformance resource, and sees whether there is already a QuestionnaireAnswers present (e.g. when the reviewer has already partly answered the Questionnaire, or wants to change his/her answers) and renders the Questionnaire + pre-fills any answers already given. When the review is ready, the reviewer saves his/her answers using the Presentation server to the Orchestration server.
4. the editor is notified of reviewer's progress in the review
When QuestionnaireAnswers get created or changed, the Orchestration server looks up the review session (=Encounter) to which this submitted review belongs and finds the editor. The Orchestration server creates a new notification as a Communication resource, which -using a subsystem that is subscribed to new communication resources - will forward this to the editor.
5. the reviewers and the editor is able to see a summary of user comments on the review, and respond with a comment of their own
Reviewers and editors can query/poll the Orchestation server for submissions of QuestionnaireAnswers and view the other user's comments. They can select other user's QuestionnaireAnswers, and add one or more comments to them.
- I'd like to introduce a system where users can make comments on both conformance resources and QuestionnaireAnswers where they can refer to parts of the resource or Questionnaire by using FluentPath, so creating a Communication which has both a resource id (from the conformance resource or QuestionnaireAnswers) + a path into the resource. This way the Target or Presentation server can show the comments inline with the rendering of the resource itself.
6. reviewers are notified of the editor's comments, and all users are able to see the final outcome
The editor marks the Encounter as closed for review, updates the conformance resource(s). Finally, a Communication is sent to all interested parties. This may be a broader group than the reviewers, e.g. the Target site may have an RSS feed that reflects the Communication resources created as a result to updates to a conformance resource.
7. the editor updates the target resource
Don't see how 6 and 7 are different.