purgeRestoreProject: Purge and Restore Project Data
In redcapAPI: Interface to 'REDCap'

purgeRestoreProject

R Documentation

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 class 'redcapApiConnection'
preserveProject(
  object,
  ...,
  error_handling = getOption("redcap_error_handling"),
  config = list()
)

purgeProject(object, ...)

## S3 method for class '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 class '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 class '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):

Update project information
Import Arms Data
Import Events Data
Import Meta Data
Import Mappings
Import Repeating Instruments
Import Users
Import User Roles
Import User-Role Assignments
Import Data Access Groups
Import Data Access Group Assignments
Import Records

Examples

## Not run: 
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)


## End(Not run)

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