exportFilesMultiple: Export Multiple Files From a Project

Description

This method enables the user to export multiple files from a REDCap project with a single call. The REDCap API only allows for one file to be exported per call, and the exportFiles() methods are written to mirror that limitation. This extension allows the user to pass vectors of arguments for records, fields, events, or repeat instances. Files that can be matched to any combination of these values will be exported.

Usage

exportFilesMultiple(
  rcon,
  record,
  field,
  event = NULL,
  dir,
  file_prefix = TRUE,
  ...
)
# S3 method for redcapApiConnection
exportFilesMultiple(
  rcon,
  record,
  field,
  event = NULL,
  dir,
  file_prefix = TRUE,
  repeat_instance = NULL,
  ...,
  quiet = TRUE
)

Value

Invisibly returns a data.frame with the following columns:

Column	Description
`record`	The record ID
`field`	The name of the field in which the file is stored.
`event`	The name of the event associated with the file.
`repeat_instance`	For repeat instances, the instance associated with the file.
`is_exported`	`logical` indicating if the file was successfully exported.
`saved_to`	The file path to which the file was saved.
`error`	If an error was encountered, the text of the error.

Arguments

rcon: A redcapConnection object.
record: character or integerish. The record ID in which the desired file is stored.
field: character. The field name in which the file is stored.
event: character or NULL. The event name for the file. This applies only to longitudinal projects. If the event is not supplied for a longitudinal project, the API will return an error message
dir: character(1). A directory/folder to which the file will be saved. By default, the working directory is used.
file_prefix: logical(1). Determines if a prefix is appended to the file name. The prefix takes the form [record_id]-[event_name]-[file_name]. The file name is always the same name of the file as it exists in REDCap.
...: Arguments to pass to other methods
repeat_instance: integerish or NULL. The repeat instance number of the repeating event or the repeating instrument. When available in your instance of REDCap, and passed as NULL, the API will assume a value of 1.
quiet: logical(1). When TRUE, any errors encountered while exporting files will be converted to messages.

Details

exportFilesMultiple will construct all combinations of the record, field, event, and repeat_instance arguments and attempt to export the file associated with each combination. Should any of these combinations produce an error (for example, if a record does not have a third repeat instance), the error is captured and returned with the output.

Examples

Run this code

if (FALSE) {
unlockREDCap(connections = c(rcon = "project_alias"),
             url = "your_redcap_url",
             keyring = "API_KEYs",
             envir = globalenv())

save_to_dir <- tempdir()

# Export files for multiple records
# Results are returned invisibly - saving to an object is
#   helpful to be able to view the results

Export <-
  exportFilesMultiple(rcon,
                      record = 1:4,
                      field = "file_upload_field",
                      event = "event_1_arm_1",
                      dir = save_to_dir)
Export

# Export files for multiple instances

Export <-
  exportFilesMultiple(rcon,
                      record = 1,
                      field = "file_upload_field",
                      event = "event_1_arm_1",
                      repeat_instance = 1:4,
                      dir = save_to_dir)
Export

# Export files for multiple records, fields, events, and instances

Export <-
  exportFilesMultiple(rcon,
                      record = 1:10,
                      field = c("registration", "waiver"),
                      events = c("event_1_arm_1", "event_2_arm_1"),
                      repeat_instance = 1:3,
                      dir = save_to_dir)
Export
}