fileMethods() R function from [redcapAPI]

Export, Import, or Delete Files to a Field in a REDCap Project

These methods enable to the user to export a file stored in a project field, import a file, or delete an existing file.


exportFiles(
  rcon,
  record,
  field,
  event = NULL,
  dir = getwd(),
  file_prefix = TRUE,
  ...
)

importFiles(
  rcon,
  file,
  record,
  field,
  event,
  overwrite = TRUE,
  repeat_instance = NULL,
  ...
)

deleteFiles(rcon, record, field, event, ...)

## S3 method for class 'redcapApiConnection'
exportFiles(
  rcon,
  record,
  field,
  event = NULL,
  dir = getwd(),
  file_prefix = TRUE,
  repeat_instance = NULL,
  ...
)

## S3 method for class 'redcapApiConnection'
importFiles(
  rcon,
  file,
  record,
  field,
  event = NULL,
  overwrite = TRUE,
  repeat_instance = NULL,
  ...
)

## S3 method for class 'redcapApiConnection'
deleteFiles(
  rcon,
  record = NULL,
  field = NULL,
  event = NULL,
  repeat_instance = NULL,
  ...
)

Arguments

rcon: A redcapConnection object.
record: character(1) or integerish(1). The record ID in which the desired file is stored.
field: character(1). The field name in which the file is stored.
event: character(1) 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
repeat_instance: integerish(1) 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.
file: character(1). The file path to the file to be imported.
overwrite: logical(1). When FALSE, the function checks if a file already exists for that record. If a file exists, the function terminates to prevent overwriting. When TRUE, no additional check is performed.
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

Returns

exportFiles invisibly returns the file path to which the exported file was saved.

importFiles invisibly returns TRUE when successful, or throws an error if the import failed.

deleteFiles invisible returns TRUE when successful, or throws an error if the deletion failed.

Details

These functions only export, import, or delete a single file.

When exporting, the file name cannot be changed; whatever name exists in REDCap is the name that will be used. The record ID and event name may be appended as a prefix.

Functions

exportFiles(): Export a file from a REDCap project.
importFiles(): Import a file to a REDCap project.
deleteFiles(): Delete a file from a REDCap project.

Examples


## Not run:

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

save_to_dir <- tempdir()              

# Export a file
exportFiles(rcon, 
            record = 1, 
            field = "file_upload_test", 
            dir = save_to_dir)
            
# Export a file for a specific event
exportFiles(rcon, 
            record = 1, 
            field = "file_upload_test",
            event = "event_1_arm_1", 
            dir = save_to_dir)

# Import a file 
importFiles(rcon,
            file = "file_to_upload.txt" 
            record = 1, 
            field = "file_upload_test")
           
# Delete a file
deleteFiles(rcon, 
            record = 1, 
            field = "file_upload_test")
## End(Not run)

fileMethods function