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::updateRandomizationTableEntry
(REDCap >= 14.7.0)
REDCap::updateRandomizationTableEntry
— Updates the target (randomization field or number), alternate target, or "is_used_by" details for a specified allocation table entry.
Description
mixed REDCap::updateRandomizationTableEntry ( int $project_id, int $randomization_id, int $allocation_id, string $column, mixed $value [, string $reason = ''] )
Writes the specified value to the specified column of the allocation table in the database. Returns true on success or false on failure.
Parameters
project_id
The project ID number of the REDCap project for which you want to update the allocation table.
The project ID number of the REDCap project for which you want to update the allocation table.
randomization_id
The id of the randomization (i.e., the primary key value from the redcap_randomization_table. Obtain corresponding randomization attributes using
The id of the randomization (i.e., the primary key value from the redcap_randomization_table. Obtain corresponding randomization attributes using
\Randomization::getRandomizationAttributes($randomization_id, $project_id)).allocation_id
A unique id of an entry in the allocation table for the specified randomization.
A unique id of an entry in the allocation table for the specified randomization.
column
The column of the allocation table in the database to which the value will be written. Options: target_field, target_field_alt, is_used_by, allocation_time, allocation_time_utc.
The column of the allocation table in the database to which the value will be written. Options: target_field, target_field_alt, is_used_by, allocation_time, allocation_time_utc.
value
The value to write to the column in the allocation table in the database. Can be NULL.
The value to write to the column in the allocation table in the database. Can be NULL.
reason (optional)
A reason message to include in logging.
A reason message to include in logging.
Return Values
Returns integer allocation id if an unallocated entry is found, or string '0' if no entry is available (allocation table is exhausted). Returns false on error, e.g. if incorrect stratification information provided.
Examples
Example #1:
Randomizing a record using a custom group allocation algorithm.
*
* $randomization_id = 465;
* $allocation_id = 65460; // A specific entry in the allocation table
* $column = 'target_field'; // The column for the randomization field value
* $value = "1"; // The value we want to set for the randomization field
* $result = REDCap::updateRandomizationTableEntry($project_id, $randomization_id, $allocation_id, $column, $value);
* if ($result) {
* // Success
* } else {
* // Invalid arguments
* }
*
REDCap 14.9.1 - © 2024 Vanderbilt University