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::reserveNewRecordId
(REDCap >= 10.3.0)
REDCap::reserveNewRecordId
— A thread-safe way to reserve a new record ID in a project prior to creating the record.
Description
string REDCap::reserveNewRecordId ( int $project_id [, string $recordIdToReserve = NULL] )
A thread-safe way to reserve a new record ID in a project prior to creating the record by using record auto-numbering or by manually providing a new record name to reserve as the $recordIdToReserve parameter. NOTE: This method will not create the record but will merely reserve the record ID so that it will not be used by any other processes in REDCap when creating a record in the near future. Once the record ID is reserved, it will remain reserved for up to 72 hours. When using this method, the assumption is that after reserving a new record ID, you should create a new record with that record name shortly thereafter.
Parameters
project_id
The project ID number of the REDCap project. If the project_id parameter's value is not numeric, it will throw an exception.
The project ID number of the REDCap project. If the project_id parameter's value is not numeric, it will throw an exception.
recordIdToReserve
(optional) To use record auto-numbering to automatically determine the next record ID to reserve, this parameter should be NULL or omitted. If a value is passed for this parameter and it fails to reserve it, FALSE will be returned.
(optional) To use record auto-numbering to automatically determine the next record ID to reserve, this parameter should be NULL or omitted. If a value is passed for this parameter and it fails to reserve it, FALSE will be returned.
Return Values
The record name of the newly created record. If the recordIdToReserve parameter is used and it fails to reserve the desired record ID, then FALSE will be returned.
Examples
Example #1:
Reserving a new record via record auto-numbering
$reservedRecordId = REDCap::reserveNewRecordId($project_id); $data = [['record_id'=>$reservedRecordId]]; $results = REDCap::saveData($project_id, 'json', json_encode($data));
Example #2:
Reserving a new record by manually passing a desired record ID
$reservedRecordId = REDCap::reserveNewRecordId($project_id, "VUMC-004"); $data = [['study_id'=>$reservedRecordId]]; $results = REDCap::saveData($project_id, 'json', json_encode($data));
Example #3:
Simple example of using manually record reserving while dealing with failures
while (true)
{
// You might have a function or method for generating a complex, new record ID
$desiredRecordId = myFunctionToGenerateNextId();
// Attempt to reserve it
$reservedRecordId = REDCap::reserveNewRecordId($project_id, $desiredRecordId);
// If it fails to be reserved, then keep trying in the next loop
if ($reservedRecordId !== false)
{
// If successfully reserved, create a record using it
$data = [['record_id'=>$reservedRecordId]];
$results = REDCap::saveData($project_id, 'json', json_encode($data));
break;
}
}
REDCap 14.9.1 - © 2024 Vanderbilt University