This function uses REDCap's API to select and return data.
redcap_write_oneshot(
ds,
redcap_uri,
token,
overwrite_with_blanks = TRUE,
convert_logical_to_integer = FALSE,
verbose = TRUE,
config_options = NULL,
handle_httr = NULL
)
The base::data.frame()
or tibble::tibble()
to be imported into the REDCap project.
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.
A boolean value indicating if
blank/NA
values in the R data frame
will overwrite data on the server.
This is the default behavior for REDCapR,
which essentially deletes the cell's value
If FALSE
, blank/NA
values in the data frame
will be ignored. Optional.
If TRUE
, all base::logical columns
in ds
are cast to an integer before uploading to REDCap.
Boolean values are typically represented as 0/1 in REDCap radio buttons.
Optional.
A boolean value indicating if message
s should be printed
to the R console during the operation. The verbose output might contain
sensitive information (e.g. PHI), so turn this off if the output might
be visible somewhere public. 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 official documentation can be found on the 'API Help Page' and 'API Examples' pages on the REDCap wiki (i.e., 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.
if (FALSE) {
# Define some constants
uri <- "https://bbmc.ouhsc.edu/redcap/api/"
token <- "D70F9ACD1EDD6F151C6EA78683944E98"
# Read the dataset for the first time.
result_read1 <- REDCapR::redcap_read_oneshot(redcap_uri=uri, token=token)
ds1 <- result_read1$data
ds1$telephone
# Manipulate a field in the dataset in a VALID way
ds1$telephone <- paste0("(405) 321-000", seq_len(nrow(ds1)))
ds1 <- ds1[1:3, ]
ds1$age <- NULL; ds1$bmi <- NULL # Drop the calculated fields before writing.
result_write <- REDCapR::redcap_write_oneshot(ds=ds1, redcap_uri=uri, token=token)
# Read the dataset for the second time.
result_read2 <- REDCapR::redcap_read_oneshot(redcap_uri=uri, token=token)
ds2 <- result_read2$data
ds2$telephone
# Manipulate a field in the dataset in an INVALID way. A US exchange can't be '111'.
ds1$telephone <- paste0("(405) 321-000", seq_len(nrow(ds1)))
# This next line will throw an error.
result_write <- REDCapR::redcap_write_oneshot(ds=ds1, redcap_uri=uri, token=token)
result_write$raw_text
}