Learn R Programming

redcapAPI (version 2.10.0)

importFileToRecord: 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

  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 enabledrecordRecord ExistsAction
YesNULLNoCreate a new record (using force_auto_number = TRUE) and import the file to the new record
YesSpecifiedYesImport the file to the existing record
YesSpecifiedNoCreate a new record (using force_auto_number = TRUE)and import the file to the new record
NoNULLNoError: record must be provided when auto numbering is not enabled
NoSpecifiedYesImport the file to the existing record
NoSpecifiedNoCreate the record (using force_auto_number = FALSE) and import the file to the new record.

See Also

importFiles(),
importRecords()