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: An option for how to handle errors returned by the API. see redcap_error
config: list Additional configuration parameters to pass to 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 user roles data should be purged from the project; or a data.frame for restoring user roles data via importRecords
purge_all: logical(1). A shortcut option to purge all data elements from a project.
flush: logical(1). If TRUE, the 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 doesn't support deleting metadata, but an import replaces the existing metadata.
mappings: A data.frame for restoring instrument-event mappings via importMappings. The API doesn't support deleting mappings, but an import replaces the existing mappings.
repeating_instruments: A data.frame for restoring repeating instruments configuration via importRepeatingInstrumentsEvents. The API doesn't 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 doesn't 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 doesn't 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