R: Import a File With Option to Create A Record to Receive the...

importFileToRecord {redcapAPI}

R Documentation

Import a File With Option to Create A Record to Receive the File

Description

There are times when the user may desire to create a record and import a file as part of a single action. For example, a study consent form may have been collected and needs to be stored with the data of the new study participant. importFileToRecord extends importFiles to allow the concurrent creation of the record in which the file will be stored.

Usage

importFileToRecord(
  rcon,
  file,
  record = NULL,
  field,
  event,
  overwrite = TRUE,
  repeat_instance = NULL,
  ...
)

Arguments

`rcon`	A `redcapConnection` object.
`file`	`character(1)`. The file path to the file to be imported.
`record`	`character(1)` or `integerish(1)` or `NULL`. The record ID in which the desired file is stored. When `NULL`, an attempt will be made to create a new record for the file. See 'Details'
`field`	`character(1)`. The field name in which the file is stored.
`event`	`character(1)` or `NULL`. The event name for the file. This applies only to longitudinal projects. If the event is not supplied for a longitudinal project, the API will return an error message
`overwrite`	`logical(1)`. When `FALSE`, the function checks if a file already exists for that record. If a file exists, the function terminates to prevent overwriting. When `TRUE`, no additional check is performed.
`repeat_instance`	`integerish(1)` or `NULL`. The repeat instance number of the repeating event or the repeating instrument. When available in your instance of REDCap, and passed as `NULL`, the API will assume a value of 1.
`...`	Arguments to pass to other methods

Details

The behavior of importFileToRecord depends on

whether record auto numbering has been enabled in the project,
if the record is specified by the user
if the record specified by the user exists.

The following table details the actions taken based on these conditions. (force_auto_number is an argument to importRecords()).

Autonumbering enabled	`record`	Record Exists	Action
Yes	`NULL`	No	Create a new record (using `force_auto_number = TRUE`) and import the file to the new record
Yes	Specified	Yes	Import the file to the existing record
Yes	Specified	No	Create a new record (using `force_auto_number = TRUE`)and import the file to the new record
No	`NULL`	No	Error: record must be provided when auto numbering is not enabled
No	Specified	Yes	Import the file to the existing record
No	Specified	No	Create the record (using `force_auto_number = FALSE`) and import the file to the new record.

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())

importFileToRecord(rcon,
                   file = "file_to_upload.txt" 
                   record = NULL, 
                   field = "file_upload_test")

## End(Not run)