Concept Proposal Client and Server

Primary mentor	Darius Jazayeri
Backup mentor
Assigned to	Melbourne Hack Night

Abstract

At the heart of every OpenMRS implementation is a concept dictionary that defines the medical concepts (questions and answers) used as the building blocks for forms, orders, clinical summaries, reports (almost every aspect of the data). Most OpenMRS implementations have an open concept dictionary - one that is considered incomplete and evolves over time, particularly as new forms are developed, with new questions and answers about different aspects of clinical care, or new disease areas.

Maintaining a high-quality concept dictionary is difficult, and requires significant work. Many projects outsource their concept dictionary maintenance (often by using the MVP/CIEL dictionary), but even among projects that don't, the dictionary is usually maintained by one person, while forms are designed and built by someone else.

The goal of this project is to build a simple client-server workflow that lets users create concepts on a development server, then send those in the form of "concept proposals" to an official concept dictionary, and track the status of those proposals.

Target Scenario

In the cloud there's a concept authority (in my case MVP/CIEL) who manages your concept dictionary, and you periodically pull updates from there.
You have one server that has your official concept dictionary. (This could be your "metadata", "forms", or production server.)
- No development work happens directly on this machine. Concept dictionary and forms are developed elsewhere, and imported.
You have one or more development machines where you do (potentially-messy) development and testing of forms

Target Workflow to Support

On a development machine, starting with your master dictionary, you work on a form. It is expected that you will create a bunch of new concepts, revise them, and delete some of them that were mistakes.
When your form is ready-to-go, you identify all concepts on your form that do not come from the master dictionary (i.e. they were newly-created)
You send that batch of new concepts up to a web service on the concept authority in the cloud, as proposals. You get back tokens you can use to check the status of your proposals.
(Periodically you ping the concept authority, until all proposals from that batch are resolved.)
You hit the concept authority and download its official versions of the concepts that you created locally, and these replace your locally-created concepts.
- (I hope we can leverage the Metadata Sharing module to do this pretty easily.)
You edit your form to refer to the new official versions of the concepts you proposed
At this point you export the form from your dev machine, and import it into your metadata/forms/production server.

Proposed Solution

Create one or two modules, to handle Client and Server sides of the Concept Proposal workflow.

(client-side, for use on forms development machines)

every time you create a new concept, it is marked as "temporary"
you can view a list of all "temporary" concepts, and delete ones you don't like
you can select some temporary concepts and "propose to master dictionary"
you can see a list of all your submitted proposals, and check on their current statuses (on the master server)
when a proposal has been marked as complete by the master server, the module needs to download it and overwrite your local "temporary" concept with the new official one, clearing the "temporary" flag

(server-side)

web service endpoint that lets clients propose a batch of concepts
web service endpoint that lets clients checking the status of a proposal
UI that lets the dictionary manager see a list all open proposals
UI that lets the dictionary manager see a detailed view of a single proposal
Ability to make comments on a batch of proposed concepts, or a single proposed concept
- In the first pass, this is purely for the dictionary manager to make notes for him or herself. Comments do not need to be communicated back to the proposer.
UI that lets the dictionary manager record what action they took for each item in a batch of proposals
- Created New Concept (specify the concept)
- Already Exists (specify the concept)
- Rejected (specify the free-text reason)
- (maybe more?)
Email notification to dictionary manager when a new proposal comes in

In a future iteration (but not required for the first pass) the server-side should automate the case where the dictionary manager decides that a proposed concept is "exactly right" and wants to create a concept exactly like it. In the first pass, we let the dictionary manager use existing UIs to create or modify concepts, and merely records the action they took with this module.

Personas and privileges

	Set up CPM locally	Edit CPM settings	Create draft proposal	Add (text) details to proposal	Add local concept/s to proposal	Save draft proposal	Submit proposal	Edit draft proposal	Edit submitted proposal	View own proposals	View all proposals
Clinician	x	x	x	x	x	x	x	x	x	x	x
Local admin	Y	Y	Y	Y	Y	Y	Y	Y	x	Y	x
Dictionary manager	Y	Y	Y	Y	Y	Y	Y	Y	N	Y	Y

Prior work

The OpenMRS data model contains a concept_proposal table, which is used to allow clinicians or data clerks a way to record things like symptoms or diagnoses when they are filling out a form and the value they want to record is not in the concept dictionary yet. For purposes of the first iterations of this project, it's okay to ignore this workflow. Further down the line we'll consider incorporating this.

There have also been prior attempts at building a Concept Proposal module that have failed, without generating any usable artifacts, largely because the use cases they attempted to handle in the first pass were too complex. You can look at those more complex functional requirements if you are interested, and sticking to the basic workflow described here.

Resources

An email thread about this concept proposal workflow
Suggested Excel template for proposing concepts to MVP/CIEL