Overview
The Patient Flags module allows users to create "flags" that generate warning messages in the Patient Dashboard.
A flag is simply some criteria (stored in a string), and an associated message string. The patient flag module computes the flags for a patient (or a group of patients) when in form submission or do this as AOP for data submitted outside of forms and save the results in the database table. Whenever a Patient Dashboard is loaded, it loads the selected patient is tested against all enabled pre-computed patient flags in the system, and for all flags that evaluate true, the database table and the associated message string is displayed. The message string can be simple string, or a code for a localized message stored in message.properties.
A flag All flags can also be tested evaluate against all Patients patients in the system via on the Administration page.Flag
In OpenMRS 2.x, the flags are shown in the patient dashboard under the patient flag section,
...
In the Legacy UI of OpenMRS, flag messages can be configured to be displayed in the patient header, and/or in a "Patient Flags" box in the Overview section. two primary locations,
patient header
patient overview section
An example of a patient flag displayed in the patient header:
An example of flags displayed in the Overview section:
...
Download
User Guide
On the Administration page, the Patient Flags section provides options to Manage Flags, Manage Tags, Manage Priorities, Manage Flag Display, and Find Flagged Patients.
Use the Manage Flags option to create new flags, and to edit and remove existing ones.
...
When creating or editing a flag, it may be assigned a priority, which determines the order of flags the style of text when flag messages are displayed on the patient dashboard. Priority levels and display styles can be set via the Manage Priorities page. A style for a priority can be any valid attribute that can be used within an HTML <span> tag. For example, to create priority where message text appears in red, set the style property to:
Code Block |
---|
style="color:red" |
Flags can also be associated with one or more tags, which are used to group flags together and to control what specific users (based on role) will see a flag, as well as where the flags are displayed. Use the Manage Tags options to create and edit tags. A tag can be associated with one or more roles and one or more display locations (i.e. the patient dashboard header or patient dashboard overview). Any flag that is associated with a tag will only be displayed in the location(s) associated with the tag, and to a user who has a role associated with the tag.
...
Security issues with Groovy scripts
One potential problem with Groovy flags is that a Groovy script could potentially be destructive. In most cases, we would like to restrict Groovy flags to only have view-related privileges. To that end, a specific username must be associated with Groovy flags. When Groovy flags are evaluated, they are only allowed, by proxy, the set of privileges associated with that user.
As a default, the module sets the Groovy flag username to the username defined in the scheduler.username global property. As this user is most likely a super-user, it is recommended that the Groovy flag username be changed to a user with a more limited set of privileges--perhaps even a dummy "Groovy user" created specifically for this purpose. The Groovy username can be changed in the "Manage Patient Flags Properties" section.
Note that when creating and editing Groovy flags, the privileges allowed are further restricted by those privileges assigned to the current user.
SQL Flag
A SQL flag takes a SQL statement as it's criteria. The SQL should be a SELECT that returns all Patients that match the specific criteria. For example, to flag all Patients that have an upcoming encounter scheduled, the criteria would be:
...
Code Block |
---|
for (Flag flag : results) { content = content + "" + flag.getLocalizedMessage() + ", "; } |
Global Properties
patientflags.defaultPatientLink - when viewing a list of patients generated using the "Preview" functionality, this defines the link that will be anchored to each patient. The patient id will be appended to end of the link in the format "patientId=123". If no value is specified, it links to the patient dashboard by default.
Required Privileges
Manage Flags and Manage Tags require "Manage Flags" privilege
Find Flagged Patients requires "Test Flags" privilege
...
Developer Guide
...
Get the Code
The module can be checked out through git at https://github.com/openmrs/openmrs-module-patientflags
You can build the module like any other mavenized module by doing a
mvn clean install
in the root module package.
REST endpoints
Method | URL | Parameters / Body | Description | Rep Default | Rep Full |
---|---|---|---|---|---|
Priority | |||||
GET | /ws/rest/v1/patientflags/priority/{uuid or name} | Fetches unique priority by name or uuid |
|
| |
GET | /ws/rest/v1/patientflags/priority | none | Fetches all priorities | ||
GET | /ws/rest/v1/patientflags/priority | q | Searches priority by name | ||
POST | /ws/rest/v1/patientflags/priority | name, rank style | Create with properties in request | ||
POST | /ws/rest/v1/patientflags/priority/{uuid or name} | name, rank style | Update with properties in request | ||
DELETE | /ws/rest/v1/patientflags/priority/{uuid} | Deletes the record | |||
Flag | |||||
GET | /ws/rest/v1/patientflags/flag/{uuid or name} | Fetches unique flag by uuid or name |
|
| |
GET | /ws/rest/v1/patientflags/flag | none | Fetches all flags | ||
GET | /ws/rest/v1/patientflags/flag |
| Searches data by specified filters. | ||
POST | /ws/rest/v1/patientflags/flag | name, criteria, evaluator, message, priority, enabled, tags (comma separated) | Create with properties in request | ||
POST | /ws/rest/v1/patientflags/flag/{uuid} | name, criteria, evaluator, message, priority, enabled, tags (comma separated) | Update given uuid with properties in request | ||
DELETE | /ws/rest/v1/patientflags/flag/{uuid} | Delete from database | |||
Tag | |||||
GET | /ws/rest/v1/patientflags/tag/{uuid or name} | Fetches unique tag by uuid or name |
|
| |
GET | /ws/rest/v1/patientflags/tag | none | Fetches all tags | ||
GET | /ws/rest/v1/patientflags/tag |
| Fetches tag by name | ||
POST | /ws/rest/v1/patientflags/tag | name, roles, displayPoints | Create with properties in request | ||
POST | /ws/rest/v1/patientflags/tag/{uuid} | name, roles, displayPoints | Update given uuid with properties in request | ||
DELETE | /ws/rest/v1/patientflags/tag/{uuid}?purge | Delete from database | |||
Display Point | |||||
GET | /ws/rest/v1/patientflags/displaypoint | none |
- name
...
Fetches all display points |
| not supported | |||
Patient Flag | |||||
---|---|---|---|---|---|
GET | /ws/rest/v1/patientflags/patientflag/{uuid} | get generated patient flag by uuid |
|
| |
GET | /ws/rest/v1/patientflags/patientflag |
| Searches patient flags by patient |
Release Notes
Version 3.0.7
Version 3.0.6
Version 3.0.5
Version 3.0.4
Version 3.0.3
Version 3.0.2
Version 3.0.1
Version 3.0.0
Version 2.1.0
Version 2.0.0
Version 1.3.4
Jira Issues | ||||||||
---|---|---|---|---|---|---|---|---|
|
Version 1.3.3
Jira Issues | ||||||||
---|---|---|---|---|---|---|---|---|
|
Version 1.3.2
Reverted change made in 1.3.1 since excluding antlr and asm jars was causing problems with executing Groovy flags
Added maven plugin to add svn revision number to module version number
Version 1.3.1
Fixed issue in 1.3.0 where antlr and asm jars were being included in the lib folder of the module (this is redundant since they are being provided by OpenMRS core)
Version 1.3.0
Updated to use OpenmrsClassLoader when instantiating an evaluator (to facilitate the use of custom evaluators in other modules)
Mavenized codebase
Version 1.2.9
Modified implementation so that flags and associated metadata can be shared using the Sync module
Removed auto-creation of default priorities (to facilitate sync)
Version 1.2.8.1
Removed "spring-form.tld" from jsp pages to make module compatible with OpenMRS 1.7, since "spring-form.tld" is included in the OpenMRS header as of 1.7
Version 1.2.7.1
Modified SQL Evaluator so that it will not return voided patients
Version 1.2.7
Fixed ticket http://dev.openmrs.org/ticket/2264
Version 1.2.6
Updated to be compatible with OpenMRS 1.6
Version 1.2.5
Improved Groovy flag evaluator so that privileges given to Groovy scripts can be better customized
Fixed SQL flag evaluator so that users without SQL Level Access privilege can still execute (but not create or edit) SQL flags
Added convenience method generateFlagsForPatient(Patient patient, Set<Role> roles, String displayPointName)
Version 1.2.1
Fixed typo in patientflags_tag_displaypoint table
Version 1.2.0
Added ability to control flag display based on location and a User's role
Added ability to specify custom evaluator types
Misc bug fixes/tweaks
Version 1.1.0
Added ability to display flags in the patient header
Added UI for modifying priority levels
Misc bug fixes/tweaks
Version 1.0.0
Added priority functionality
Fixed bugs with SQL evaluator criteria handling
Version 0.9.0
Initial version with basic functionality
Planned Future Functionality
- Better editor for Groovy scripts
- Improved criteria validation
- UI improvements
- Integration to OpenMRS 2.x UI