userMethods: Export, Import, or Delete Users and User Permissisons

In redcapAPI: Interface to 'REDCap'

Export, Import, or Delete Users and User Permissisons

Description

These methods enable the user to add and remove users from a project. They also enable the user to modify the permissions granted to each user within the project.

Usage

exportUsers(rcon, ...)

importUsers(rcon, data, ...)

deleteUsers(rcon, users, ...)

## S3 method for class 'redcapApiConnection'
exportUsers(
  rcon,
  dates = TRUE,
  labels = TRUE,
  form_rights = TRUE,
  ...,
  error_handling = getOption("redcap_error_handling"),
  config = list(),
  api_param = list()
)

## S3 method for class 'redcapApiConnection'
importUsers(
  rcon,
  data,
  consolidate = TRUE,
  refresh = TRUE,
  ...,
  error_handling = getOption("redcap_error_handling"),
  config = list(),
  api_param = list()
)

## S3 method for class 'redcapApiConnection'
deleteUsers(
  rcon,
  users,
  refresh = TRUE,
  ...,
  error_handling = getOption("redcap_error_handling"),
  config = list(),
  api_param = list()
)

Arguments

rcon	A redcapConnection object.
dates	logical(1). When TRUE, expiration dates are converted to a POSIXct object.
labels	logical(1). When TRUE the data export and form access rights are converted to factor objects.
form_rights	logical(1). When TRUE, the form rights will be transformed to one column per form. The API-provided character string is always returned with the format ⁠[form_name]:[access_code]⁠ and a comma separating each form.
users	character. Vector of unique user names to be deleted.
data	data.frame. Provides the user data for import. It must have a column titled username. All other columns are optional.
consolidate	logical(1). When TRUE, the form and data export access values will be read from the expanded columns. Otherwise, the consolidated values (as provided by the API export) are utilized.
refresh	logical(1). When TRUE, the cached data will be refreshed after the API action is complete.
...	Arguments to pass to other methods
error_handling	character(1). One of c("error", "null"). An option for how to handle errors returned by the API. see redcapError().
config	A named list. Additional configuration parameters to pass to httr::POST(). These are appended to any parameters in rcon$config.
api_param	A named list. Additional API parameters to pass into the body of the API call. This provides users to execute calls with options that may not otherwise be supported by redcapAPI.

Details

User project access fields (those not related to forms or exports) are mapped between coded and labeled values as:

Code	Label
0	No Access
1	Access

Form access fields are mapped as:

Code	Label
0	No Access
1	View records/responses and edit records (survey responses are read-only)
2	Read Only
3	Edit survey responses

Form export permission fields are mapped as:

Code	Label
0	No Access
1	Full Data Set
2	De-Identified
3	Remove Identifier Fields

Importing Users/User Roles

It is not required that the user provide a data frame with all of the fields available for modification. Only fields that are provided will be modified. The only required field for imports is the username field.

When setting permissions for a user project access fields, form access, and form export permissions, the user may provided any of the coded or labeled values above. The user data is passed through prepUserImportData() before sending it to the API; text values will be converted to the numeric value.

It is also permissible to use a column for each form individually, as can be exported via exportUsers(). With consolidate = TRUE, these settings will be consolidated into the text string expected by the API.

The REDCap API does not natively allow for modifying the rights of a user that is part of a User Role. When an attempt to modify the rights of a user in a User Role is made with this package, the user will be removed from the User Role, the rights modified, and then the User Role restored. This is done silently: be aware that modifications to a user's rights may not have an impact while the User Role is assigned.

Limitations

When importing via CSV, (as redcapAPI does by default) it appears that the form access rights are imported but may not always be reflected in the exported values. The form export rights do not appear to be imported when using the CSV format. We may be able to resolve this in the future using a JSON format.

Value

exportUsers returns a data frame with the columns:

username	The unique username for a user that can access the project.
email	The e-mail address associated with the user in the REDCap system.
firstname	The user's first name.
lastname	The user's last name.
expiration	The date at which the user's access to the project will expire.
data_access_group	The text name of the Data Access Group to which the user is assigned.
data_access_group_id	The REDCap assigned unique identifier of the Data Access Group.
design	Boolean flag indicating if the user has permissions to utilize the project design modules.
alerts	Boolean flag indicating if the user has permissions to utlize the alerts tools.
user_right	Boolean flag indicating if the user has permissions to modify user rights.
data_access_groups	Boolean flag indicating if the user has user has permission to assign user to Data Access Groups.
reports	Boolean flag indicating if the user has permissions to design reports.
stats_and_charts	Boolean flag indicating if the user has permissions to view the Statistics and Charts module.
manage_survey_participants	Boolean flag indicating if the user has permissions to manage survey participants.
calendar	Boolean flag indicating if the user has permissions to utilize the project calendar module.
data_import_tool	Boolean flag indicating if the user has permissions to use the data import tool.
data_comparison_tool	Boolean flag indicating if the user has permissions to use the data comparison tool.
logging	Boolean flag indicating if the user has permissions to view the project logs (audit trail).
file_repository	Boolean flag indicating if the user has permissions to access the project file repository.
data_quality_create	Boolean flag indicating if the user has permission create new data quality rules.
data_quality_execute	Boolean flag indicating if the user has permission to execute data quality rules.
api_export	Boolean flag indicating if the user has API export privileges.
api_import	Boolean flag indicating if the user has API import privileges.
mobile_app	Boolean flag indicating if the user has permissions to use the mobile app.
mobile_app_download_data	Boolean flag indicating if the user has permissions to download data on the mobile app.
record_create	Boolean flag indicating if the user has permission to create new records.
record_rename	Boolean flag indicating if the user has permission to rename existing records.
record_delete	Boolean flag indicating if the user has permission to delete records.
lock_records_all_forms	Boolean flag indicating if the user has permission to lock records across all forms.
lock_records	Boolean flag indicating if the user has permission to lock a records on individual forms.
lock_records_customization	Boolean flag indicating if the user has permission to customize record locking.
random_setup	Boolean flag indicating if the user has permission to set up randomization rules.
random_dashboard	Boolean flag indicating if the user has permission to view the randomization dashboard.
random_perform	Boolean flag indicating if the user has permission to perform record randomization.
forms	Character string listing form access rights for each form.
forms_export	Character string listing the form export rights for each form.

When form_rights = TRUE, additional columns are created that give the form access and form export rights in an individual column for each form. Form access rights columns have the naming pattern ⁠[form_name]_access⁠ and the form export rights columns have the naming pattern ⁠[form_name]_export_access⁠.

importUsers has no return value and displays a message indicating how many users were added or modified.

deleteUsers has no return value and displays a message indicating how many users were deleted.

Functions

• exportUsers(): Export users affiliated with a project.

• importUsers(): Add users or modify user permissions in a project.

• deleteUsers(): Remove users from a project.

See Also

exportUserRoles(),
importUserRoles(),
deleteUserRoles(),
exportUserRoleAssignments(),
importUserRoleAssignments()

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())
             
# Export users
exportUsers(rcon)

# Export users without additional form access variables
exportUsers(rcon, 
            form_rights = FALSE)
            
# Export users as raw data
exportUsers(rcon, 
            labels = FALSE)
            
            
# Import new permissions
NewData <- data.frame(username = "target_user", 
                      design = 0, 
                      api_export = 1, 
                      api_import = "No Access")
importUsers(rcon, 
            data = NewData)
            

# Remove a user from a project
deleteUsers(rcon, 
            users = "target_user")

## End(Not run)

redcapAPI documentation built on Sept. 13, 2023, 1:07 a.m.