Learn R Programming

redcapAPI (version 2.10.0)

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:

ColumnDescription
recordThe record ID
fieldThe name of the field in which the file is stored.
eventThe name of the event associated with the file.
repeat_instanceFor repeat instances, the instance associated with the file.
is_exportedlogical indicating if the file was successfully exported.
saved_toThe file path to which the file was saved.
errorIf 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.

See Also

exportFiles()

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
}


Run the code above in your browser using DataLab