redcapAPI (version 2.8.0)

purgeRestoreProject: Purge and Restore Project Data

Description

These functions are primarily intended to assist with testing features of redcapAPI. Purging and restoring project data permits us to perform tests on different project structures without having to manage multiple projects or API tokens.

When purging project data, many of these actions may only be performed with a project in development status, as they are potentially destructive and may result in data loss. It is a good practice to back up your data and project structure before purging a project.

Usage

preserveProject(object, ...)
# S3 method for redcapApiConnection
preserveProject(
  object,
  ...,
  error_handling = getOption("redcap_error_handling"),
  config = list()
)
purgeProject(object, ...)
# S3 method for redcapApiConnection
purgeProject(
  object,
  arms = FALSE,
  events = FALSE,
  users = FALSE,
  user_roles = FALSE,
  dags = FALSE,
  records = FALSE,
  purge_all = FALSE,
  flush = TRUE,
  ...,
  error_handling = getOption("redcap_error_handling"),
  config = list()
)
restoreProject(object, ...)
# S3 method for redcapApiConnection
restoreProject(
  object,
  project_information = NULL,
  arms = NULL,
  events = NULL,
  meta_data = NULL,
  mappings = NULL,
  repeating_instruments = NULL,
  users = NULL,
  user_roles = NULL,
  user_role_assignments = NULL,
  dags = NULL,
  dag_assignments = NULL,
  records = NULL,
  flush = TRUE,
  ...,
  error_handling = getOption("redcap_error_handling"),
  config = list()
)
# S3 method for list
restoreProject(
  object,
  rcon,
  ...,
  error_handling = getOption("redcap_error_handling"),
  config = list()
)

Arguments

object, rcon

A redcapConnection object. Except in restoreProject.list, where object is a list of data frames to use in restoring the project.

...

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.

arms

Either logical(1) indicating if arms data should be purged from the project; or a data.frame for restoring arms data via importArms.

events

Either logical(1) indicating if events data should be purged from the project; or a data.frame for restoring events data via importEvents

users

Either logical(1) indicating if users data should be purged from the project; or a data.frame for restoring users data via importUsers. NOT YET IMPLEMENTED

user_roles

Either logical(1) indicating if user roles data should be purged from the project; or a data.frame for restoring user roles data via importUserRoles. NOT YET IMPLEMENTED

dags

Either logical(1) indicating if DAG data should be purged from the project; or a data.frame for restoring DAGs data via importDags. NOT YET IMPLEMENTED

records

Either logical(1) indicating if records data should be purged from the project; or a data.frame for restoring records data via importRecords

purge_all

logical(1). A shortcut option to purge all data elements from a project.

flush

logical(1). When TRUE, all caches in the connection object will be flushed after completing the operation. This is highly recommended.

project_information

data.frame for restoring data. Provides the project settings to load via importProjectInformation.

meta_data

A data.frame for restoring metadata data via importMetaData. The API does not support deleting metadata, but an import replaces the existing metadata.

mappings

A data.frame for restoring instrument-event mappings via importMappings. The API does not support deleting mappings, but an import replaces the existing mappings.

repeating_instruments

A data.frame for restoring repeating instruments configuration via importRepeatingInstrumentsEvents(). The API does not support deleting repeating instruments, but an import replaces the existing instruments. NOT YET IMPLEMENTED

user_role_assignments

A data.frame for restoring user-role assignments via importUserRoleAssignments. The API does not support deleting assignments, but an import replaces the existing assignments. NOT YET IMPLEMENTED.

dag_assignments

A data.frame for restoring DAG assignments via importDagAssignments. The API does not support deleting assignments, but an import replaces the existing assignments. NOT YET IMPLEMENTED.

Details

When restoring a project, all arguments are optional. Any argument that is NULL will result in no import being made. The order of reconstructing the project is (purging data occurs in the reverse order):

1. Update project information

2. Import Arms Data

3. Import Events Data

4. Import Meta Data

5. Import Mappings

6. Import Repeating Instruments

7. Import Users

8. Import User Roles

9. Import User-Role Assignments

10. Import Data Access Groups

11. Import Data Access Group Assignments

12. Import Records

Examples

if (FALSE) {
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())
             
# Preserve a project
preserveProject(rcon)

# Purge a project
purgeProject(rcon, 
             purge_all = TRUE)
                
# Restore a project
restoreProject(rcon)

}