Merge branch 'release/3.0.0'

pbchase · pbchase · commit 81c48417a22f · 2026-01-05T12:05:25.000-05:00
diff --git a/AUTHORS.md b/AUTHORS.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,10 @@
 # Change Log
 All notable changes to the REDCap Warn Users of Pending Suspension project will be documented in this file.
 
+# warn_users_of_pending_suspension 3.0.0 (released 2026-01-05)
+- Make extend_suspension_time() optional (@pbchase, #26, #28)
+- Replace AUTHORS.md with CITATION.cff (@pbchase, #25, #27, #28)
+
 # warn_users_of_pending_suspension 2.0.5 (released 2025-12-12)
 - Add VERSION (@pbchase)
 - Do not log the event (@pbchase, #24)
diff --git a/CITATION.cff b/CITATION.cff
@@ -0,0 +1,51 @@
+# This CITATION.cff file was generated with cffinit.
+# Visit https://bit.ly/cffinit to generate yours today!
+
+cff-version: 1.2.0
+title: REDCap Warn Users of Pending Suspension
+message:
+  If you use this software, please cite it using the metadata
+  in CITATIONS.cff or https://doi.org/10.5281/zenodo.3634733
+type: software
+authors:
+  - family-names: Chase
+    given-names: Philip B
+    email: pbc@ufl.edu
+    affiliation: University of Florida
+    orcid: https://orcid.org/0000-0002-5318-9420
+  - family-names: Chesney
+    given-names: Kyle
+    affiliation: University of Florida
+    orcid: https://orcid.org/0000-0002-0479-7251
+  - family-names: Stoffs
+    given-names: Taryn L
+    email: tls@ufl.edu
+    affiliation: University of Florida
+    orcid: https://orcid.org/0000-0002-0830-8179
+  - family-names: Gotti
+    given-names: Marly
+    affiliation: Apple, Inc.
+  - family-names: Bember
+    given-names: Tiago
+    affiliation: Howard Hughes Medical Institute
+  - family-names: Barnes
+    given-names: Christopher P
+    email: cpb@ufl.edu
+    affiliation: University of Florida
+    orcid: https://orcid.org/0000-0001-7114-1992
+repository-code:
+  https://github.com/ctsit/warn_users_of_pending_suspension
+url:
+  https://github.com/ctsit/warn_users_of_pending_suspension
+abstract:
+  A REDCap external module that will warn users of pending suspensions and provide an easy opportunity to extend the life of REDCap accounts.
+keywords:
+  - redcap
+  - "redcap repo"
+  - "redcap external module"
+identifiers:
+  - type: doi
+    value: 10.5281/zenodo.3561122
+license: Apache-2.0
+version: 3.0.0
+date-released: '2026-01-05'
diff --git a/README.md b/README.md
@@ -4,19 +4,16 @@
 
 A REDCap external module that will warn users of pending suspensions and provide an easy opportunity to extend the life of REDCap accounts.
 
-## Prerequisites
-- REDCap >= 8.0.3
+## Installation
+- Obtain this module from the Consortium [REDCap Repo](https://redcap.vumc.org/consortium/modules/index.php) from the REDCap Control Center.
 
-## Easy Installation
-- Obtain this module from the Consortium [REDCap Repo](https://redcap.vanderbilt.edu/consortium/modules/index.php) from the control center.
+## REDCap Requirements
 
-## Manual Installation
-- Clone this repo into to `<redcap-root>/modules/warn_users_of_pending_suspension_v<version_number>`.
-- Go to **Control Center > External Modules** and enable Warn Users of Pending Suspension.
+Warn Users of Pending Suspension (WUPS) is dependent upon REDCap's normal _Auto-suspend users after period of inactivity_ feature being enabled. WUPS does not suspend accounts it only _warns_ of pending suspending via emails.
 
-## REDCap Requirements
+## Breaking Change in Version 3.0.0
 
-WUPS is dependent upon REDCap's normal _Auto-suspend users after period of inactivity_ feature being enabled. WUPS does not suspend accounts it only _warns_ of pending suspending via emails.
+If your system uses a single signon configuration that bypasses the REDCap Login page, you might need to turn on `Update user_lastlogin on main REDCap pages` in the WUPS system configuration after you upgrade to Version 3.x. See the [Updating user_lastlogin](#updating-user_lastlogin) section below.
 
 ## Configuration
 
@@ -47,13 +44,23 @@ If the email address is blank in either case, emails will not be sent and the cr
 
         10, 12, 20
 
+## Updating user_lastlogin
+
+As of version 3.0.0, WUPS no longer sets the `user_lastlogin` column in the `redcap_user_information` table by default. Sites using single signon systems that bypass the REDCap Login page, might need to set `Update user_lastlogin on main REDCap pages` in the WUPS system configuration. This option will update the `user_lastlogin` column in the `redcap_user_information` table any time a user accesses the _Home_ page or the _My Projects_ page. To determine if your system needs this feature, upgrade to WUPS 3.x, logout of REDCap, login, then run this SQL query:
+
+```sql
+select username, user_lastlogin
+from redcap_user_information 
+order by user_lastlogin desc;
+```
 
+Your username should be near the top of the list, `user_lastlogin` should reflect the precise time of your login. If `user_lastlogin` is not updating, access the system configuration of the WUPS module and check `Update user_lastlogin on main REDCap pages`. 
 
-## How to Implement WUPS and Account Suspensions
+## How to Implement WUPS
 
 Implementing WUPS and/or activating REDCap account suspensions can require some careful planning to avoid annoying your users who have not logged in recently.  If you have never used account suspension on your REDCap host, activating it will cause all accounts that have not logged in within the _Period of inactivity_ to be suspended within 24 hours. If those people want their accounts reenabled they will have to ask the REDCap admin to reenable them.  That generates the kind of help desk workload WUPS was designed to _prevent_.
 
-To avoid the chaos of hundreds of accounts getting prematurely suspended, you can run a few SQL queries to adjust the last login dates and last activity dates for your REDCap users.  Done correctly, you can use WUPS to warn these users of the pending suspension, allow interested REDCap users to renew their account, and let the rest suspend normally.
+To avoid the chaos of hundreds of accounts getting prematurely suspended, you can run a few SQL queries to adjust the last login dates for your REDCap users.  Done correctly, you can use WUPS to warn these users of the pending suspension, allow interested REDCap users to renew their account, and let the rest suspend normally.
 
 The first step is to configure WUPS' _Days Before Suspension_.  In this example, we'll use `30, 15, 7, 3, 1`, but only the highest number affects our work. We've also set _Period of inactivity_ to 180 days. We want everyone who is approaching their date of suspension to receive every warning WUPS is configured to provide. To achieve that, _no one_ is allowed to be within 30 days of suspension when WUPS is turned on. This requires some accounts have their date of last login changed.
 
@@ -82,34 +89,6 @@ With that temporary table created, it is a simple matter to change `user_lastlog
 
 This will make the WUPS warnings start in 0-30 days. If the warnings are unheeded, account suspensions will happen in 30-60 days.
 
+## Contributing
 
-## Developer testing techniques
-
-To test WUPS, you need to turn on a few REDCap features it interacts with.  You need to turn on "Auto-suspend users after period of inactivity" in Control Center, User Settings.  For our tests we also set "Period of inactivity" to 30 days. A lazy developer might just want to run this SQL to make that happen:
-
-    update redcap_config set value="all" where field_name = "suspend_users_inactive_type";
-    update redcap_config set value="1" where field_name = "suspend_users_inactive_send_email";
-    update redcap_config set value="30" where field_name = "suspend_users_inactive_days";
-
-This module has to be configured before you can do anything with it. The instructions that follow assume the module has been configured as described in _Email Configuration Example_ above. The _Days Before Suspension_ setting of `10, 12, 20` is especially important. As this tool sends emails, also make sure the field that will be used for the **Sender Email** address is configured correctly in your module configuration.
-
-You'll need some test users. Assuming you have a set of test users `alice`, `bob`, `carol`, and `dan` you can configure them to receive alerts _today_ by adjusting their `user_lastlogin` date as follows:
-
-    update redcap_user_information set user_lastlogin = date_add(now(), interval -10 day) where username='alice';
-    update redcap_user_information set user_lastlogin = date_add(now(), interval -18 day) where username='bob';
-    update redcap_user_information set user_lastlogin = date_add(now(), interval -10 day) where username='carol';
-    update redcap_user_information set user_lastlogin = date_add(now(), interval -20 day) where username='dan';
-
-If you are testing REDCap under [redcap-docker-compose](https://github.com/123andy/redcap-docker-compose), the automatic table-based user creation tools can make these users for you. If you are testing under a [redcap_deployment](https://github.com/ctsit/redcap_deployment) Vagrant VM, the above set of test users can be created via the SQL file at [https://github.com/ctsit/redcap_deployment/blob/master/deploy/files/test\_with\_table\_based\_authentication.sql](https://github.com/ctsit/redcap_deployment/blob/master/deploy/files/test_with_table_based_authentication.sql). People testing in other environments will need to design their own set of test cases.
-
-To get the alerts from these test users, you'll want to update their email addresses with _your_ email address. e.g.,
-
-    update redcap_user_information set user_email = 'you@example.org' where username in ("alice", "bob", "carol", "dan");
-
-The final step to facilitate testing is to adjust the frequency of the cron job. The external module framework monitors the cron configuration settings in a module's `config.json`. If you change the cron frequency in that file to 60 seconds, the EM framework will, shortly thereafter, do the same to the module's cron job:
-
-    "cron_frequency": "60",
-
-Turn that value back down to `86400` (that's the number of seconds in one day) when you are done to get back to the normal configuration.
-
-All of these SQL commands and more are rolled up in [developer_testing_commands.sql](developer_testing_commands.sql). Open this file in your favorite SQL tool and run the commands one section at a time to see the relevant database state.
+Software developers who want to contribute to WUPS should read [Developer testing techniques](./developer_testing.md)
diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-2.0.5
+3.0.0
diff --git a/WarnUsersOfPendingSuspension.php b/WarnUsersOfPendingSuspension.php
@@ -1,33 +1,40 @@
 <?php
 /**
  * @file
- * Provides ExternalModule class for SuspensionWarning.
+ * Provides ExternalModule class for WarnUsersOfPendingSuspension.
  */
 
-namespace SuspensionWarning\ExternalModule;
+namespace UF_CTSI\WarnUsersOfPendingSuspension;
 
 use ExternalModules\AbstractExternalModule;
 use REDCap;
 use Logging;
 
 /**
- * ExternalModule class for SuspensionWarning.
+ * ExternalModule class for WarnUsersOfPendingSuspension.
  */
-class ExternalModule extends AbstractExternalModule {
+class WarnUsersOfPendingSuspension extends AbstractExternalModule {
  	/**
      * @inheritdoc
      */
-    function redcap_every_page_top($project_id)
+    function redcap_every_page_top($project_id = null)
     {
-        $is_on_log_page = preg_match("/(redcap\/\z|\/index.php\?action=myprojects\z)/", PAGE);
+		# Check if we are on the index page and there are no parameters
+		# If so, extend the suspension time for the user
+		# Otherwise, do nothing and return
+		$is_on_index = preg_match("/index.php\z/", PAGE_FULL);
+		$no_parameters = (count($_GET) == 0);
 
-        $is_on_homepage = preg_match("/\/index.php\z/", PAGE);
-
-        if ($is_on_log_page || $is_on_homepage) {
+        if ($is_on_index && $no_parameters) {
             if(defined('USERID') && !empty(USERID)){
-                $this->extend_suspension_time(USERID);
+				$wups_update_user_lastlogin = $this->getSystemSetting('wups_update_user_lastlogin');
+				if($wups_update_user_lastlogin) {
+					$this->extend_suspension_time(USERID);
+				}
             }
-        }
+        } else {
+			return;
+		}
     }
 
     function extend_suspension_time($username='')
diff --git a/config.json b/config.json
@@ -1,29 +1,27 @@
 {
     "name": "Warn Users of Pending Suspension",
-    "namespace": "SuspensionWarning\\ExternalModule",
+    "namespace": "UF_CTSI\\WarnUsersOfPendingSuspension",
     "description": "A REDCap external module that will warn users of pending suspensions and provide an easy opportunity to extend the life of REDCap accounts.",
+
     "permissions": [
         "redcap_every_page_top"
     ],
     "enable-every-page-hooks-on-system-pages": true,
     "authors": [
         {
-            "name": "Philip Chase",
-            "email": "pbc@ufl.edu",
-            "institution": "University of Florida - CTSI"
-        },
-        {
-            "name": "Taryn Stoffs",
-            "email": "tls@ufl.edu",
-            "institution": "University of Florida - CTSI"
-        },
-        {
-            "name": "Kyle Chesney",
-            "email": "kyle.chesney@ufl.edu",
+            "name": "University of Florida CTS-IT",
+            "email": "CTSIT-REDCAP-MODULE-SUPPO@LISTS.UFL.EDU",
             "institution": "University of Florida - CTSI"
         }
     ],
     "system-settings" : [
+        {
+            "key": "wups_update_user_lastlogin",
+            "name": "Update user_lastlogin on main REDCap pages",
+            "required": false,
+            "type": "checkbox",
+            "repeatable": false
+        },
         {
             "key": "use_wups_sender",
             "name": "Use Custom Email Sender",
@@ -74,9 +72,5 @@
             "cron_frequency": "86400",
             "cron_max_run_time": "1200"
         }
-    ],
-    "compatibility": {
-        "redcap-version-min": "8.0.3",
-        "redcap-version-max": ""
-   }
+    ]
 }
diff --git a/developer_testing.md b/developer_testing.md
@@ -0,0 +1,30 @@
+# Developer testing techniques
+
+To test WUPS, you need to turn on a few REDCap features it interacts with.  You need to turn on "Auto-suspend users after period of inactivity" in Control Center, User Settings.  For our tests we also set "Period of inactivity" to 30 days. A lazy developer might just want to run this SQL to make that happen:
+
+    update redcap_config set value="all" where field_name = "suspend_users_inactive_type";
+    update redcap_config set value="1" where field_name = "suspend_users_inactive_send_email";
+    update redcap_config set value="30" where field_name = "suspend_users_inactive_days";
+
+This module has to be configured before you can do anything with it. The instructions that follow assume the module has been configured as described in _Email Configuration Example_ above. The _Days Before Suspension_ setting of `10, 12, 20` is especially important. As this tool sends emails, also make sure the field that will be used for the **Sender Email** address is configured correctly in your module configuration.
+
+You'll need some test users. Assuming you have a set of test users `alice`, `bob`, `carol`, and `dan` you can configure them to receive alerts _today_ by adjusting their `user_lastlogin` date as follows:
+
+    update redcap_user_information set user_lastlogin = date_add(now(), interval -10 day) where username='alice';
+    update redcap_user_information set user_lastlogin = date_add(now(), interval -18 day) where username='bob';
+    update redcap_user_information set user_lastlogin = date_add(now(), interval -10 day) where username='carol';
+    update redcap_user_information set user_lastlogin = date_add(now(), interval -20 day) where username='dan';
+
+If you are testing REDCap under [redcap-docker-compose](https://github.com/123andy/redcap-docker-compose), the automatic table-based user creation tools can make these users for you. If you are testing under a [redcap_deployment](https://github.com/ctsit/redcap_deployment) Vagrant VM, the above set of test users can be created via the SQL file at [https://github.com/ctsit/redcap_deployment/blob/master/deploy/files/test\_with\_table\_based\_authentication.sql](https://github.com/ctsit/redcap_deployment/blob/master/deploy/files/test_with_table_based_authentication.sql). People testing in other environments will need to design their own set of test cases.
+
+To get the alerts from these test users, you'll want to update their email addresses with _your_ email address. e.g.,
+
+    update redcap_user_information set user_email = 'you@example.org' where username in ("alice", "bob", "carol", "dan");
+
+The final step to facilitate testing is to adjust the frequency of the cron job. The external module framework monitors the cron configuration settings in a module's `config.json`. If you change the cron frequency in that file to 60 seconds, the EM framework will, shortly thereafter, do the same to the module's cron job:
+
+    "cron_frequency": "60",
+
+Turn that value back down to `86400` (that's the number of seconds in one day) when you are done to get back to the normal configuration.
+
+All of these SQL commands and more are rolled up in [developer_testing_commands.sql](developer_testing_commands.sql). Open this file in your favorite SQL tool and run the commands one section at a time to see the relevant database state.
