This repository has been archived and is no longer actively maintained.

This project was archived as of October 1, 2025. The project for which it was written is now over. There's no funding to provide further maintenance for other projects. Please don't hesitate to use this code in accordance with the license; however, the authors are unable to offer any additional support.

A REDCap module to facilitate the scheduling and data management of COVID-19 testing for first responders. This project was created by a multidisciplinary team at the University of Florida to support the testing of first responders in Alachua County, Florida and the surrounding counties.

This module was created with numerous abstractions to allow it to be reused in other sites and projects, yet there remain some hard-coded project features. We advise you to use the included Project XML as a starting point to minimize your challenges in running this module. Also, be aware the data entry fields for site data do not carefully test the values keyed in. We recommend you start with the included example sites file, then make modifications.

• REDCap >= 9.3.5
• REDCap Entity >= 2.3.3

• Clone this repo into <redcap-root>/modules/fr_covidata_v0.0.0.
• Clone the redcap_entity repo into <redcap-root>/modules/redcap_entity_v0.0.0.
• Go to Control Center > External Modules, enable REDCap Entity, and then this module. REDCap Entity will be enabled globally, but fr_covidata has to be enabled on a per-project basis after Global Configuration is completed.

To configure and use this module, follow these steps:

1. Create a REDCap project from the file First_Responder_COVID19.xml
2. Update the appointments field on the Appointments Form, changing it to a Dynamic SQL field and configuring it to auto-complete. Paste the appropriate code from example/dynamic_sql_*.sql
3. Enable the FR Covidata module as described above.
4. Configure the FR Covidata module identify to set Which location ID is this project for? (0-15). This will reduce the risk of errors if one lab is processing specimens from different REDCap projects. Start with 0 and work your way up if you have to deploy multiple production instances of this module.
5. Configure the FR Covidata module identify to set Which instrument is used for appointments? In the included REDCap XML files, the form is named "Appointments".
6. Configure the FR Covidata module to indicate which repeat type is used for repeats: Repeating instances or Individual Events. In the included REDCap XML files, events are used.
7. Use a MySQL client to load sites data from redcap_entity_test_site_data.sql. Alternatively, use the Define Sites page of this module to enter the data. Be cautious as some portions of the interface of this module have very few guard rails. I.e., your data entry will not be checked. E.g., tiems must be entered in a 4-digit, 24-hour clock format such that 7 a.m. is 0700. The leading zero is critical. The development schedule has not allowed the addition of these tests, nor does it allow for much documentation. As such, the authors advise you to use the example configuration as a starting point.
8. Adjust the project_ids referenced on those just-loaded sites by editing and running a copy of redcap_entity_test_site_update.sql
9. Access Define Sites to make any needed changes to the site definitions.
10. Generate the initial appointment blocks by accessing Define Sites and selecting the sites of interest and clicking Manually generate new appointments

This module adds an appointment scheduling feature to REDCap. This feature is built on top of REDCap Entity and a dynamic SQL field. It allows appointment blocks to be selected from a Dynamic SQL field using the built-in auto-completion feature of Dynamic SQL fields. The SQL query queries a table of appointments to generate a list of available appointment blocks. On form save, REDCap writes the appointment_id into the value of the Dynamic SQL field. The module uses the redcap_save_record hook to write the record_id and event_id into the appointment record. The redcap_save_record hook will also update appointment-related fields on the record to provide easy lookups of the site details and date and time of the appointment block.

Once assigned to a person, an appointment block is no longer available. This feature is used in a REDCap survey to allow the first responders to select their appointments.

If the research participant needs to cancel or change an appointment, they must call the Study Team. The study team will access the REDCap project, locate the participant's record, and cancel or replace the existing appointment.

REDCap Entity manages the table of appointments.

A site is a COVID-19 testing site. A study coordinator or REDCap admin must define each site before appointment blocks for that site can be created.

REDCap Entity manages the site data. A study coordinator or REDCap admin can populate the site table by accessing the Define Sites page. It allows for CRUD operations on sites for this project.

Each site allows the configuration of a long name, short name, appointment duration, address, open time, close time, closed days of the week, and the number of appointment days to build out in advance. The open and close times are bounds on the generation of appointments.

NOTE: All cron management features have been disable as of 0.5.2. This is to allow us (CTS-IT) to more easily manage manual appointment block creation until we can add a per-site, per-weekday, start and stop times. Sorry for the inconvenience. The docs will be over-hauled when that feature is completed.

An appointment block is a fixed block of time at a single site. Appointment blocks must be created for a site before a research participant can schedule an appointment at that site.

This module manages appointment block creation. The script that makes the appointment blocks can be run manually or automatically. The appointment blocks are generated when a study coordinator presses the Manually generate new appointments button of the Define sites page or automatically by a cron job that runs each day.

Appointment block creation uses the appointment horizon, site id, open, close, closed_days, start_date, and appointment duration attributes for each site to generate records in the appointments table. It will create appointment horizon days of appointment blocks for each site if those blocks do not already exist.

The module will define a cron job that runs daily to assure appointment_horizon days of appointment blocks exist at all times. Whether you let the cron job make the appointments or use the Manually generate new appointments button to make them, the underlying code will create appointment blocks starting on the next day. For example, if you configure a site to have three days of appointments, then click the button on Monday, the script will create appointments on Tuesday, Wednesday, and Thursday. If the same site were closed on Wednesday, the script would create appointments only on Tuesday and Thursday.

As of release 0.6.0, the most precise way to make appointment blocks is to set appointment_horizon days to zero and set start_date to the precise date for which you want to make appointments. Select the sites that need new appointment blocks and click Manually generate new appointments. Repeat this process for each site date that needs new appointment blocks.

The test_data folder includes RScript to generate test datasets for the ICF, Questionnaire and Mini Questionnaire. Together, these import files can speed the process of testing the custom code used in these project. To make test data. Open the R Project in the test_data folder and run make_test_data.R. If you provide a file called replacement_demographics.csv and it has the columns first_name, last_name, email, and phone1 the RScript will replace the first_name, email, and phone on each demographic record.

To load test data, erase all data in the project, then load these three files from ./test_data/output/:

all_baseline_data.csv

There are additional mini_questionnaire_0* files, but they might not be useful for typical testing. They fill in the mini-question with diminishing frequency, but they do it out of sync with the Appointment and Result forms. That is probably not helpful, but they are provided here should they prove useful.

To clone a development project into a production project, follow the steps below. Note: This procedure assumes you are copying a project within a REDCap host.

1. Locate your development project and copy it using Project Setup, Other Functionality, Copy the project.

2. Set the details on the new project 'First Responder COVID-19 Testing - Production'.

3. Also copy the following project attributes:

   • All records/responses (NNN records total)
   • All users and user rights
   • All users roles
   • All reports
   • All report folders
   • All data quality rules
   • All Project Folders
   • All settings for Survey Queue and Automated Survey Invitations
   • All project bookmarks
   • All custom record status dashboards
   • All settings for External Modules (modules will be disabled by default)
   • All alerts & notifications

4. Enable Project Overlay Banner module. Set text to This is the real, production project. It is under construction and not ready for live data. Set the CSS to something like this to change the BG color to yellow

   #project-overlay-banner {
       /* position and z-index cause the banner to appear to float over the page */
       position: fixed;
       z-index: 1000;
   
       opacity: 0.8;
   
       --bg-color: #008888;
       background-color: var(--bg-color);
   
       padding: 1%;
   
       width: 100%;
   
       text-align: center;
   }
   

5. Enable the FR Covidata module.

6. Configure the FR Covidata module identify to set Which location ID is this project for? (0-15). Change this to not match the location in the development project.

7. Configure the FR Covidata module identify to set Which instrument is used for appointments? In the included REDCap XML files, the form is named "Appointments".

8. Configure the FR Covidata module to indicate which repeat type is used for repeats: Repeating instances or Individual Events. In the included REDCap XML files, events are used.

9. Use a MySQL client to load the site data from redcap_entity_test_site_data.sql.

10. Adjust the project_ids referenced on those just-loaded sites by editing and running a copy of redcap_entity_test_site_update.sql

11. Access Define Sites to make any needed changes to the site definitions.

12. Generate the initial appointment blocks by accessing Define Sites, selecting the appropriate sites, and clicking Manually generate new appointments.

13. Add an API token for the data manager and send the token to be integrated into Rscript-based tools that need it.

14. Assign User Rights privileges to the Study team lead so they can make roles and adjust user rights for their team.

15. Delete reports that are only relevant in the development.

16. Edit Alerts to remove testing email addresses in the To: field, set From addresses to something reasonable, "TEST" banner at the top of the emails, and "TESTING:" from the subject lines.

17. Switch the project to production mode.

18. Disable the Project Overlay Banner module.

19. Add the Public Survey URL to the public-facing landing page.

20. You have now completed the project deployment.