importFileToRecord function

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

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.

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

1. whether record auto numbering has been enabled in the project,
2. if the record is specified by the user
3. 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)

See Also

importFiles(),

importRecords()