REDCap Email Notifications External Module
This README file has been written following the recommendations given at Make a README.
External Modules are individual packages of software that can be downloaded and installed by a REDCap administrator. Modules can extend REDCap's current functionality, and can also provide customizations and enhancements for REDCap's existing behavior and appearance at the system level or project level.
The Email Notification EM allows project administrators to schedule email notifications (every minute, hourly, daily, weekly or monthly) to one or more recipients summarizing record creation through the REDCap API, i.e. REDCap Mobile App.
Since REDCap 9.0.0 version, the Email Alert EM is included as core functionality within the Alerts & Notifications Application. This application allows users to construct alerts and send customized email notifications. These notifications may be sent to one or more recipients and can be triggered or scheduled when a form/survey is saved and/or based on conditional logic whenever data is saved or imported. However, these notifications are record-based, i.e. one notification when one record is saved (one-to-one). This is adequate when records are not created in a very frequent basis, e.g. a Clinical Trial. However, for a Household Survey context, in which many records are created everyday, these kind of notifications may be overwhelming.
Thus, the Email Notification EM sends every minute, hour, day, week or month a summary of the new records coming from the field, i.e. from the REDCap Mobile App. This summary includes the number of records created, who created them and in which project.
Installation
This External Module is not part of the REDCap Repo yet. Therefore, you will need to copy and paste manually the email_notifications_vX.X.X folder to the REDCap modules directory, usually at:
cp -R email_notifications_vX.X.X /var/www/html/redcap/modules/
chown www-data:www-data -R /var/www/html/redcap/modules/email_notifications_vX.X.X As this EM is using the REDCap::email method to send the emails from a cron call. PHP sendmail configuration must be setup in CLI/php.ini as well as in APACHE2/php.ini. Although REDCap is not displaying any error related to the email configuration in the Control Center Configuration Check, CLI/php.ini must be checked to verify that sendmail setup is the same as in APACHE2.ini [REDCap::email from External Module Cron Job method].
Once you have copied the folder, login REDCap with an Admin account and navigate to the Control Center. Then, click on the External Modules link (within the Technical / Developer Tools section) and after on the Enable a module button. A popup will be open from where you will be able to enable the module.
After that, the EM will appear under the Modules Currently Available on this System section. Click on the Configure button and complete the Sender email address field with a valid email address. This will be the email address used in the FROM, i.e. from whom the email will appear to be sent. This will also be the "reply-to" address as it appears to the recipient.
Usage
Login REDCap and access to any project in which you have the Project Setup/Design privilege. Under the Applications section, click on the External Modules link. After that, click on the Enable a module button. Look for the Email Notifications vX.X.X module and click on its Enable button (on the right).
The module is now enabled in the project. It should appear under the Currently Enabled Modules section within the project. The next step is to configure it. Therefore, click on the Configure button close to the Email Notifications - vX.X.X module. A popup will be displayed allowing us to define as many notification recipients as we want. Each of the recipients will have its own notification frequency. To add more than one recipient, click on the + button.
Support
For reporting any problem and/or any feature request, go to the Issues tracker on GitHub. For any other question, write an email to maximo.ramirez@isglobal.org.
Roadmap
-
Send notifications in a concrete date and time: daily, weekly or monthly notifications are triggered when REDCap considers that interval has passed by and not at the end of the day, week or month. Next step is to provide the user with the capacity of defining when she wants to send the notifications. E.g. notify me how many records were created during the last week on Fridays at 18:00.
-
Log the action of notifying: write a project log just after the email notification has been sent.
Contributing
As far as this is a one-person repository, the branching model used is the simplest function model. I.e. two long-living branches, master and develop. Each release to production comes out from the master branch and it has a tag with a named version. The master branch is protected and it requires pull request reviews before merging. Therefore, all commits must be made to the develop or any bug-fix branches (which are not protected) and then submitted via a pull request that will have to be approved.
This way the team can work on new features on a separate branch (develop), while the master is intact until the next release. The main advantage of this approach is that, if you have bugs to fix (you will always have), you will be able to solve the bug without having to stash your changes or speed up the features you are developing. So in these situations, we create a short lived branch for the fix (a bug-fix branche), merge on the master and deploy to production with a new tag, and propagate the fix to develop. When the new features are ready, they would already have the fixes, and merging with the master branch would not be a problem [Grazi Bonizi, 2018].
Version numbers follow the recommendations from Semantic Versioning 2.0.0.
Authors and acknowledgment
This EM is entirely coded by Máximo Ramírez from ISGlobal.
Chris Kadolph is acknowledged by his contribution for setting project specific scope in REDCap EMs.
License
Copyright (c) 2019 Máximo Ramírez Robles
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.