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,
...
)A redcapConnection object.
character(1). The file path to the file to be imported.
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'
character(1). The field name in which the file is stored.
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
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.
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
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. |
importFiles(),
importRecords()