R/redcap-file-upload-oneshot.R
redcap_file_upload_oneshot.Rd
This function uses REDCap's API to upload a file.
redcap_file_upload_oneshot(
file_name,
record,
redcap_uri,
token,
field,
event = "",
verbose = TRUE,
config_options = NULL,
handle_httr = NULL
)
The name of the relative or full file to be uploaded into the REDCap project. Required.
The record ID where the file is to be imported. Required
The uri/url of the REDCap server typically formatted as "https://server.org/apps/redcap/api/". Required.
The user-specific string that serves as the password for a project. Required.
The name of the field where the file is saved in REDCap. Required
The name of the event where the file is saved in REDCap. Optional
A boolean value indicating if message
s should be printed
to the R console during the operation. Optional.
A list of options passed to httr::POST()
.
See details at httr::httr_options()
. Optional.
The value passed to the handle
parameter of
httr::POST()
.
This is useful for only unconventional authentication approaches. It
should be NULL
for most institutions. Optional.
Currently, a list is returned with the following elements:
success
: A boolean value indicating if the operation was apparently
successful.
status_code
: The
http status code
of the operation.
outcome_message
: A human readable string indicating the operation's
outcome.
records_affected_count
: The number of records inserted or updated.
affected_ids
: The subject IDs of the inserted or updated records.
elapsed_seconds
: The duration of the function.
raw_text
: If an operation is NOT successful, the text returned by
REDCap. If an operation is successful, the raw_text
is returned as
an empty string to save RAM.
Currently, the function doesn't modify any variable types to conform to
REDCap's supported variables. See validate_for_write()
for a helper
function that checks for some common important conflicts.
The function redcap_upload_file_oneshot()
is soft-deprecated
as of REDCapR 1.2.0.
Please rename to redcap_file_upload_oneshot()
.
The official documentation can be found on the 'API Help Page' and 'API Examples' pages on the REDCap wiki (ie, https://community.projectredcap.org/articles/456/api-documentation.html and https://community.projectredcap.org/articles/462/api-examples.html). If you do not have an account for the wiki, please ask your campus REDCap administrator to send you the static material.
# \dontrun{
# Define some constants
uri <- "https://bbmc.ouhsc.edu/redcap/api/"
token <- "D70F9ACD1EDD6F151C6EA78683944E98" # The simple project -pid 213
field <- "mugshot"
event <- "" # only for longitudinal events
# Upload a single image file.
record <- 1
file_path <- system.file("test-data/mugshot-1.jpg", package = "REDCapR")
REDCapR::redcap_file_upload_oneshot(
file_name = file_path,
record = record,
field = field,
redcap_uri = redcap_uri,
token = token
)
#> Error in eval(expr, envir, enclos): object 'redcap_uri' not found
# Upload a collection of five images.
records <- 1:5
file_paths <- system.file(
paste0("test-data/mugshot-", records, ".jpg"),
package="REDCapR"
)
for (i in seq_along(records)) {
record <- records[i]
file_path <- file_paths[i]
REDCapR::redcap_file_upload_oneshot(
file_name = file_path,
record = record,
field = field,
redcap_uri = redcap_uri,
token = token
)
}
#> Error in eval(expr, envir, enclos): object 'redcap_uri' not found
# }