Imports records from a data.frame to a REDCap Database
importRecords(
rcon,
data,
overwriteBehavior = c("normal", "overwrite"),
returnContent = c("count", "ids", "nothing", "auto_ids"),
returnData = FALSE,
logfile = "",
...
)# S3 method for redcapApiConnection
importRecords(
rcon,
data,
overwriteBehavior = c("normal", "overwrite"),
returnContent = c("count", "ids", "nothing", "auto_ids"),
returnData = FALSE,
logfile = "",
force_auto_number = FALSE,
...,
batch.size = -1,
error_handling = getOption("redcap_error_handling"),
config = list(),
api_param = list()
)
A REDCap connection object as created by redcapConnection.
A data.frame to be imported to the REDCap project.
Character string. 'normal' prevents blank fields from overwriting populated fields. 'overwrite' causes blanks to overwrite data in the REDCap database.
Character string. 'count' returns the number of
records imported; 'ids' returns the record ids that are imported;
'nothing' returns no message; 'auto_ids' returns a list of pairs of all
record IDs that were imported. If used when force_auto_number = FALSE,
the value will be changed to 'ids'.
Logical. Prevents the REDCap import and instead returns the data frame that would have been given for import. This is sometimes helpful if the API import fails without providing an informative message. The data frame can be written to a csv and uploaded using the interactive tools to troubleshoot the problem. Please send us an e-mail if you find errors I haven't accounted for.
An optional filepath (preferably .txt) in which to print the
log of errors and warnings about the data.
If "", the log is printed to the console.
Arguments to be passed to other methods.
logical(1) If record auto-numbering has been
enabled in the project, it may be desirable to import records where each
record's record name is automatically determined by REDCap (just as it
does in the user interface). If this parameter is set to 'true', the
record names provided in the request will not be used (although they
are still required in order to associate multiple rows of data to an
individual record in the request), but instead those records in the
request will receive new record names during the import process.
NOTE: To see how the provided record names get translated into new auto
record names, the returnContent parameter should be set to 'auto_ids',
which will return a record list similar to 'ids' value, but it will have
the new record name followed by the provided record name in the request,
in which the two are comma-delimited.
Specifies size of batches. A negative value indicates no batching.
An option for how to handle errors returned by the API.
see redcap_error
list Additional configuration parameters to pass to
POST. These are appended to any parameters in
rcon$config.
list Additional API parameters to pass into the
body of the API call. This provides users to execute calls with options
that may not otherwise be supported by redcapAPI.
The REDCap API is fairly restrictive about what it will accept as valid data for import.
importRecords tries to simplify the process by allowing users to
submit data in any form recognized by the data dictionary. It is then converted
internally to the
appropriate text format for import. This means, for example, that a radio button value
where the code 1 is mapped to the label Guitar (defined in the user interface
with "1, Guitar"), the user can provide
either "1" or "Guitar" as a value and importRecords will translate it to the
code that the API expects.
While this provides a level of convenience for the user, it has some limitations when applied to checkbox values. When submitting checkbox values for import, it is strongly recommended that you submit either the code "0" (for unchecked), "1" (for checked), or the labels "Unchecked" and "Checked".
In particular, when the checkbox labels are defined with a code or label that is "0" or "1"
(for example, "0, checkbox_label" or "check_code, 0"), importRecords is unable to
determine if a 0 indicates an unchecked box or if the zero is the label of a checked box.
When encountering ambiguity, importRecords will always assume "0" represents an
unchecked box and "1" represents a checked box.
Benjamin Nutter
with thanks to Josh O'Brien and etb (see references)
A record of imports through the API is recorded in the Logging section of the project.
importRecords prevents the most common import errors by testing the
data before attempting the import. Namely
Check that all variables in data exist in the REDCap data dictionary.
Check that the study id variable exists
Force the study id variable to the first position in the data frame (with a warning)
Remove calculated fields (with a warning)
Verify that REDCap date fields are represented in the data frame as either character, POSIXct, or Date class objects.
Determine if values are within their specified validation limits.
See the documentation for validateImport for detailed
explanations of the validation.
See the REDCap API documentation at your institution's REDCap documentation.
validateImport