1. University of Kansas Medical Center, Medical Informatics Division
Enhancing REDCap Extensibility Using Model-View-Controller and Event-Listener Design Patterns
Michael R. Prittie, Matthew C. Hoag, Bhargav Adagarla, Lemuel R. Waitman
University of Kansas Medical Center, Medical Informatics Division
Motivation
Plugin Framework
Hook Registry
In 2014 Dr. Christie Befort, at the University of Kansas Medical Center (KUMC), was awarded $10 million by the Patient-Centered Outcomes Research Institute (PCORI) to fund the multi-site RE-POWER study. The primary aim of this study is to compare the efficacy of three obesity treatment models in rural Middle America.  To achieve this goal, the study will enroll 1440 patients over a five-year period, at 36 rural primary care clinics, across four Midwestern states.  In order to meet the RE-POWER study’s needs using REDCap, our team realized that significant customizations to REDCap would need to be made to deliver all of the desired functionality, which included:
REDCap plugins provide developers with a space to execute custom PHP code to produce new user-interfaces for REDCap users. This space gives external developers a very flexible “blank-slate” to create new functionality. If plugins are relatively simple, then all plugin logic can easily fit into one or two files, but as the complexity and number of plugins increases, the need for a structure to meaningfully separate logic grows. To provide this structure a Model-View-Controller (MVC) Plugin Framework was developed. A major contributor to issues of maintainability, readability, and robustness with code used to generate user-interfaces, is the blending of disparate types of logic into a single file, function, or class. The MVC design pattern was expressly developed to address these issues and does so by breaking logic up into three distinct components:
Models: Provide representations of and a means of manipulating an application’s underlying data.
Views: Produce user interfaces given a minimal set of relevant information.
Controllers: Manage interactions between models and views to achieve application functionality.
REDCap hooks allow outside developers to write additional PHP, which can “hook” into REDCap at specific times and places to add some desired behavior. Some hooks allow the look and feel of a given type of page to be altered, while others allow custom code to be run when a survey or data instrument are saved.
Event
Listener
Severe Adverse Event Alerts
Group Counseling Session Interfaces
Advanced Multi-Project Reporting
Event Triggered Data Pipelines
View
Controller
Model
[redcap_save_record]
hooks/projects/foo.php= foo_save_record:1,2
plugins/bar/hook_impl.php= bar_save_record:*
These feature gaps would need to be bridged in order for REDCap to be a viable solution for the RE-POWER study. Fortunately, REDCap provides external developers with three mechanisms through which to extend REDCap functionality.
The Hook Registry transforms REDCap hooks from a one-to-one, to a one-to-many event-listener pattern. With this pattern many listeners can be defined separately and registered with the same event independently. This allows for listener code to be logically separated from unrelated code and co-located with associated functionality. Listener functions are “registered” with target REDCap hooks (events) in a configuration file which defines hook – listener – project relationships (example configuration above).
Hook Registry use cases:
Severe Adverse Event Alerts (SAE): SAE alerts were one of 10 different alerts developed for the RE-POWER study using a Notifications Plugin which utilizes both the Hook Registry and the Plugin Framework. This plugin allows for notifications and calendar invitations to be configured by REDCap administrators using a dedicated REDCap project.
Event Based Data Pipelines: One example of a data pipeline is the RE-POWER patient screening process. As a patient is being screened their data moves between a dedicated registry project of potential patients to a patient project containing study data on those who have agreed to participate in the study.
REDCap Extensibility
In addition to the more highly structured API for manipulating REDCap's underlying database, the REDCap development team has provided more minimally structured plugin and hook offerings to allow external developers to extend REDCap functionally to meet local requirements. This approach, paired with over two dozen available helper functions, provides developers with an easily accessible, highly flexible environment within which to add new REDCap features.
Plugin Framework use cases:
Group Counseling Sessions: The RE-POWER team wanted their group counselors to be able to enter all of the information about a given group counseling session, both for the session as a whole, and for each patient individually, into a single form. This meant developing interfaces which pulled data from four distinct REDCap projects and saved form data to multiple records in two different projects.
Advanced Multi-Project Reporting: Since the RE-POWER study’s footprint spans eight different REDCap projects, the need existed to build reports across two or more of these projects at a time. The Plugin Framework was leveraged to both cleanly and securely execute report SQL, as well as display the report results. A dedicated REDCap project allows for new reports to be easily configured and access granted by username, project role, and/or DAG.
Minimally Structured
Simple
Flexible
Accessible
Highly Structured
Scalable
Maintainable
Modular
Summary
Acknowledgements
The REDCap Plugin Framework and Hook Registry allowed developers at KUMC to manage the complexity of creating and maintaining the REDCap customizations made in support of the RE-POWER study, and provided re-useable components which are currently being used to support other local REDCap customers. This approach resulted in DRYer code, that was more readable by peer developers, less error prone, more configurable, and easier to deploy to a production environment. Now that these resources have been produced, the rapid development of future customizations is possible as plugin and hook components are easily repurposed for new use cases.
This project is supported in part by NIH grant UL1TR000001, and PCORI Contracts CDRN and OB
We would also like to acknowledge the work of Dr. Christie Befort and Dr. Danielle Christifano, and their team at RE-POWER.
Source code for both the Plugin Framework and the Hook Registry can be found at:
The downside of this approach is it encourages the concentration of code into monolithic files in the case of plugins, and monolithic functions in the case of hooks. This concentration of code into monolithic forms presents challenges when producing highly complex, yet easily maintainable and robust REDCap customizations. In order to address these challenges a Hook Registry and Plugin Framework were developed to support local development of REDCap customizations at KUMC.
The REDCap Plugin Framework and Hook Registry developed at KUMC consist of a collection of loosely-coupled components. This means that any or all the available components can be used to aid in the development of a new REDCap customization.