vignettes/vignette_user.md

In kamclean/collaborator: Scalable multi-centre research using R and REDCap

Collaborator: Redcap User Management

Management of user rights in REDCap becomes increasingly laborious as the scale of the research project expands (e.g. with the number of users, and the number of data access groups). Here are a series of functions to understand and manage users on a project

For a user to be able to use a REDCap project, there are two prerequisites they must have:

1. User account - This username allows the user to log onto the REDCap instance.

2. User rights - This is required to access a specific REDCap project, and determines the capabilities the user has (e.g. to access certain forms, to be restricted to a specific data access group, to import/export data, etc)

Create REDCap Accounts

REDCap user accounts cannot be generated via R at present, and need to be manually uploaded at present (however there is capability to bulk upload via a csv file). This function can be used to generate the csv file in the exact format required for direct upload via the control centre.

It requires a dataframe of at least 4 mandatory columns (corresponding to: username, first name, last name, and email address) and 4 optional columns (corresponding to: institution, sponsor, expiration, comments). All optional columns will be blank unless otherwise specified.

library(collaborator);library(dplyr)

# Create example of new users output from user_role()
collaborator::user_role(redcap_project_uri = Sys.getenv("collaborator_test_uri"),
                        redcap_project_token = Sys.getenv("collaborator_test_token"),
                        remove_id = F)$all %>%
  dplyr::filter(role_name=="collaborator") %>% head(10) %>%
  dplyr::select(username, email, firstname, lastname, data_access_group) %>%

  # Format these new users to allow account creation
  collaborator::user_import(username = "username", first_name = "firstname", last_name = "lastname",
                            email = "email", institution = "data_access_group") %>%

  knitr::kable()

Username First name Last name Email address Institution ID Sponsor username Expiration Comments a\_barker Aleesha Barker hospital\_a a\_hanna Aleesha Hanna hospital\_d a\_hicks Alyssa Hicks hospital\_e a\_lees Aleesha Lees hospital\_h a\_nicholson Alyssa Nicholson hospital\_i c\_avila Chanice Avila c\_gould Chanice Gould hospital\_b c\_kent Chanice Kent hospital\_f c\_michael Chanice Michael hospital\_h f\_almond Fleur Almond

View Project Users and Data Access Groups (DAGs)

Use user_role() to count the number of unique user “roles” within the REDCap Project (e.g. the number of unique combinations of user rights). The users without an allocated data access group or role will be listed as NA. Please note those without an assigned role will have the minimum user righst by default, but those without an assigned data access group will have access to ALL data on the project.

The output from user_role() is a nested dataframe of:

1). $all: A dataframe of all users and their allocated role on the redcap project.

• By default the user name and emails are not provided (however this can be by changing “remove_id” to FALSE)

# Example output from user_role()
# please note all names are randomly generated
user_role <- collaborator::user_role(redcap_project_uri = Sys.getenv("collaborator_test_uri"),
                                     redcap_project_token = Sys.getenv("collaborator_test_token"))

knitr::kable(user_role$all)

role\_name role\_id username data\_access\_group data\_access\_group\_id admin U-82337CEWAF kmclean NA NA collaborator U-3319YWM9ND a\_barker hospital\_a 4117 collaborator U-3319YWM9ND a\_hanna hospital\_d 4120 collaborator U-3319YWM9ND a\_hicks hospital\_e 4121 collaborator U-3319YWM9ND a\_lees hospital\_h 4124 collaborator U-3319YWM9ND a\_nicholson hospital\_i 4125 collaborator U-3319YWM9ND c\_avila NA NA collaborator U-3319YWM9ND c\_gould hospital\_b 4118 collaborator U-3319YWM9ND c\_kent hospital\_f 4122 collaborator U-3319YWM9ND c\_michael hospital\_h 4124 collaborator U-3319YWM9ND f\_almond NA NA collaborator U-3319YWM9ND f\_galindo hospital\_a 4117 collaborator U-3319YWM9ND f\_livingston hospital\_g 4123 collaborator U-3319YWM9ND h\_herman hospital\_d 4120 collaborator U-3319YWM9ND h\_mustafa hospital\_i 4125 collaborator U-3319YWM9ND k\_ashton NA NA collaborator U-3319YWM9ND k\_gibbons hospital\_b 4118 collaborator U-3319YWM9ND k\_marks hospital\_h 4124 collaborator U-3319YWM9ND l\_cervantes hospital\_a 4117 collaborator U-3319YWM9ND l\_jensen hospital\_e 4121 collaborator U-3319YWM9ND l\_paine hospital\_j 4126 collaborator U-3319YWM9ND m\_owens hospital\_j 4126 collaborator U-3319YWM9ND r\_bradford hospital\_c 4119 collaborator U-3319YWM9ND r\_hodge hospital\_i 4125 collaborator U-3319YWM9ND r\_ochoa hospital\_i 4125 collaborator U-3319YWM9ND s\_ayala NA NA collaborator U-3319YWM9ND s\_beech hospital\_b 4118 collaborator U-3319YWM9ND s\_hardy hospital\_e 4121 collaborator U-3319YWM9ND s\_knights hospital\_f 4122 collaborator U-3319YWM9ND s\_moses hospital\_h 4124 collaborator U-3319YWM9ND tdrake hospital\_d 4120 collaborator U-3319YWM9ND y\_andersen NA NA collaborator U-3319YWM9ND y\_cameron hospital\_d 4120 collaborator U-3319YWM9ND y\_holder hospital\_e 4121 collaborator U-3319YWM9ND y\_mackie hospital\_g 4123 collaborator U-3319YWM9ND y\_odoherty hospital\_j 4126 manager U-591P8EWTJY eharrison hospital\_c 4119

ii). $sum: A dataframe of each role on REDCap, alongside the total and list of usernames with those rights. These can be used in later functions to assign or change user roles.

• By default the exact rights these roles have are not shown (however this can be by changing “show_rights” to TRUE)

knitr::kable(user_role$sum)

role\_name role\_id n username admin U-82337CEWAF 1 kmclean collaborator U-3319YWM9ND 35 a\_barker , a\_hanna , a\_hicks , a\_lees , a\_nicholson , c\_avila , c\_gould , c\_kent , c\_michael , f\_almond , f\_galindo , f\_livingston, h\_herman , h\_mustafa , k\_ashton , k\_gibbons , k\_marks , l\_cervantes , l\_jensen , l\_paine , m\_owens , r\_bradford , r\_hodge , r\_ochoa , s\_ayala , s\_beech , s\_hardy , s\_knights , s\_moses , tdrake , y\_andersen , y\_cameron , y\_holder , y\_mackie , y\_odoherty manager U-591P8EWTJY 1 eharrison

Manage Project Data Access Groups (DAGs) and Project Users

The automatic management of users and data access groups (DAGs) has several important advantages over the manual method:

• Once set-up, it involves a fraction of the time and labour (compared to doing so manually), and can be easily repeated using R. This enables multicentre research using REDCap to become easily scalable irrespective of the number of users and number of data access groups.

• It significantly reduces allocation errors (e.g. users being allocated to incorrect DAGs).

dag_manage()

Effective management of DAGs is essential to ensure access to data is restricted to only appropriate users - this can be done using dag_manage().

If you simply want to view the current DAGs on the project, just enter the URL and TOKEN. However, if you wish to add or remove DAGs, use the import and remove arguments. It is highly recommended you keep the DAG name limited to 18 characters, with no special characters or spaces to avoid issues with duplicate or altered DAG names on the REDCap project.

• When importing, the “data_access_group_name” will be the DAG imported, and “unique_group_name” the automatically generated REDCap name.

dag_manage(redcap_project_uri = Sys.getenv("collaborator_test_uri"),
           redcap_project_token = Sys.getenv("collaborator_test_token"),
           import = "hospital_n", remove = "hospital_w") %>%
  knitr::kable()

data\_access\_group\_name unique\_group\_name status hospital m hospital\_m - hospital\_a hospital\_a - hospital\_b hospital\_b - hospital\_c hospital\_c - hospital\_d hospital\_d - hospital\_e hospital\_e - hospital\_f hospital\_f - hospital\_g hospital\_g - hospital\_h hospital\_h - hospital\_i hospital\_i - hospital\_j hospital\_j - hospital\_k hospital\_k - hospital\_l hospital\_l - hospital\_m hospital\_mb - hospital\_n hospital\_n -

The dag_manage() function output provides a list of all DAGs with a breakdown of the outcome:

• The outcome of the DAGs will be displayed (“status”) - either unchanged (“-”), “removed” or “added”.

user_manage()

Effective management of users is essential to ensure users have the user rights and data access appropriate to them - this can be done using user_manage().

Usernames to manage can be supplied to the users argument as a vector or as a tibble with at least 1 column (“username”). If you simply want to view the current users on the project, just enter the URL and TOKEN and you will be shown the output from user_role().

newuser <- tibble::tibble("username" = "gs2s1005789")

knitr::kable(newuser)

username gs2s1005789

There are 2 main ways to manage users:

1. Add or amend users:

The role and/or DAG can be specified for ALL users supplied to users (“role” and “dag”), or for individual users by adding a “role” and/or “dag” column to users with the appropriate value for each username. If present, the information from the columns will take precedence.

• role: This must exactly match either a role name or ID, or a username with the appropriate role (see the output from user_role())

• dag: This must exactly match the “unique_group_name” of an existing DAG (see the output from dag_manage())

In order to prevent errors due to users not being assigned to specific roles and DAGs, there will be an error message if either of these are listed as NA. If you want a user to not have a specific role or DAG, then these must be explicitly listed as “none”.

add_outcome <- user_manage(redcap_project_uri = Sys.getenv("collaborator_test_uri"),
                           redcap_project_token = Sys.getenv("collaborator_test_token"),
                           users = newuser %>% mutate("role" = "manager", "dag" = "none"))

This function output provides a breakdown of the outcome for each username in users:

1. correct: Users who have been allocated correctly according to the information provided, and provides details on this change.

knitr::kable(add_outcome$correct)

username action role dag gs2s1005789 add NA –> manager NA –> none

1. error: Users who have NOT been allocated correctly according to the information provided, and provides details on what the current status of that user is / what the outcome should have been according to the information supplied. This may be an incorrect specification of the username, role, or DAG.

knitr::kable(add_outcome$error)

username action status\_intended role role\_intended dag dag\_intended

2. Remove users:

This can be specified for ALL users supplied to users (“remove==T”) or for individual users by adding a “remove” column to users with the value TRUE for each username wanting to be removed (this allows users to be added and removed at the same time).

• If present, the information from the columns will take precedence.

remove_outcome <- user_manage(redcap_project_uri = Sys.getenv("collaborator_test_uri"),
                              redcap_project_token = Sys.getenv("collaborator_test_token"),
                              users = newuser$username, remove = T)

knitr::kable(remove_outcome$correct)

username action role dag gs2s1005789 remove manager –> NA none –> NA

kamclean/collaborator documentation built on Nov. 17, 2023, 3:52 a.m.