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::saveData
(REDCap >= 6.8.0)
REDCap::saveData
— Saves a set of data (i.e. records) in a specified format to a given project
Description
mixed REDCap::saveData ( [ int $project_id, ] [ string $dataFormat = 'array' [, mixed $data [, string $overwriteBehavior = 'normal' [, string $dateFormat = 'YMD' [, string $type = 'flat' [, mixed $dataAccessGroup = NULL [, bool $dataLogging = TRUE [, bool $performAutoCalc = TRUE [, bool $commitData = TRUE ]]]]]]]]] )
Saves a set of data (i.e. records) in a specified format to a given project. Much like the Data Import Tool and API data import, the saveData method performs all sorts of error checking, such as field validation, before saving the data. Any errors encountered will be returned, in which the data will not be saved until all errors have been removed from the dataset being imported.
Note: If Automated Survey Invitations (ASIs) are being used in the project on which the saveData method is used, then you should be aware that those ASIs will be triggered (i.e., survey invitations will be scheduled or sent) *if* the ASI's conditional logic now evaluates as TRUE due to the new data values being added/updated (just like when editing a record on a survey, form, or data import).
Note about checkboxes: If saving checkbox data, please be aware that each checkbox option must be represented as a *separate* field (i.e., with field name appended with triple underscore and the choice's coded value). It will not accept comma-delimited checkbox values, such as those output by REDCap::getData() with combine_checkbox_values=TRUE.
Alternative way of passing parameters: Rather than providing the method's parameters individually, they instead may be passed to the method in an associative array, in which each key in the array exactly matches the parameter names listed above (must match case). Note: Not all the parameters have to be included in the array, but only the ones you wish to set explicitly. See the following example and more at the bottom.
$params = array('dataFormat'=>'json', 'type'=>'flat', 'data'=>'[{"record_id":"1","age":"41","dob":"1978-07-20","form_1_complete":"0"}]');
$response = REDCap::saveData($params);
Note: If Automated Survey Invitations (ASIs) are being used in the project on which the saveData method is used, then you should be aware that those ASIs will be triggered (i.e., survey invitations will be scheduled or sent) *if* the ASI's conditional logic now evaluates as TRUE due to the new data values being added/updated (just like when editing a record on a survey, form, or data import).
Note about checkboxes: If saving checkbox data, please be aware that each checkbox option must be represented as a *separate* field (i.e., with field name appended with triple underscore and the choice's coded value). It will not accept comma-delimited checkbox values, such as those output by REDCap::getData() with combine_checkbox_values=TRUE.
Alternative way of passing parameters: Rather than providing the method's parameters individually, they instead may be passed to the method in an associative array, in which each key in the array exactly matches the parameter names listed above (must match case). Note: Not all the parameters have to be included in the array, but only the ones you wish to set explicitly. See the following example and more at the bottom.
$params = array('dataFormat'=>'json', 'type'=>'flat', 'data'=>'[{"record_id":"1","age":"41","dob":"1978-07-20","form_1_complete":"0"}]');
$response = REDCap::saveData($params);
Parameters
project_id (optional)
The project ID number of the REDCap project in which to save data. If not provided in a project-level plugin, it will assume the current project ID of the plugin and will also infer return_format to be the first parameter passed to the method. If project_id is not provided in a system-level plugin, it will throw a fatal error.
The project ID number of the REDCap project in which to save data. If not provided in a project-level plugin, it will assume the current project ID of the plugin and will also infer return_format to be the first parameter passed to the method. If project_id is not provided in a system-level plugin, it will throw a fatal error.
dataFormat
The format of the input data being provided in the "data" parameter. Valid options: 'array', 'csv', 'json', 'xml', 'json-array', and 'odm'. (The 'odm' option represents CDISC ODM XML format - ODM version 1.3.1, which was added in REDCap 6.12.0. The 'json-array' option represents the same flat data structure as decoded JSONs, but avoids the encode/decode steps; this feature was added in REDCap 12.5.2.) By default, 'array' is used. If in 'array' format, the data must conform to the exact same format as output by REDCap::getData(), in which the record name is the 1st-level array key, the event_id number is the 2nd-level array key (even if a Classic project), the variable/field name is the 3rd-level array key with the field value as the array value (and if a checkbox field, the checkbox raw coded value will be the 4th-level array key with 0 or 1 as the value).
The format of the input data being provided in the "data" parameter. Valid options: 'array', 'csv', 'json', 'xml', 'json-array', and 'odm'. (The 'odm' option represents CDISC ODM XML format - ODM version 1.3.1, which was added in REDCap 6.12.0. The 'json-array' option represents the same flat data structure as decoded JSONs, but avoids the encode/decode steps; this feature was added in REDCap 12.5.2.) By default, 'array' is used. If in 'array' format, the data must conform to the exact same format as output by REDCap::getData(), in which the record name is the 1st-level array key, the event_id number is the 2nd-level array key (even if a Classic project), the variable/field name is the 3rd-level array key with the field value as the array value (and if a checkbox field, the checkbox raw coded value will be the 4th-level array key with 0 or 1 as the value).
data
The data being imported (in the specified format).
The data being imported (in the specified format).
overwriteBehavior
Determines how blank values are treated. Valid options: 'normal' or 'overwrite'. With 'normal', all blank values will be ignored and will not be saved (existing saved values will be kept), but with 'overwrite', any blank values will overwrite any existing saved data. By default, 'normal' is used.
Determines how blank values are treated. Valid options: 'normal' or 'overwrite'. With 'normal', all blank values will be ignored and will not be saved (existing saved values will be kept), but with 'overwrite', any blank values will overwrite any existing saved data. By default, 'normal' is used.
dateFormat
Specifies the format of dates or datetimes in the input data. Valid options: 'YMD', 'MDY', and 'DMY'. By default, 'YMD' is used. If a date/datetime does not match the dateFormat specified, it will return an error message.
Specifies the format of dates or datetimes in the input data. Valid options: 'YMD', 'MDY', and 'DMY'. By default, 'YMD' is used. If a date/datetime does not match the dateFormat specified, it will return an error message.
type
Specifies if the input data is 'flat' (one record-event per row/item) or 'eav' (one data point per row/item, referring to Entity-Attribute-Value model - EAV). Note: Classic projects must have the fields record, field_name, value; whereas longitudinal projects must have the fields record, field_name, value, redcap_event_name, in which "record" value is the record's record name. By default, 'flat' is used.
Specifies if the input data is 'flat' (one record-event per row/item) or 'eav' (one data point per row/item, referring to Entity-Attribute-Value model - EAV). Note: Classic projects must have the fields record, field_name, value; whereas longitudinal projects must have the fields record, field_name, value, redcap_event_name, in which "record" value is the record's record name. By default, 'flat' is used.
dataAccessGroup
A single unique group name (string) or group_id number (int). This will assign *all* records being imported/updated to that particular data access group. By default, NULL is used, in which this parameter will be ignored during the save process. Note: If you wish to assign the records to various data access groups, you should instead use the redcap_data_access_group field name for each record. If a value is provided for dataAccessGroup *and* values are also provided for the redcap_data_access_group field for one or more records, then the dataAccessGroup value will be used and the redcap_data_access_group field will be ignored.
A single unique group name (string) or group_id number (int). This will assign *all* records being imported/updated to that particular data access group. By default, NULL is used, in which this parameter will be ignored during the save process. Note: If you wish to assign the records to various data access groups, you should instead use the redcap_data_access_group field name for each record. If a value is provided for dataAccessGroup *and* values are also provided for the redcap_data_access_group field for one or more records, then the dataAccessGroup value will be used and the redcap_data_access_group field will be ignored.
dataLogging
Boolean that specifies whether or not to log the data value changes on the project's Logging page. If TRUE, it will log the values exactly as seen when saving records on surveys, forms, or data imports. By default, TRUE is used.
Boolean that specifies whether or not to log the data value changes on the project's Logging page. If TRUE, it will log the values exactly as seen when saving records on surveys, forms, or data imports. By default, TRUE is used.
performAutoCalc
Boolean that specifies if auto-calculations should be performed if any values being added/modified trigger a calculated field for the given record. By default, TRUE is used.
Boolean that specifies if auto-calculations should be performed if any values being added/modified trigger a calculated field for the given record. By default, TRUE is used.
commitData
Boolean that specifies whether or not to commit/save the data. If FALSE, it will simply do a test run and will return the expected values of returnContent, but the data will not be saved (nor will any Automated Survey Invitations be triggered). By default, TRUE is used.
Boolean that specifies whether or not to commit/save the data. If FALSE, it will simply do a test run and will return the expected values of returnContent, but the data will not be saved (nor will any Automated Survey Invitations be triggered). By default, TRUE is used.
Return Values
Returns an associate array with the following keys: "errors" (array), "warnings" (array), "ids" (array), and "item_count" (int). If the "errors" sub-array is empty, then no fatal errors occurred during the save, which assumes the save was successful. If any errors occurred, each error will be listed as an item in the sub-array. If the "warnings" sub-array is not empty, it will list all warnings (e.g. values out of range) as items in the sub-array. Warnings will not prevent the saving of data, but are allowable and are only informative. The "ids" sub-array will list all records that were created/modified during the save. "item_count" represents a count of how many individual data values were saved.
Examples
Example #1:
This example illustrates how to save a few values in CSV format to the current project.
// The CSV data to save
$csv_data =
"study_id,date_of_service,name
1001,2015-05-22,Paul
1002,2014-12-08,Rob";
// Import the data
$response = REDCap::saveData('csv', $csv_data);
// Print the number of records saved (e.g., "2" in this example)
print "We just saved {$response['item_count']} records!";
Example #2:
This example saves XML data for project_id=2301 and assigns all the records to data access group "vanderbilt_group". Since all the dates are in MM/DD/YYYY format, we set dateFormat as 'MDY'.
// The XML data to save (with dates in 'MDY' format) $xml_data = <<<DATA <?xml version="1.0" encoding="UTF-8" ?> <records> <item><study_id>1001</study_id><date_enrolled><![CDATA[12/31/2015]]></date_enrolled></item> <item><study_id>1002</study_id><date_enrolled><![CDATA[01/15/2009]]></date_enrolled></item> </records> DATA; // Import the data $response = REDCap::saveData(2301, 'xml', $xml_data, 'normal', 'MDY', 'flat', 'vanderbilt_group');
Example #3:
Overwite existing values with blank values for the field "first_name" in JSON format for the current project.
// The XML data to save with dates in 'MDY' format
$json_data = '[{"study_id":1001,"first_name":""},{"study_id":1002,"first_name":""}]';
// Import the data
$response = REDCap::saveData('json', $json_data, 'overwrite');
Example #4:
Export all the data from one project in CSV format, and then import that same data into another project.
// Get the CSV data from the first project
$csv_data = REDCap::getData(392, 'csv');
// Import the data into the second project
$response = REDCap::saveData(8240, 'csv', $csv_data, 'normal', 'YMD');
// Output message to user
print "These records were copied from one project to another: " . implode(", ", $response['ids']);
REDCap 14.9.1 - © 2024 Vanderbilt University