Feedback on Patient List Module Design

The OpenHMIS team is working on a new module that will display lists of patients; a module we are calling the patient list module. In this post we are asking for feedback from the community on our design before we start the development of the module. Please note, this module is not intended to be a solution for patient queueing as we see that as beyond the scope of this module.

The content below come from a more detailed module specification which can be found here.


The patient list module provides the ability to create customizable lists of patients that can be viewed from the Patient Lists page. A patient list is a named list with:

  • One or more selection rules
  • (Optional) Display templates for the patient list items
  • (Optional) List ordering rules.

The selection rules utilize patient information (that is patient details, patient attributes, visit details, and visit attributes) along with a comparison value and an optional value to compare against. For example, a list can be created to show all patients with an active visit that have a last name starting with “br”. The patient list item display templates (header and body) can use patient information along with basic HTML tags to customize the appearance of the patient list items. Lastly, the ordering of the patient list can be set by using any of the patient information fields.

Patient List Functionality

A patient list is a dynamically populated list of patients that meet some set of selection rules. These lists are viewable on the Patient Lists page and are generated on-demand, when a list is requested. Administrators create and manage the patient lists via the Manage Patient Lists page. Each list must have a unique name one or more selection rules. The list can optionally have a description, item header template, item body template, and ordering fields.

Selection Rules

A list selection rule is used to select which patients will appear in the list and has three parts:

  1. The patient information field
  2. The comparison type (equals, not equals, starts with, contains, is defined, is not defined, etc)
  3. An optional comparison value or field

The Add/Edit Patient List page will provide a simple UI to create selection rules and have dropdowns populated with all the patient information fields. When calculating the patients to include in a list, the selection rules will be transformed into HQL that will return the appropriate patients.

Display Templates

The appearance of each patient item on the patient list is customizable via display templates. Each list can define a header and body display templates. The header template is used to set the appearance of the single-line patient item header while the body template is used to set the appearance of the patient item body. If no display templates are defined the default templates will be used. The template can use basic HTML tags along with any of the patient information fields to create the format needed. Each patient list item has two parts:

  1. List Item Header
  2. Optional List Item Body

The template will use a common (yet-to-be-determined) web template language.


The ordering of the patient list can optionally be defined as part of the list definition by adding one or more ordering fields using the patient information fields. If no patient list order is defined the default ordering will be used.

Patient Information

The patient information fields can reference any of the following fields:

  • Patient Details
  • Patient Attributes
  • Patient Visit Details
  • Patient Visit Attributes

The patient and visit schema’s will be simplified (flattened) as much as possible. The patient information field syntax:

  • Patient Details: p.<field_name>
  • p.given_name
  • p.family_name
  • p.gender
  • p.birth_date
  • Patient Attributes: p.attr.<attribute_name>
  • p.attr.birthplace
  • p.attr.civil_status
  • Visit Details: v.<field_name>
  • v.start_date
  • v.end_date
  • v.note.primary_diagnosis
  • v.vitals.weight
  • Visit Attributes: v.<attribute_name>
  • v.attr.new_patient
  • v.attr.ward
  • Special Fields:
  • p.hasActiveVisit
  • v.hasDiagnosis

Patlient list Page Mockup

Potential Future Features

  • Real-time list updates
  • User/Role-specific lists
  • Selection Rule Grouping
  • List Exclusion Rules
  • User-specific lists
  • List Patient Removal
  • Remove a patient from a list, can be timed or permanent
  • Custom Patient Field Support
  • Utilize patient-related information from other modules

Hi @ibewes,

This sounds great! I would like to come back to you on the actual specs as outlined in your functional document, but first of all something drew my attention:

The Patient List Module will require:

  • OpenHMIS Commons Module version 3.2+
  • OpenMRS Reference Application version 2.3.1+

This is because I tend to become more and more paranoid about non cross-distributions UI development :wink: I understand that you want this to run within your usual UI environment, but would it be possible to try to adopt development methods that would allow those patient lists to be reused elsewhere as easily as possible? For example by using Angular components, or even better by (1) using Angular components and (2) shipping them through an OWA? It doesn’t have to be Angular of course but as long as the newly designed UI widgets are portable and reusable.

I would be curious to know your thoughts about this.

Thanks very much for your comments! This module will definitely be built using Angular and we will try to design the UI so that the components can be easily reused. Can you think of any specific use cases for a patient list outside of the patient list page that we will create?

Regarding shipping it as an OWA, what is the benefit of doing this as opposed to using the traditional omod distribution?

The requirement for the OpenHMIS Commons module is to allow us to use our entity framework for data access, data services, unit tests, REST resources, and our client-side Angular helper framework. Does the inclusion of this module (or the refapp modules) concern you?

I think there is always a little bit of a common UI pattern within OpenMRS. At first we start with a full page that provides the most complete UI for the new functionality that we bring in. But then it is also convenient to have the ability to produce more compact UIs to be inserted in other pages through extension points (such as dashboards, headers… etc). For instance our VDUI module revolves around the main documents gallery page but it also provides a more compact gallery to be shown on the CF patient dashboard for quick overviews. At the end of the day this comes naturally through widgets and parameters to control their mode of display. In our case is at its heart the thumbnail widget and then the gallery widget (as a list of thumbnails). The default gallery displays a lot and in fact makes for most of the main page, while simpler galleries can be displayed elsewhere, such as the quick one shown on the CF dashboard.

In theory the OWA is OpenMRS independent, as long as the REST API that it uses is around and provides the desired responses, it will just work. There is thus no more GSP pages, Spring… etc, just the pure client-side app. You may still need to produce a “traditional” OMOD to bring the missing REST resources (is that what OpenHMIS Commons is about?), but the whole UI will be shipped as an OWA. The most important thing is to ensure that the widgets are portable, and a thorough thinking about how to organise the Angular components is definitely the main thing to do (OWA or not).