fileRepositoryMethods {redcapAPI}

Export, Import, or Delete Multiple Files from the File Repository

Description

These methods enable the user to export, import, or delete entire folders of files from the file repository. These actions may be done recursively to include subfolders as well.

Usage

exportFileRepository(
  rcon,
  folder_id,
  dir = getwd(),
  dir_create = FALSE,
  recursive = FALSE,
  ...
)

importFileRepository(rcon, dir, folder_id = numeric(0), ...)

deleteFileRepository(rcon, folder_id, recursive = FALSE, ...)

## S3 method for class 'redcapApiConnection'
exportFileRepository(
  rcon,
  folder_id = numeric(0),
  dir = getwd(),
  dir_create = FALSE,
  recursive = FALSE,
  ...,
  error_handling = getOption("redcap_error_handling"),
  config = list(),
  api_param = list()
)

## S3 method for class 'redcapApiConnection'
importFileRepository(
  rcon,
  dir,
  folder_id = numeric(0),
  dag_id = numeric(0),
  role_id = numeric(0),
  recursive = FALSE,
  ...,
  error_handling = getOption("redcap_error_handling"),
  config = list(),
  api_param = list()
)

## S3 method for class 'redcapApiConnection'
deleteFileRepository(
  rcon,
  folder_id,
  recursive = FALSE,
  ...,
  confirm = c("ask", "no", "yes"),
  error_handling = getOption("redcap_error_handling"),
  config = list(),
  api_param = list()
)

Arguments

rcon

A redcapConnection object.

folder_id

integerish(0/1) The folder ID with the files to download. If length 0, defaults to the top-level directory.

dir

character(1). A directory on the local system to which the files are to be saved. Defaults to the working directory.

dir_create

logical(1). When TRUE create the directory dir if it does not already exist. Defaults to FALSE. If dir does not exist and dir_create = FALSE, an error is thrown.

dag_id

integerish(0/1) The ID of a data access group. When provided, access to the folder will be restricted to the DAG.

role_id

integerish(0/1) The ID of a role. When provided, access to the folder will be restricted to users with that role.

recursive

logical(1). When TRUE, export all subfolders and their files as well.

confirm

character. One of c("ask", "no", "yes"). When "ask", user will be prompted to confirm the deletion. When "no", the function will terminate with no action. When "yes", the function will proceed without confirmation (useful for automated processes).

...

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

deleteFileRepository will only delete files and cannot delete folders.

Deleted files will remain in the recycling bin for up to 30 days.

Value

exportFileRepository returns a data frame with the locations to which the files were saved on the local system. It has the columns:

directory	The directory in which the file is saved.
filename	The name of the saved file.

importFileRepository returns a data frame with the locations to which the files were saved on the local system. It has the columns:

directory	The directory in which the file is saved.
filename	The name of the saved file.

deleteFileRepository returns a data frame listing the files that were deleted from the file repository. It has the columns:

folder_id	The REDCap assigned ID number for the folder. This will be NA for files.
doc_id	The REDCap assigned ID number for the file.
name	The filename of the deleted files.
parent_folder	The folder ID of parent folder.

Functions

• exportFileRepository(): Export multiple files from the File Repository.

• importFileRepository(): Import multiple files to the File Repository.

• deleteFileRepository(): Delete multiple files from the File Repository.

See Also

exportFromFileRepository(),
importToFileRepository(),
deleteFromFileRepository(),
exportFileRepositoryListing(),
createFileRepositoryFolder()

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())
             
save_location <- tempdir()

# Export the top-level file repository folder
exportFileRepository(rcon, 
                     folder_id = numeric(0), 
                     dir = save_location)
                     
# Export the entire repository 
exportFileRepository(rcon, 
                     folder_id = numeric(0), 
                     dir = save_location, 
                     recursive = TRUE)
                     
# Export a file repository folder below the top-level
exportFileRepository(rcon, 
                     folder_id = 12345, 
                     dir = save_location)
                     
# Import the files from a folder to the top-level file repository
importFileRepository(rcon, 
                     dir = "path/to/folder")
                     
# Import the files from a folder to sub folder of the file repository
importFileRepository(rcon, 
                     dir = "path/to/folder", 
                     folder_id = 12345) 
                     
# Import the files from a folder and assign to a specific 
# Data Access Group
importFileRepository(rcon, 
                     dir = "path/to/folder", 
                     dag_id = 789)  
                     
# Delete files from the top-level folder of the file repository
deleteFileRepository(rcon, 
                     folder_id = numeric(0))
                     
# Delete all the file sfrom the file repository
deleteFileRepository(rcon, 
                     folder_id = numeric(0), 
                     recursive = TRUE)                   

## End(Not run)