importRecords: Import Records to a REDCap Database

Description

Imports records from a data.frame to a REDCap Database

Usage

importRecords(
  rcon,
  data,
  overwriteBehavior = c("normal", "overwrite"),
  returnContent = c("count", "ids", "nothing"),
  returnData = FALSE,
  logfile = "",
  ...
)
# S3 method for redcapDbConnection
importRecords(
  rcon,
  data,
  overwriteBehavior = c("normal", "overwrite"),
  returnContent = c("count", "ids", "nothing"),
  returnData = FALSE,
  logfile = "",
  ...
)
# S3 method for redcapApiConnection
importRecords(
  rcon,
  data,
  overwriteBehavior = c("normal", "overwrite"),
  returnContent = c("count", "ids", "nothing"),
  returnData = FALSE,
  logfile = "",
  ...,
  bundle = NULL,
  batch.size = -1
)

Arguments

rcon: A REDCap connection object as created by redcapConnection.
data: A data.frame to be imported to the REDCap project.
overwriteBehavior: Character string. 'normal' prevents blank fields from overwriting populated fields. 'overwrite' causes blanks to overwrite data in the REDCap database.
returnContent: Character string. 'count' returns the number of records imported; 'ids' returns the record ids that are imported; 'nothing' returns no message.
returnData: 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 shoot me an e-mail if you find errors I havne't accounted for.
logfile: 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.
bundle: A redcapBundle object as created by exportBundle.
batch.size: Specifies size of batches. A negative value indicates no batching.

Author

Benjamin Nutter
with thanks to Josh O'Brien and etb (see references)

Details

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.

References

http://stackoverflow.com/questions/12393004/parsing-back-to-messy-api-strcuture/12435389#12435389
https://github.com/etb/my-R-code/blob/master/R-pull-and-push-from-and-to-REDCap.R
See also the REDCap API documentation Please refer to your institution's API documentation.