Queues App Functional Spec
Introduction
In any busy waiting room, it’s difficult for healthcare staff to remember:
Who is here in my department? Who is the top priority? What exactly are they waiting for next?
The queues app aims to allow healthcare staff to:
Organize People: view patients with active visits, based on the service the patient is attending, and their current status for that service.
Prioritize the Right People: show how long a patient has been in a particular status, what their priority is, what they may be waiting for and when they will be transitioned to another status relative to other patients on the queue.
Move People: Through workflows and/or physical workstations. The queues app supports workflows to change a patient status on a queue and to transfer a patient between queues.
This specification lists out the functional requirements and design considerations for the O3 Reference Implementation of the queues app front-end.
Definitions
Location: A location within the hospital/clinic facility. Every queue MUST be associated with a location*. However, note that a Location can have multiple queues.
Session Location: The location the user selects and logs into from when logging into the OpenMRS instance.
Service: A concept that represents the specific service that a Queue is associated with. Every queue MUST be associated with a service*. The list of possible services of a Queue is defined by a global property.
Visit: A Visit tracks a patient who has entered the facility. A Visit MUST have a start time, and MAY have an end time (if it has ended). A visit that has not ended is an Active Visit.
Queue: An ordered list of patients to track at a particular Location for a particular Service over time, typically within a Visit. A typical Queue will have several Queue Entries that track a given patient throughout the course of a given visit. An example of a typical Queue would be a Consultation Queue in which patients transition from a state of "Waiting" to "Attending" during their Visit.
Queue Entry: Represents that a patient is on a queue with a specific state and priority, typically for a particular visit, for a specific date/time period. Besides the patient, a queue entry is required to contain the following:
Started At: The date and time at which the queue entry is considered valid. Note that this is usually the timestamp at which the patient is added to a queue, or has its status or priority changed from a previous value. However, the Started At time may be set to a time in the past (for the purpose of retroactive data entry)
Priority: The priority of the patient in the queue (ex: Urgent, Expedited, Normal). The list of possible priorities of a queue entry are defined via a Concept Set. This is configured via a global property as a default for all queues, and can also be defined on a per-queue basis. In other words, some queues may have only one possible priority (effectively disabling the prioritization mechanism) while other queues can have multiple tiers of priorities.
Status: The status of the patient in the queue (ex: "Waiting for Admission", "Admitted", "Waiting for Transfer"). This is configured via a global property as a default for all queues, and can also be defined on a per-queue basis. Status may be ordered to imply a linear workflow the patients might typically go through (Waiting for Admission => Admitted => Waiting for Transfer).
Active Queue Entry: Queue entries that have started but not ended are considered active, whereas those that have ended remain as part of the history.
Remove from Queue: Although Queue entries can be voided or purged, this is only appropriate in the case of data entry error. The correct way to "remove" a queue entry is to mark it as ended. Whenever we indicate "Remove from Queue", this means to mark the active queue entry as ended, typically with the current timestamp when used at point of service.
Transition: An action the causes a queue entry to end and immediately starts a new queue entry with (slightly) different fields. This allows us to keep a history of queue entries through the transitions of a patient's visit. Note that there are some use cases (like RDE or data correction) where a transition is NOT an appropriate way to change the patient's queue state.
Transfer: A transfer is represented whenever a patient ends one Queue Entry and starts a new Queue Entry at the same date/time, but when the two Queue Entries are associated with different Queues. Note that this is a special case of a transition.
Status Change: A status is represented whenever a patient ends one Queue Entry and starts a new Queue Entry at the same date/time, on the same Queue.
* Note: This may change in the future, see: https://openmrs.atlassian.net/browse/O3-2454
Requirements
| User Story | Details |
---|---|---|
Entering / Editing Queue Entries | As a clerk, from a queue view, must be able to search for a patient and add the patient to a specific queue |
|
As a clerk, from a queue view, must be able to manage existing queue entries: |
| |
As a clinician, from the patient chart: |
| |
In any of the use cases listed, when adding or editing queue entries: |
| |
Viewing Queue Entries | As a clerk, I want to be able to view the patients currently being followed on a specific queue with a specific status |
|
| As a clerk, I want to be able to view the patients currently being followed on a specific queue, organized by status |
|
| As a clerk, I want to be able to view the patients currently being followed on any queues, filterable by queue, service, location, and status |
|
| In any of the use cases listed: |
|
Viewing Queue Metrics | As a facility manager, should be able to view aggregate volume of specific queues |
|
Out of scope
These items are considered out of scope for the ref app. (They may, however, be implemented and turned on via configurations)
Appointments - Any action done within the queues app should have no effect on appointments
Adding / Removing of Queues themselves (not queue entries)
Further Reading
Backend Support for Service Delivery Queues / Workflows - Development - OpenMRS Talk
Current Mockup of Active Visits List, which has some similarity to the Queues App.