redcap_import_records: Import Records

In RoeLabWustl/roelabr: A collection of functions for the Drives Lab at Washington University

Import Records

Description

Import Records

Usage

redcap_import_records(
  redcap_uri = "https://redcap.wustl.edu/redcap/api/",
  token,
  format = c("xml", "csv", "json", "odm"),
  type = c("flat", "eav"),
  overwrite_behavior = c("normal", "overwrite"),
  force_auto_number = FALSE,
  data,
  date_format = c("YMD", "MDY", "DMY"),
  csv_delimiter = c(",", "tab", ";", "|", "^"),
  return_content = c("count", "ids", "auto_ids"),
  return_format = c("xml", "csv", "json")
)

Arguments

redcap_uri	The URI (uniform resource identifier) of the REDCap project.
token	The API token specific to your REDCap project and username (each token is unique to each user for each project). See the section on the left-hand menu for obtaining a token for a given project.
format	csv, json, xml [default], odm ('odm' refers to CDISC ODM XML format, specifically ODM version 1.3.1)
type	flat - output as one record per row [default] eav - input as one data point per row Non-longitudinal: Will have the fields - record(1), field_name, value Longitudinal: Will have the fields - record*, field_name, value, redcap_event_name(2) 'record' refers to the record ID for the project Event name is the unique name for an event, not the event label
overwrite_behavior	normal - blank/empty values will be ignored [default] overwrite - blank/empty values are valid and will overwrite data
force_auto_number	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. For example, if false (or 'false') - The record names provided in the request will be used. [default] true (or 'true') - New record names will be automatically determined.
data	The formatted data to be imported. TIP: If importing repeating instances for a repeating event or repeating instrument, you may auto-number the instances by providing a value of 'new' for the 'redcap_repeat_instance' field in the dataset you are importing. This is useful because it allows you to import such data without the need to determine how many instances already exist for a given repeating event/instance prior to the import. NOTICE: The 'new' value option for auto-numbering instances does NOT work for 'eav' type data but only for 'flat' type. NOTE: When importing data in EAV type format, please be aware that checkbox fields must have their field_name listed as variable+'___'+optionCode and its value as either '0' or '1' (unchecked or checked, respectively). For example, for a checkbox field with variable name 'icecream', it would be imported as EAV with the field_name as 'icecream___4' having a value of '1' in order to set the option coded with '4' (which might be 'Chocolate') as ' checked'.
date_format	MDY, DMY, YMD [default] - the format of values being imported for dates or datetime fields (understood with M representing 'month', D as 'day', and Y as 'year') - NOTE: The default format is Y-M-D (with dashes), while MDY and DMY values should always be formatted as M/D/Y or D/M/Y (with slashes), respectively.
csv_delimiter	Set the delimiter used to separate values in the CSV data file (for CSV format only). Options include: comma ',' (default), 'tab', semi-colon ';', pipe '|', or caret '^'. Simply provide the value in quotes for this parameter.
return_content	count [default] - the number of records imported, ids a list of all record IDs that were imported, auto_ids = (used only when forceAutoNumber=true) a list of pairs of all record IDs that were imported, includes the new ID created and the ID value that was sent in the API request (e.g., 323,10).
return_format	csv, json, xml - specifies the format of error messages. If you do not pass in this flag, it will select the default format for you passed based on the 'format' flag you passed in or if no format flag was passed in, it will default to 'xml'.

Value

httr::response() object containing the number of records deleted.

Examples

## Not run: 
## csv eav example to edit a single data point
### write data to disk and read back in to get correctly parsed csv string
csv_data <- data.frame(
  record = 2,
  field_name = "text_box",
  value = "a new value"
)
csv_file <- tempfile("data", fileext = ".csv")
write.csv(csv_data, csv_file, row.names = FALSE)
data <- paste(readLines(csv_file), collapse = "\n")

### retreive credentials
path <- system.file("misc/example.credentials", package = "REDCapR")
p1 <- REDCapR::retrieve_credential_local(path, 153L)

### submit api request and check response
httr::content(
  redcap_import_records(
    token = p1$token,
    format = "csv",
    type = "eav",
    data = data,
    return_format = "json"
  )
)

## End(Not run)

RoeLabWustl/roelabr documentation built on Aug. 27, 2022, 9:57 a.m.