Queues App Functional Spec

Owned by Chi Bong Ho
Last updated: Mar 08, 2024 by Grace PotmaVersion comment
8 min read
[ 1 Introduction ] [ 2 Definitions ] [ 3 Requirements ] [ 4 Out of scope ] [ 5 Further Reading ]

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.

Real Waiting Room Images_Sierra Leone.jpg
An OPD receptionist with a growing queue in background. (PIH, Sierra Leone)
Real Waiting Room Images.jpg
A growing waiting room in Mirebalais Hospital (PIH, Haiti).

 

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

 

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

  • Must be able to search for a patient and choose an appropriate patient from the search results

  • If the patient does not have a currently active visit, must be able to enter into a workflow to start an active visit before proceeding

  • If / once the patient has an active visit:

    • If the patient is actively on the current queue:

      • must provide options to transition the patient to a new queue and/or status, or to change their start time, queue priority and/or sort order

    • If the patient is not actively on the current queue:

      • must provide options to create a new queue entry for the patient, setting start time, priority, status, defaulting to the current date/time

    • If the patient is active on different queues:

      • must provide options to transition the patient from one of these other queues onto the current queue, defaulting to the current date/time and retaining the same priority if available

As a clerk, from a queue view, must be able to manage existing queue entries:

  • Must be able to transition the patient to a new queue and/or status, or to change their start time, queue priority and/or sort order

  • Must be able to end a queue entry without transitioning to a new queue or status

  • Must be able to delete/void a queue entry due to a data entry error or other

As a clinician, from the patient chart:

  • Within the context of a currently active visit:

    • Must be able to view the history of queue entries for a patient for the visit, along with queue, startedAt, endedAt, status, and priority

    • Must be able to add a patient who is not actively on any queue, to a queue with a specific status and priority, defaulting to the current date/time and session location

    • Must be able to to transition a patient who is actively on a queue to a new queue entry due to a queue change or a status change, defaulting to the current date/time

    • Must be able to change the start date/time, end date/time, priority and sort order of an existing queue entry

    • Must be able to end a queue entry without transitioning to a new queue entry, defaulting to the current date/time

    • Must be able to delete a queue entry that was entered due to error

  • With in the context of a past visit

    • Must be able to do all of the same steps as with the currently active visit, with the exception that no defaults to the current date/time and session location should be used, but entered explicitly

In any of the use cases listed, when adding or editing queue entries:

  • The startedAt and endedAt must be within the start time and end time of the visit it is associated with and should not overlap with any existing startedAt and endedAt for the same patient on the same queue

  • When operating on the active visit, the start time should default to the current date/time

  • Priority should default to the least urgent priority (lowest sort order of allowed priorities), unless it is a transition from another queue entry with the same available priority concept, in which case it should be preserved

  • Status should default to the first in the list of allowed statuses for a queue / lowest sort order

  • When transitioning to a new queue, there is no restriction on location - one could transition to a queue entry associated with a queue at another location

  • When transitioning to a new queue or status, the initial queue entry is ended, not deleted, and the new queue entry is started at the same date/time as the initial was ended

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

  • Example:  I want to just display a page of patients who are Waiting for Triage (specific Queue = Triage, specific status = Waiting)

  • Must be able to have a default view that displays patient name (links to patient chart), previous queue, priority, status, time on queue / wait time

  • Must support configurable columns, and must support these specific use cases:

    • Queue Number

    • Patient Name should be configurable to use the O2 patient chart instead of O3

    • Actions such as "Transfer" and a "Bell" icon to change status

    • Any other direct properties of Queue, with custom display formats

    • Age, Admission Date, Baby Name, Location of Baby

  • Must provide the ability to easily switch between different queues associated with my session location

  • Must provide the ability to view queues associated with other locations that are different from my session location

 

As a clerk, I want to be able to view the patients currently being followed on a specific queue, organized by status

  • Example: I want to display a page of all patients at ED Triage (queue), and I want to see those broken down by status (Waiting for Triage, Attending Triage)

  • Must support all of the same use cases as above, while easily allowing these to be filtered by status

  • Possible UI mockup:

 

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

  • Must support all of the same use cases as above, while providing filters on queue, service, and location (this is the closest thing that matches the current service-queues route)

 

In any of the use cases listed:

  • Queue Entries should default to ordering by sort_order asc, priority desc, startedAt asc.  sort_order allows explicit overrides of ordering, priority ensures critical patients are served first, then it is first come, first served

  • Queue Entry ordering should be driven by backend configuration, not frontend configuration.  The algorithm for producing the order should be configurable on the backend

Viewing Queue Metrics

As a facility manager, should be able to view aggregate volume of specific queues 

  • Should be able to view a summary card listing the number of active queue entries for a specific queue.  Should be able to link from this to the corresponding detail page described above.

  • Should be able to view a summary card listing the number of active queue entries for a specific queue and status.  Should be able to link from this to the corresponding detail page described above. 

  • Should be able to view a summary card listing the current wait time for a specific queue.  Should be able to link from this to the corresponding detail page described above.  (Note, currently the system has average, but this doesn't seem clear).

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