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::deleteRecord
(REDCap >= 11.3.0)
REDCap::deleteRecord
— Delete a single record in a given project or optionally delete parts of a record, such as a single instrument's data or a single event's data for the specified record.
Description
mixed REDCap::deleteRecord ( int $project_id, string $record [, string $arm = NULL [, string $event = NULL [, string $instrument = NULL [, int $repeat_instance = 1 ]]]] )
Returns boolean if the specified record (or part of the specified record) was successfully deleted. You may provide the $repeat_instance parameter to delete the data for a specified repeating instrument/event in the record. In a longitudinal project, if $event is provided without $instrument, it will delete all the data for that entire event.
Parameters
project_id
The project ID number of the REDCap project in which the record exists.
The project ID number of the REDCap project in which the record exists.
record
The record name of the specific record for which you want to delete the data.
The record name of the specific record for which you want to delete the data.
arm (optional)
The specific arm number for which you want to delete the entire record. If null and if the event/instrument/repeat_instance parameters are also null, then the record will be deleted across all arms on which it exists (if longitudinal with multiple arms), otherwise it will delete the record only in the specified arm. NOTE: The "arm" parameter should always be NULL unless the project is a multi-arm longitudinal project in which you specifically wish to delete ALL the data for a record in only a single arm.
The specific arm number for which you want to delete the entire record. If null and if the event/instrument/repeat_instance parameters are also null, then the record will be deleted across all arms on which it exists (if longitudinal with multiple arms), otherwise it will delete the record only in the specified arm. NOTE: The "arm" parameter should always be NULL unless the project is a multi-arm longitudinal project in which you specifically wish to delete ALL the data for a record in only a single arm.
event (optional)
A single unique event name as a string. NOTE: If instrument is provided for a longitudinal project, the event parameter is mandatory.
A single unique event name as a string. NOTE: If instrument is provided for a longitudinal project, the event parameter is mandatory.
instrument (optional)
The unique instrument name (column B in the Data Dictionary) of an instrument (as a string) if you wish to delete the data for all fields on the specified instrument for the records specified.
The unique instrument name (column B in the Data Dictionary) of an instrument (as a string) if you wish to delete the data for all fields on the specified instrument for the records specified.
repeat_instance (optional)
The repeating instance number (as an integer) if you wish to delete all data of a specific repeating instrument/event's instance in the record. If not provided, this parameter defaults to "1", if applicable.
The repeating instance number (as an integer) if you wish to delete all data of a specific repeating instrument/event's instance in the record. If not provided, this parameter defaults to "1", if applicable.
Return Values
TRUE if data is deleted, or FALSE if it does not. If any of the parameters are invalid (e.g., project, record, arm, event or instrument does not exist or is invalid, instance number missing for repeating event or repeating instrument), then NULL is returned.
Examples
Example #1:
This example illustrates how to delete an entire record (across all arms, if in a multi-arm longitudinal project).
$record = "101";
$deleted = REDCap::deleteRecord(465, $record);
if ($deleted === null) {
// The parameters are not valid
} elseif ($deleted) {
// Records are deleted
} else {
// Records are not deleted
}
Example #2:
This example illustrates deleting records on a single arm.
$record = "101"; $arm_number = 2; $deleted = REDCap::deleteRecord(3245, $record, $arm_number);
Example #3:
This example illustrates deleting all the data within a specific event in a longitudinal project.
$record = "101"; $event = "enrollment_arm_1"; $deleted = REDCap::deleteRecord(3245, $record, null, $event);
Example #4:
This example illustrates deleting data for instance #3 of a repeating instrument named "visit_data" in a classic/non-longitudinal project.
$record = "101"; $instrument = "visit_data"; $instance = 3; $deleted = REDCap::deleteRecord(85, $record, null, null, $instrument, $instance);
Example #5:
This example illustrates deleting data for instance #4 of a repeating instrument named "visit_data" for event "visit_2_arm_1" in a longitudinal project.
$record = "101"; $event = "visit_2_arm_1"; $instrument = "visit_data"; $instance = 4; $deleted = REDCap::deleteRecord(347, $record, null, $event, $instrument, $instance);
Example #6:
This example illustrates deleting data for instance #2 of a repeating event named "visits_arm_1" in a longitudinal project.
$record = "101"; $event = "visits_arm_1"; $instance = 2; $deleted = REDCap::deleteRecord(851, $record, null, $event, null, $instance);
REDCap 14.9.1 - © 2024 Vanderbilt University