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::logEvent
(REDCap >= 5.5.1)
REDCap::logEvent
— Create a custom logged event
Description
void REDCap::logEvent ( string $action_description [, string $changes_made = NULL [, string $sql = NULL [, string $record = NULL [, string $event = NULL [, int $project_id = NULL ]]]]] )
Create a custom logged event, which will be displayed in the Control Center's Activity Log, and if a project-level plugin, it will be associated with the project and thus displayed on the project's Logging page.
Parameters
action_description
A short description of the action being performed. This can be whatever text you wish, either a custom action specific to your plugin (e.g., "Perform meta-analysis", "Export data to EMR") or an existing REDCap logged action type (e.g., "Updated Record"). The action_description will be displayed as-is on the Control Center's Activity Log and (if a project-level plugin) the project's Logging page.
A short description of the action being performed. This can be whatever text you wish, either a custom action specific to your plugin (e.g., "Perform meta-analysis", "Export data to EMR") or an existing REDCap logged action type (e.g., "Updated Record"). The action_description will be displayed as-is on the Control Center's Activity Log and (if a project-level plugin) the project's Logging page.
changes_made
(optional) A string of text listing any notable changes made (not necessarily data values for a project). If a project-level plugin, this text will be displayed in the List of Changes column on the project's Logging page. For display purposes on the Logging page, you may use \n or natural line breaks in the string to begin a new line for each item you are listing.
(optional) A string of text listing any notable changes made (not necessarily data values for a project). If a project-level plugin, this text will be displayed in the List of Changes column on the project's Logging page. For display purposes on the Logging page, you may use \n or natural line breaks in the string to begin a new line for each item you are listing.
sql
(optional) An SQL query executed by the plugin that you wish to associate with this logged event (e.g., the SQL used if a database table was queried). You may input multiple queries together by delimiting them with a semi-colon all as a single string. This will never be displayed within REDCap anywhere but is merely for record keeping, in which it will stay stored in the redcap_log_event database table for reference/audit purposes.
(optional) An SQL query executed by the plugin that you wish to associate with this logged event (e.g., the SQL used if a database table was queried). You may input multiple queries together by delimiting them with a semi-colon all as a single string. This will never be displayed within REDCap anywhere but is merely for record keeping, in which it will stay stored in the redcap_log_event database table for reference/audit purposes.
record
(optional) The name of the record, assuming this logged event involves a record (e.g., data changes). If this is set, the logged event will be filterable by that record name on a project's Logging page.
(optional) The name of the record, assuming this logged event involves a record (e.g., data changes). If this is set, the logged event will be filterable by that record name on a project's Logging page.
event
(optional) The event_id number OR the unique event name of a REDCap event in a project, assuming this logged event involves a record (e.g., data changes).
(optional) The event_id number OR the unique event name of a REDCap event in a project, assuming this logged event involves a record (e.g., data changes).
project_id
(optional) The project_id number of the REDCap project for which this event should be logged. If this method is being called in a project context, then this will override the existing project's project_id, but if project_id is left as NULL in a project context, then the project's project_id will be used. NOTE: This parameter was added in REDCap 5.10.0.
(optional) The project_id number of the REDCap project for which this event should be logged. If this method is being called in a project context, then this will override the existing project's project_id, but if project_id is left as NULL in a project context, then the project's project_id will be used. NOTE: This parameter was added in REDCap 5.10.0.
Return Values
Returns nothing.
Examples
Example #1:
This example demonstrates how one might log a specific data change to a record in project.
// Update the data table (assumes a value already exists for this field)
$sql = "update redcap_data set value = 'Paul' where project_id = 43
and record = '1002' and event_id = 78 and field_name = 'first_name'";
if (db_query($sql))
{
// Log the data change
REDCap::logEvent("Updated Record", "study_id = '1002',\nfirst_name = 'Paul'", $sql, '1002', 78);
}
Example #2:
This example shows how data values stored in an array can be logged as a custom logged event.
// Array of data with REDCap variable name as array key
$data = array(
'record_id' => '23-4832',
'hypertension' => '1',
'type_diabetes' => '2',
'age' => '66'
);
// [Perform plugin actions here]
// Format $data array for logging. First put into array, then implode into string.
$data_formatted = array();
foreach ($data as $this_field => $this_value) {
$data_formatted[] = "$this_field = '$this_value'";
}
$data_changes = implode(",\n", $data_formatted);
// Log the event
REDCap::logEvent("Imported data from I2B2", $data_changes, NULL, '23-4832', 'visit1_arm1');
Example #3:
This example shows how to log only the action that occurred without including any other related information.
REDCap::logEvent("Downloaded attendee report");
REDCap 14.9.1 - © 2024 Vanderbilt University