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::evaluateLogic
(REDCap >= 8.0.1)
REDCap::evaluateLogic
— Returns whether a string of logic (e.g., branching logic) evaluates as true or false based on the data of a given record in a given project.
Description
mixed REDCap::evaluateLogic ( string $logic, int $project_id, string $record [, mixed $event = NULL [, int $repeat_instance = 1 [, string $repeat_instrument = NULL [, string $current_context_instrument = NULL ]]]] )
Returns whether a string of logic (e.g., branching logic) evaluates as true or false based on the data of a given record in a given project. For a longitudinal project, if the variables in the logic do not have prepended unique event names (e.g., [age] instead of [event_1_arm_1][age]), you may pass the $event (unique event name OR event ID number) to evaluate the logic for that specified event's data in the record. If the project has repeating instruments or repeating events, then you may provide the $repeat_instance and (for repeating instruments only) the $repeat_instrument to evaluate the logic over the specified repeating instance's data in the record.
Note: If the logic is not syntactically correct or if any of the parameters are invalid (e.g., record or event does not exist), it will return NULL.
Note: If the logic is not syntactically correct or if any of the parameters are invalid (e.g., record or event does not exist), it will return NULL.
Parameters
logic
The string of logic text, similar to branching logic, report filters, etc. - e.g., "[age] > 18 and [sex] = '1'". Note: The logic should evaluate as a boolean and should not return a value (like a calculated field).
The string of logic text, similar to branching logic, report filters, etc. - e.g., "[age] > 18 and [sex] = '1'". Note: The logic should evaluate as a boolean and should not return a value (like a calculated field).
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 evaluate the logic.
The record name of the specific record for which you want to evaluate the logic.
event (optional)
A single unique event name or event_id (as a string or int, respectively). For a longitudinal project, if the variables in the logic do not have prepended unique event names (e.g., [age] instead of [event_1_arm_1][age]), you may pass the $event (unique event name OR event ID number) to evaluate the logic for that specified event's data in the record. If the project is not longitudinal, NULL is used. For longitudinal projects in which all variables in the logic already have prepended unique event names, then $event does not have to be used and can be left as NULL.
A single unique event name or event_id (as a string or int, respectively). For a longitudinal project, if the variables in the logic do not have prepended unique event names (e.g., [age] instead of [event_1_arm_1][age]), you may pass the $event (unique event name OR event ID number) to evaluate the logic for that specified event's data in the record. If the project is not longitudinal, NULL is used. For longitudinal projects in which all variables in the logic already have prepended unique event names, then $event does not have to be used and can be left as NULL.
repeat_instance (optional)
The instance number (as an integer) if you wish to evaluate the logic over a specific repeating instrument's or repeating event's data in the record.
The instance number (as an integer) if you wish to evaluate the logic over a specific repeating instrument's or repeating event's data in the record.
repeat_instrument (optional)
The unique instrument name (column B in the Data Dictionary) of a repeating instrument (as a string) if you wish to evaluate the logic over a specific instance of a repeating instrument's data in the record. This is used together with $repeat_instance.
The unique instrument name (column B in the Data Dictionary) of a repeating instrument (as a string) if you wish to evaluate the logic over a specific instance of a repeating instrument's data in the record. This is used together with $repeat_instance.
current_context_instrument (optional)
The unique instrument name (column B in the Data Dictionary) of an instrument (as a string) if the logic is being evaluated in the context of this specific instrument (e.g., while on a survey page or data entry form). This does not always need to be provided, but certain Smart Variables will require it if they are used in the logic. So it is recommended to always provide this instrument name if the logic is being evaluated in the context of a specific instrument.
The unique instrument name (column B in the Data Dictionary) of an instrument (as a string) if the logic is being evaluated in the context of this specific instrument (e.g., while on a survey page or data entry form). This does not always need to be provided, but certain Smart Variables will require it if they are used in the logic. So it is recommended to always provide this instrument name if the logic is being evaluated in the context of a specific instrument.
Return Values
TRUE is returned if the logic evaluates as TRUE for the given parameters, or FALSE if it does not. If the logic is not syntactically correct or if any of the parameters are invalid (e.g., record or event does not exist), then NULL is returned.
Examples
Example #1:
This example illustrates evaluating logic for a record in a classic/non-longitudinal project.
$logic = "[age] > 30 and [sex] = '1'";
$record = "101";
$valid = REDCap::evaluateLogic($logic, 465, $record);
if ($valid === null) {
// The logic is not syntactically correct, or the parameters are not valid
} elseif ($valid) {
// Logic is true
} else {
// Logic is not true
}
Example #2:
This example illustrates evaluating logic for a record and event in a non-longitudinal project.
$logic = "[age] > 30 and [sex] = '1'"; $record = "101"; $event = "enrollment_arm_1"; $valid = REDCap::evaluateLogic($logic, 3245, $record, $event);
Example #3:
This example is another way of doing the previous example above.
$logic = "[enrollment_arm_1][age] > 30 and [enrollment_arm_1][sex] = '1'"; $record = "101"; $valid = REDCap::evaluateLogic($logic, 3245, $record);
Example #4:
This example illustrates evaluating logic for a record on instance #3 of a repeating instrument named "visit_data" in a classic/non-longitudinal project.
$logic = "[diastolic] > 80 and [bmi] > 25"; $record = "101"; $instance = 3; $repeating_form = "visit_data"; $valid = REDCap::evaluateLogic($logic, 85, $record, null, $instance, $repeating_form);
REDCap 14.9.1 - © 2024 Vanderbilt University