Plugins, Hooks, & External Modules
Developer methods for
Plugins, Hooks, & External Modules
Hook functions
REDCap Developer Tools:
Documentation for Plugins, Hooks, & External Modules
REDCap Version 14.9.1
REDCap::addFileToField
(REDCap >= 13.1.0)
REDCap::addFileToField
— Attaches a file to a File Upload field for a specified record when provided with the doc_id of an existing file from the REDCap system.
Description
bool REDCap::addFileToField ( int $doc_id, int $project_id, string $record, string $field_name [, int $event_id = NULL [, int $repeat_instance = 1 ]] )
Attaches a file to a File Upload field for a specified record when provided with the doc_id number (the primary key from the redcap_edocs_metadata database table) of an existing file from the REDCap system. This method assumes the record already exists. NOTE: This method should not be used if the file's doc_id is already attached to another File Upload field or to a file in the File Repository. Thus, it is assumed that REDCap::storeFile() or REDCap::copyFile() must always be used prior to REDCap::addFileToField. If you wish to attach a file that is already being utilized elsewhere in REDCap (e.g., by another File Upload field or in the File Repository), it is recommended that you first call REDCap::copyFile() to copy the original file, and then call REDCap::addFileToField() afterward.
Parameters
$doc_id
The file's doc_id number from the redcap_edocs_metadata database table.
The file's doc_id number from the redcap_edocs_metadata database table.
project_id
The project ID (PID) number of the project.
The project ID (PID) number of the project.
record
The name of the record/response to which the survey link belongs.
The name of the record/response to which the survey link belongs.
field_name
A field's variable name. If field_name is invalid for the project, returns FALSE.
A field's variable name. If field_name is invalid for the project, returns FALSE.
event_id
(longitudinal projects only) The event ID number that corresponds to a defined event in a longitudinal project. For classic projects, the event_id is not explicitly required, and thus it will be supplied automatically since there will only ever be one event_id for the project.
(longitudinal projects only) The event ID number that corresponds to a defined event in a longitudinal project. For classic projects, the event_id is not explicitly required, and thus it will be supplied automatically since there will only ever be one event_id for the project.
repeat_instance
(only for projects with repeating instruments/events) The repeat instance number of the repeating event (if longitudinal) or the repeating instrument (if classic or longitudinal).
(only for projects with repeating instruments/events) The repeat instance number of the repeating event (if longitudinal) or the repeating instrument (if classic or longitudinal).
Return Values
Returns TRUE if the file was successfully added/attached to the specified record's field. If any provided parameters are incorrect, FALSE will be returned.
Examples
Example #1:
This example illustrates how one might attach a local file to a File Upload field.
// Store a file, obtain its doc_id, and then store it in a File Upload field $filepath = "/var/www/redcap/myfiles/participant003.docx"; $doc_id = REDCap::storeFile($filepath, $project_id); // Add file to record "101" and field "participant_file" REDCap::addFileToField($doc_id, $project_id, "101", "participant_file");
Example #2:
This example illustrates how one might first copy an existing REDCap file and then add the new file to a File Upload field.
// Doc_id of the already-existing file $doc_id = 223; // Copy the file to create a new one $new_doc_id = REDCap::copyFile($doc_id, $project_id); // Add file to record "44", event_id "297" (since the project is longitudinal), and field "participant_file" REDCap::addFileToRepository($new_doc_id, $project_id, "44", "participant_file", 297);
REDCap 14.9.1 - © 2024 Vanderbilt University