Security Access Groups

Table of Contents

• Introduction
  • FAQ
  • How do you use the module?
• Module Configuration
  • Default Email Settings
• Control Center Page
  • Users Tab
    • Import File Format
  • Security Access Groups Tab
    • SAG Import File Format
  • Reports Tab
• Project Page
  • Project Status Tab
    • Placeholders
  • Alert Log Tab
  • Logging
• Translation (i18n / l10n)
  • General Information
  • Available Translations
  • Limitations
    • Right-to-Left Languages
  • Translating the Module
    • Creating a new translation
    • Correcting an existing translation
• Miscellaneous
  • Searching
    • General
    • "AND" Searches
    • "OR" Searches
    • Exact Phrase Searches
    • Regular Expression Searches
• PHP and REDCap Version Support
• Changelog

Introduction

FAQ

1. What is it?

   This is an External Module that allows REDCap administrators to create and manage Security Access Groups in a REDCap system.

2. What are Security Access Groups?

   Security Access Groups (SAGs) are used to restrict which user rights a REDCap user can be granted in a project. SAGs do not define the rights a user will have in a given project; rather, they define the set of allowable rights the user is able to be granted. SAGs are defined at the system level and are used in any project that has this module enabled.

3. When would that be useful?

   For example, if your institution requires documentation of training for users to export data, you can create a SAG that does not allow the "Data Export Tool" User Right to be granted to users assigned it. Once a user completes training, they can be moved to a SAG that does allow the "Data Export Tool" User Right to be granted.
   
   In other words, you may want to provide different tiers of training to your users and only allow specific project-level user rights to users who have completed the appropriate training. Although this module does not administer or track training, it does handle eveything else.

4. Isn’t it the study team’s responsibility to manage user rights?

   Yes and no. As system administrators, we have the responsibility to ensure users of our system are adequately trained for the jobs they’ll be doing. Many users do not want to complete an hours-long training if they will only be entering data in a data collection instrument. You can give those users a shorter, focused training and assign them to a SAG that allows minimal user rights.

How do you use the module?

REDCap administrators first create SAGs using a menu in the Control Center. Once a SAG is created, users can be assigned to it in another tab of the same control center menu. When a user is assigned to a SAG, the user will only be able to be granted User Rights that are allowed by the SAG.

🚩	The module must be enabled in a project for it to restrict User Rights in that project. It is recommended that the module be enabled in all projects.

When the module is enabled in a project, it will check which rights are allowable for a user according to their SAG before granting any user rights to that user. The module intercepts all attempts to set user rights in a project, including

• Using the usual methods on the User Rights project page

• Using the Upload users, role, and assignments feature on the User Rights project page

• Using the REDCap API

All attempts to set user rights will be blocked if the user is not allowed to be granted the rights according to their SAG. Attempts to circumvent the module are detected and logged.

💡

The module ignores users who are currently expired in the project. This allows the user to remain in the project but prevents them from using their noncompliant user rights until those noncompliant rights are removed. The user can then be un-expired. The module provides a convenient way to expire users in a project on the Project Status tab.

Figure 1. Example of a user being blocked from being granted a User Right

---

Module Configuration

Default Email Settings

The control center module configuration page allows admins to set the default values for all alerts that can be sent to users and user rights holders from the project status page.

This is a convenient way to get up and running when you first enable the module, because many users likely will need to be notified.

Figure 2. EM Framework Config Options

ℹ️	Placeholders may be used in any of these default settings.

Table 1. EM Framework Management Config Options

Section	Option	Type	Description
User Alert Email Settings	User Alert Email Default Subject	Text	The default subject for emails sent to users.
	User Alert Email Default Body	Rich Text	The default body for emails sent to users.
	User Reminder Alert Email Default Subject	Text	The default subject for reminder emails sent to users.
	User Reminder Email Default Body	Rich Text	The default body for reminder emails sent to users.
User Rights Holder Alert Email Settings	User Rights Holders Alert Email Default Subject	Text	The default subject for emails sent to user rights holders.
	User Rights Holders Alert Email Default Body	Rich Text	The default body for emails sent to user rights holders.
	User Rights Holders Reminder Alert Email Default Subject	Text	The default subject for reminder emails sent to user rights holders.
	User Rights Holders Reminder Alert Email Default Body	Rich Text	The default body for reminder emails sent to user rights holders.
User Expiration Alert Email Settings	User Expiration Alert Email Default Subject	Text	The default subject for emails sent to users upon expiration.
	User Expiration Alert Email Default Body	Rich Text	The default body for emails sent to users upon expiration.
	User Rights Holders Alert Email Default Subject	Text	The default subject for emails sent to user rights holders upon expiration.
	User Rights Holders Alert Email Default Body	Rich Text	The default body for emails sent to user rights holders upon expiration.

---

Control Center Page

Users Tab

Figure 3. Users tab

This tab allows admins to assign users to SAGs. Users can be assigned to SAGs individually or in bulk using the Import User Assignments feature (see Import File Format).

Figure 4. User assignment

Figure 5. Users actions

Import File Format

The file used to import user assignments must be a CSV file with the following columns:

Column header	Description
username	The REDCap username of the user
sag_id	The SAG ID of the SAG to assign the user to. SAG IDs can be found on the Security Access Groups Tab of the module.

You can download a template import file using the dropdown in the menu or use the export file as a guide.

Figure 6. Confirmation popup of SAG assignment import

Security Access Groups Tab

Figure 7. Security Access Groups tab

This tab shows all SAGs that exist in the system. SAGs can be created, edited, and deleted from this tab. Click a SAG’s name to edit it.

💡	You can also Copy and Delete the SAG from the editor popup.

Figure 8. SAG editor

SAGs can also be created or edited in bulk by importing a CSV file using the dropdown options in the menu. See the SAG Import File Format for more information.

Figure 9. SAG dropdown options

When you import SAG definitions, you will have the opportunity to view and confirm any changes.

Figure 10. Confirmation popup of SAG import

SAG Import File Format

The file used to import SAGs must be a CSV file with the following columns:

Column header	Description / The User Right that is restricted	Possible values
sag_name	The display name of the SAG	The text of the SAG name
sag_id	If you are editing an existing SAG, this is the SAG ID of the SAG to edit. If you are creating a new SAG, this column should be left blank.	The text of the SAG ID
design	Project Design and Setup	0 - Not allowed 1 - Allowed
user_rights	User Rights	Prior to REDCap v14.1.0: 0 - Not allowed 1 - Allowed As of REDCap v14.1.0: 0 - No access 2 - Read only 1 - View & Edit Note: The counterintuitive values here break with the general pattern of this module (in which higher values correspond with more permissions) in order to aid in maintaining backwards compatibility and prevent errors with this very important permission.
data_access_groups	Data Access Groups	0 - Not allowed 1 - Allowed
dataViewing	Data Viewing Rights	0 - Only No access is allowed 1 - No access and Read only are allowed 2 - No access, Read only, and View & Edit are allowed 3 - All data viewing rights settings are allowed
dataExport	Data Export Rights	0 - Only No access is allowed 1 - No access and De-Identified are allowed 2 - No access, De-Identified, and Remove All Idenitifier Fields are allowed 3 - All data export rights settings are allowed
alerts	Alerts & Notifications	0 - Not allowed 1 - Allowed
reports	Reports & Report Builder	0 - Not allowed 1 - Allowed
graphical	Stats & Charts	0 - Not allowed 1 - Allowed
participants	Survey Distribution Tools	0 - Not allowed 1 - Allowed
calendar	Calendar & Scheduling	0 - Not allowed 1 - Allowed
data_import_tool	Data Import Tool	0 - Not allowed 1 - Allowed
data_comparison_tool	Data Comparison Tool	0 - Not allowed 1 - Allowed
data_logging	Logging	0 - Not allowed 1 - Allowed
file_repository	File Repository	0 - Not allowed 1 - Allowed
lock_record_customize	Record Locking Customization	0 - Not allowed 1 - Allowed
lock_record	Lock/Unlock Records	0 - Only Disabled is allowed 1 - Disabled and Locking / Unlocking are allowed 2 - All record locking settings are allowed
data_quality_design	Data Quality (create/edit rules)	0 - Not allowed 1 - Allowed
data_quality_execute	Data Quality (execute rules)	0 - Not allowed 1 - Allowed
mobile_app	REDCap Mobile App	0 - Not allowed 1 - Allowed
mobile_app_download_data	Allow user to download data for all records to the app?	0 - Not allowed 1 - Allowed
realtime_webservice_mapping	CDP/DDP Setup / Mapping	0 - Not allowed 1 - Allowed
realtime_webservice_adjudicate	CDP/DDP Adjudicate Data	0 - Not allowed 1 - Allowed
dts	DTS (Data Transfer Services)	0 - Not allowed 1 - Allowed
mycap_participants	Manage MyCap Participants	0 - Not allowed 1 - Allowed
record_create	Create Records	0 - Not allowed 1 - Allowed
record_rename	Rename Records	0 - Not allowed 1 - Allowed
record_delete	Delete Records	0 - Not allowed 1 - Allowed
random_setup	Randomization - Setup	0 - Not allowed 1 - Allowed
random_dashboard	Randomization - Dashboard	0 - Not allowed 1 - Allowed
random_perform	Randomization - Randomize	0 - Not allowed 1 - Allowed
data_quality_resolution_view	Data Quality Resolution - View Queries	0 - Not allowed 1 - Allowed
data_quality_resolution_open	Data Quality Resolution - Open Queries	0 - Not allowed 1 - Allowed
data_quality_resolution_respond	Data Quality Resolution - Respond to Queries	0 - Not allowed 1 - Allowed
data_quality_resolution_close	Data Quality Resolution - Close Queries	0 - Not allowed 1 - Allowed
double_data_reviewer	Double Data Entry - Reviewer	0 - Not allowed to be a reviewer 1 - Allowed
double_data_person	Double Data Entry - Person	0 - Not allowed to be either Person #1 or Person #2 1 - Allowed
api_export	API Export	0 - Not allowed 1 - Allowed
api_import	API Import/Update	0 - Not allowed 1 - Allowed
lock_record_multiform	Lock/Unlock *Entire* Records (record level)	0 - Not allowed 1 - Allowed

Reports Tab

Figure 11. Reports tab

This tab provides an easy way to see all users in the system that currently have user rights that do not comply with their current SAG. This can occur when the module is first enabled in a project or when a user is assigned to a new SAG.

The report options are as follows:

Report title	Description
Users with Noncompliant Rights (non-expired)	This report lists all users who are assigned to a SAG that does not allow the user to be granted all of the rights they currently have in a project. This report only includes users if they are not currently expired in the project(s).
Users with Noncompliant Rights (all)	This report lists all users who are assigned to a SAG that does not allow the user to be granted all of the rights they currently have in a project. This report includes all users, regardless of whether they are currently expired in the project(s).
Projects with Noncompliant Rights (non-expired)	This report lists all projects that have at least one user who is assigned to a SAG that does not allow the user to be granted all of the rights they currently have in the project. This report only includes users who have a non-expired user account.
Projects with Noncompliant Rights (all)	This report lists all projects that have at least one user who is assigned to a SAG that does not allow the user to be granted all of the rights they currently have in the project. This report includes all users, regardless of whether their user account is expired.
Users and Projects with Noncompliant Rights (non-expired)	This report lists every user and project combination in which the user is assigned to a SAG that does not allow the user to be granted all of the rights they currently have in the project. This report only includes users who are not currently expired in the project.
Users and Projects with Noncompliant Rights (all)	This report lists every user and project combination in which the user is assigned to a SAG that does not allow the user to be granted all of the rights they currently have in the project. This report includes all users, regardless of whether they are currently expired in the project.

Figure 12. Report example

💡

You can filter based on project status by including "project_status=" and then the status you want to filter on. For example, to only include projects that are in Production, you would use project_status=Production. To only include projects that are Completed, you would use project_status=Completed. To include both Production and Development projects, you would use project_status=Production | project_status=Development. See the Searching section for more information.

Figure 13. Filtering based on project status example

---

Project Page

Project Status Tab

The module adds a page that shows the status of all users in the project. The status of each user is determined by the user’s SAG and the rights they have in the project. The color of the row indicates whether the user is:

• Green - compliant with their SAG

• Red - non-compliant with their SAG

• Grey - expired in the project

You can also check the Noncompliant Rights column to see which rights the user has that are not allowed by their SAG.

💡

If you want to see only users who inappropriately have particular rights, you can use the search box. For example, if you are only interested in the User Rights and/or Project Design and Setup rights, type "user rights" | "project design" in the search box. See the Searching section for more information.

Figure 14. Project status tab

💡

If there are any users that are non-compliant with their SAG, you can use one of the Action buttons to send an email to the user, the user’s rights holders, or both. You can also expire the user from the project. An alert can optionally be sent to the user and/or the user’s rights holders when the user is expired.

Figure 15. Alert user

Figure 16. Remind user

Figure 17. Alert user rights holders

Figure 18. Remind user rights holders

Figure 19. Expire users

Figure 20. Alert users upon expiration

Figure 21. Alert user rights holders upon expiration

Placeholders

The following placeholders can be used in the email subject and body fields in alerts:

Placeholder	Audience	Description
[sag-user]	Project User	The user’s username
[sag-user-fullname]	Project User	The user’s full name
[sag-user-email]	Project User	The user’s email address
[sag-user-sag]	Project User	The user’s current security access group
[sag-rights]	Project User	A formatted list of the rights that do not conform with the user’s security access group.
[sag-project-title]	Any	The title of the project
[sag-users]	User Rights Holders	A formatted list of usernames
[sag-user-fullnames]	User Rights Holders	A formatted list of users' full names
[sag-user-emails]	User Rights Holders	A formatted list of user emails
[sag-user-sags]	User Rights Holders	A formatted list of users' current security access groups
[sag-users-table]	User Rights Holders	A formatted table of usernames, full names, email addresses, and SAGs
[sag-users-table-full]	User Rights Holders	A formatted table of usernames, full names, email addresses, SAGs, and non-compliant rights
[sag-expiration-date]	Any (only available in User Expiration alerts)	The date the user will be expired from the project

💡	You can also use any REDCap Smart Variables, although few will be relevant in this context.

Alert Log Tab

The module provides a table of all alerts sent and scheduled in the project.

💡	Scheduled reminders can be canceled from this tab.

Figure 22. Alert log tab

Figure 23. Alert preview example

💡	Use the search bar to search for the text of an alert, the username of the user the alert is about, or the username of the user the alert is being sent to, and more. See the Searching section for more information.

Logging

One of the benefits of using this module is the enhanced logging it provides. The module creates detailed logs in the project’s own logs for all changes to user rights, including

• When a user is added to a project with custom rights

• When a user is added to a project in an existing User Role

• When a user’s rights are changed

• When a role’s rights definition is changed

• When a user is added/removed from a user role

• When users are imported into a project via CSV

• When a user’s rights are changed via CSV import

• When roles are imported into a project via CSV

• When a user is assigned to a role via CSV import

• When a user is added to a project via the API

• When a user’s rights are changed via the API

• When user roles are imported/changed via the API

• When a user is assigned to a role via the API

Figure 24. Example log of a user’s rights being changed

Figure 25. Example log of a role’s rights being changed

---

Translation (i18n / l10n)

General Information

The module is capable of being translated into languages other than English via the External Module Framework’s language selection feature. To set the language for the module system-wide, go to Control Center > External Modules > Manage External Modules and click the "Configure" button for the module. Then select the language you want to use from the "Language" dropdown and click "Save".

You can override the system-wide language at the project level by visiting the Project Module Manager and clicking the "Configure" button for the module. Then select the language you want to use from the "Language" dropdown and click "Save".

🚩	There are parts of the module that are not translated by the module itself, but instead rely on REDCap’s built-in language translation system. These include the names of the user rights and associated descriptions.

Available Translations

These languages are currently available to be used in the module:

• English (default)

• Arabic (عربي)

• Bangla (বাংলা)

• Chinese (中文)

• French (Français)

• German (Deutsch)

• Hindi (हिंदी)

• Italian (Italiana)

• Portuguese (Português)

• Spanish (Español)

• Ukrainian (українська)

• Urdu (اردو)

Limitations

Right-to-Left Languages

Currently there is limited support for RTL lanuages. The module will display RTL languages correctly, but the structure/formatting of UI elements will still be LTR. There are options for more fully supporting RTL, but this will be low priority unless we hear from groups that need this feature.

Translating the Module

The translations provided with the module were created using automatic translation software and may not be accurate. If you would like to correct a translation or contribute a new translation, please follow the instructions below.

Creating a new translation

If you want to translate the module into a new language, first fork the main branch of the module’s Github repository. Next, follow these steps:

1. Find the lang directory in the module’s source code.

2. Copy the English.ini file and change the name of the copy to the language you want to translate to. Name the file with the English name for the language (capitalized) followed by the language’s endonym (using that language’s glyphs) in parentheses. For example, if you want to translate the module into Japanese, you would name the file Japanese (日本語).ini.

3. Open the file you just created in a text editor and translate the text on the right side of the equal sign for each line. For example, if you wanted to translate the text Introduction into Japanese, you would change the line status_ui_3 = "Introduction" to status_ui_3 = "序章".

4. Repeat the process for each line.

5. Save the file and upload it to the "lang" folder of the module’s source code.

6. Submit a pull request with your changes to the main branch of the Github repository.

Correcting an existing translation

If you want to correct an existing translation, you can do so by following these steps:

1. Find the lang directory in the module’s source code.

2. Open the file for the language you want to correct in a text editor.

3. Correct the text on the right side of the equal sign for each line you want to change.

4. Save the file and upload it to the "lang" folder of the module’s source code.

5. Submit a pull request with your changes to the main branch of the Github repository.

---

Miscellaneous

Searching

General

Many of the tables in the module have a search box that can be used to filter the table. The search box will search all columns in the table.

For example, if you want to find all users that are currently assigned to the SAG whose label has the word 'Nothing' in it, you can type 'Nothing' in the search box and the table will be filtered to only show rows that have the text 'Nothing' in any column.

Figure 26. Searching example

"AND" Searches

By default, the search box will be an 'AND' seach, meaning that it will split your search term into separate words and only show results that match all of those search words. For example, if you type 'joe admin' in the search box, the table will be filtered to only show rows with BOTH 'joe' AND 'admin' in any column. It will not show rows that have either 'joe' or 'admin' but it will show rows that have e.g., 'admin' in column 1 and 'joe' in column 2.

Figure 27. AND example

"OR" Searches

If you want to show all rows that match one value OR match another value, you have to use an "OR" search.

You can use the "|" operator to search for multiple terms like this in an either/or manner. For example, if you want to find all users with the username "alice" or "bob", you can type "alice | bob" in the search box and the table will be filtered to only show users with "alice" or "bob" in any column.

💡	including the '|' symbol has the side effect of making the search a Regular Expression search (see below).

Figure 28. OR example

Exact Phrase Searches

If you want to filter based on a phrase, you can out your phrase in double quotes. For example, if you want to find all rows with the exact phrase 'joe admin' you can type '"joe admin"' in the search box and the table will be filtered to only show rows with 'joe admin' in any column.

Figure 29. Exact phrase example

Regular Expression Searches

By including a '|' character anywhere in your search term, your search turns into a Regular Expression search. This allows you to compose complex searches that are not possible with the default search.

Figure 30. Regular Expression example - showing all rows where a "d" is followed by any number of letters and then an "n" - as in "admin" and "dan"

---

PHP and REDCap Version Support

	REDCap v13.7.24	REDCap v13.11.4	REDCap v14.0.0
PHP v7.4.5
PHP v8.2

Changelog

See the releases page for a full changelog.