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::getData
(REDCap >= 5.5.0)
REDCap::getData
— Returns a set of data (i.e. records) in a specified format from a given project
Description
mixed REDCap::getData ( [ int $project_id, ] [ string $return_format = 'array' [, mixed $records = NULL [, mixed $fields = NULL [, mixed $events = NULL [, mixed $groups = NULL [, bool $combine_checkbox_values = FALSE [, bool $exportDataAccessGroups = FALSE [, bool $exportSurveyFields = FALSE [, string $filterLogic = NULL [, bool $exportAsLabels = FALSE [, bool $exportCsvHeadersAsLabels = FALSE ]]]]]]]]]]] )
Returns a set of data (i.e. records) from a given project. The format of the returned data may be specified, and the data returned may be limited to specific records, fields, events, and/or data access groups.
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('return_format'=>'json', 'filterLogic'=>'[age] >= 18', 'fields'=>array('dob','record_id'));
$data = REDCap::getData($params);
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('return_format'=>'json', 'filterLogic'=>'[age] >= 18', 'fields'=>array('dob','record_id'));
$data = REDCap::getData($params);
Parameters
project_id (optional)
The project ID number of the REDCap project from which to pull 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 from which to pull 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.
return_format
The format in which the data should be returned. 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.
The format in which the data should be returned. 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.
records
An array of record names, or alternatively a single record name (as a string). This will limit the data returned only to those records specified. By default, NULL is used, which will return data for all records from the current project.
An array of record names, or alternatively a single record name (as a string). This will limit the data returned only to those records specified. By default, NULL is used, which will return data for all records from the current project.
fields
An array of field variable names, or alternatively a single field variable name (as a string). This will limit the data returned only to those fields specified. By default, NULL is used, which will return data for all fields from the current project.
An array of field variable names, or alternatively a single field variable name (as a string). This will limit the data returned only to those fields specified. By default, NULL is used, which will return data for all fields from the current project.
events
An array of unique event names or event_id's, or alternatively a single unique event name or event_id (as a string or int, respectively). This will limit the data returned only to those events specified. By default, NULL is used, which will return data for all events from the current project. If the project is not longitudinal, NULL is used.
An array of unique event names or event_id's, or alternatively a single unique event name or event_id (as a string or int, respectively). This will limit the data returned only to those events specified. By default, NULL is used, which will return data for all events from the current project. If the project is not longitudinal, NULL is used.
groups
An array of unique group names or group_id's, or alternatively a single unique group name or group_id (as a string or int, respectively). This will limit the data returned only to those data access groups specified. By default, NULL is used, which will return data for all data access groups from the current project. If the project does not contain any data access groups, NULL is used.
An array of unique group names or group_id's, or alternatively a single unique group name or group_id (as a string or int, respectively). This will limit the data returned only to those data access groups specified. By default, NULL is used, which will return data for all data access groups from the current project. If the project does not contain any data access groups, NULL is used.
combine_checkbox_values
Sets the format in which data from checkbox fields are returned. By default, FALSE is used. Combine_checkbox_values can only be used when return_format is 'csv', 'json', 'xml', or 'odm'. If return_format is 'array', then combine_checkbox_values is set to FALSE. When combine_checkbox_values is set to TRUE, it will return a checkbox field's data as a single field with all its checked options (excludes unchecked options) combined as a comma-delimited string (e.g., meds="1,3,4" if only choices 1, 3, and 4 are checked off). If set to FALSE, a checkbox's data values are returned as multiple fields appended with triple underscores with a value of "1" if checked and "0" if unchecked (e.g., meds___1="1", meds___2="0", meds___3="1", meds___4="1").
Sets the format in which data from checkbox fields are returned. By default, FALSE is used. Combine_checkbox_values can only be used when return_format is 'csv', 'json', 'xml', or 'odm'. If return_format is 'array', then combine_checkbox_values is set to FALSE. When combine_checkbox_values is set to TRUE, it will return a checkbox field's data as a single field with all its checked options (excludes unchecked options) combined as a comma-delimited string (e.g., meds="1,3,4" if only choices 1, 3, and 4 are checked off). If set to FALSE, a checkbox's data values are returned as multiple fields appended with triple underscores with a value of "1" if checked and "0" if unchecked (e.g., meds___1="1", meds___2="0", meds___3="1", meds___4="1").
exportDataAccessGroups
Specifies whether or not to return the "redcap_data_access_group" field when data access groups are utilized in the project. By default, FALSE is used.
Specifies whether or not to return the "redcap_data_access_group" field when data access groups are utilized in the project. By default, FALSE is used.
exportSurveyFields
Specifies whether or not to return the survey identifier field (e.g., "redcap_survey_identifier") or survey timestamp fields (e.g., form_name+"_timestamp") when surveys are utilized in the project. By default, FALSE is used.
Specifies whether or not to return the survey identifier field (e.g., "redcap_survey_identifier") or survey timestamp fields (e.g., form_name+"_timestamp") when surveys are utilized in the project. By default, FALSE is used.
filterLogic
Text string of logic to be applied to the data set so that only record-events that evaluate as TRUE for the logic will be output in the returned data set. By default, this parameter is NULL and is thus ignored. This logic string is the same format as used all throughout REDCap in advanced filters for reports, branching logic, Data Quality module, etc. Example: [sex] = "1". If the project is longitudinal, in certain contexts you may need to additionally provide the unique event name, which must also be in brackets and prepended to the variable name, in order to target that field on a particular event - e.g., [event_2_arm_1][variable_name].
Text string of logic to be applied to the data set so that only record-events that evaluate as TRUE for the logic will be output in the returned data set. By default, this parameter is NULL and is thus ignored. This logic string is the same format as used all throughout REDCap in advanced filters for reports, branching logic, Data Quality module, etc. Example: [sex] = "1". If the project is longitudinal, in certain contexts you may need to additionally provide the unique event name, which must also be in brackets and prepended to the variable name, in order to target that field on a particular event - e.g., [event_2_arm_1][variable_name].
exportAsLabels
Sets the format of the data returned. If FALSE, it returns the raw data. If TRUE, it returns the data as labels (e.g., "Male" instead of "0"). By default, FALSE is used. This parameter is ignored if return_format = "array" since "array" only returns raw values.
Sets the format of the data returned. If FALSE, it returns the raw data. If TRUE, it returns the data as labels (e.g., "Male" instead of "0"). By default, FALSE is used. This parameter is ignored if return_format = "array" since "array" only returns raw values.
exportCsvHeadersAsLabels
Sets the format of the CSV headers returned (only applicable to 'csv' return formats). If FALSE, it returns the variable names as the headers. If TRUE, it returns the fields' Field Label text as the headers. By default, FALSE is used.
Sets the format of the CSV headers returned (only applicable to 'csv' return formats). If FALSE, it returns the variable names as the headers. If TRUE, it returns the fields' Field Label text as the headers. By default, FALSE is used.
Return Values
If return_format = 'csv', 'json', 'xml', or 'odm', then data will be returned in the standard format for those return formats. If return_format = 'array', returns array of data with record name as the 1st-level array key, event_id as the 2nd-level array key, field variable name as the 3rd-level array key, and the data values as the array values for each field. If a field is a checkbox field, then the checkbox's coded values will the the 4th-level array keys while the value of each checkbox option ("0" or "1") will be the array value for each option.
SPECIAL NOTICE ABOUT REPEATING INSTRUMENTS/EVENTS if return_format = 'array': Please note that if the project has repeating instruments or repeating events enabled *and* is outputting data for at least one repeating instrument/event in 'array' return_format, then the data for all repeating instruments/events will be returned in a slightly different structure in the array returned, in which the 2nd-level array key will not be the event_id but instead will be 'repeat_instances' (this exact text string). Then under this, event_id will be the 3rd-level array key, redcap_repeat_instrument will be the 4th-level array key, redcap_repeat_instance will be the 5th-level array key, the field variable name will be the 6th-level array key, and the data values as the array values for each field. Note that non-repeating data will still be returned in the normal format in the array, but any repeating data will be added to that array in this different format as described above (thus you may have both formats represented in the array). Keep in mind that redcap_repeat_instance will always be numerical, and redcap_repeat_instrument will be the unique form name of the instrument for a repeating instrument. However, for repeating events specifically (as opposed to repeating instruments), redcap_repeat_instrument will have a blank value.
If the fields parameter includes the project’s primary key (e.g., record_id), and the return_format parameter is given as 'json', getData will return the following identifying fields, where applicable:
redcap_event_name
redcap_repeat_instance
redcap_repeat_instrument
SPECIAL NOTICE ABOUT REPEATING INSTRUMENTS/EVENTS if return_format = 'array': Please note that if the project has repeating instruments or repeating events enabled *and* is outputting data for at least one repeating instrument/event in 'array' return_format, then the data for all repeating instruments/events will be returned in a slightly different structure in the array returned, in which the 2nd-level array key will not be the event_id but instead will be 'repeat_instances' (this exact text string). Then under this, event_id will be the 3rd-level array key, redcap_repeat_instrument will be the 4th-level array key, redcap_repeat_instance will be the 5th-level array key, the field variable name will be the 6th-level array key, and the data values as the array values for each field. Note that non-repeating data will still be returned in the normal format in the array, but any repeating data will be added to that array in this different format as described above (thus you may have both formats represented in the array). Keep in mind that redcap_repeat_instance will always be numerical, and redcap_repeat_instrument will be the unique form name of the instrument for a repeating instrument. However, for repeating events specifically (as opposed to repeating instruments), redcap_repeat_instrument will have a blank value.
If the fields parameter includes the project’s primary key (e.g., record_id), and the return_format parameter is given as 'json', getData will return the following identifying fields, where applicable:
redcap_event_name
redcap_repeat_instance
redcap_repeat_instrument
Restrictions
If used in a system-level plugin, the project_id parameter is required.
Examples
Example #1:
This example illustrates many different variations of how to export data from a project using various values for each parameter.
// Export ALL data in ARRAY format
$data = REDCap::getData('array');
// Export data in CSV format for only record "101" for ALL fields
$data = REDCap::getData('csv', '101');
// Export data in CSV format for a single record for ALL fields from two different
// REDCap projects (project_id = 44 and 723, respectively)
$data1 = REDCap::getData(44, 'csv', '101');
$data2 = REDCap::getData(723, 'csv', '934-2');
// Export data in JSON format for records "101" and "102"
// for only the fields "record_id" and "dob"
$data = REDCap::getData('json', array('101', '102'), array('record_id', 'dob'));
// Export data in XML format for ALL records, for only the field "dob", and
// for only two specific events (assuming a longitudinal project)
$data = REDCap::getData('xml', null, 'dob', array('enrollment_arm1', 'visit1_arm1'));
// Export ALL data in ARRAY format for the data access group named "Vanderbilt Group"
$data = REDCap::getData('array', null, null, null, 'vanderbilt_group');
// Export data in CSV format for ALL records and for the fields "study_id" and "meds"
// in which each checkbox field's checked values are combined into a comma-delimited string
$data = REDCap::getData('csv', null, array('study_id', 'meds'), null, null, true);
// Export data as labels in CSV format with label headers for only the fields 'record_id', 'dob',
// and the Data Access Group field but JUST records whose record name ends with "--1"
$data = REDCap::getData('csv', null, array('record_id', 'dob'), null, null, false, true, false,
'ends_with([record_id], "--1")', true, true);
// Export data in XML format for only the fields 'record_id', 'dob', survey identifier,
// and survey timestamps but JUST records where the last name contains "tay"
$data = REDCap::getData('xml', null, array('record_id', 'dob'), null, null, false, false, true,
'contains([last_name], "tay")');
// Export data as labels in JSON format for ALL fields but JUST records where [sex] = "0"
$data = REDCap::getData('json', null, null, null, null, false, false, false, '[sex] = "0"', true);
// Export ALL data from the current project in CDISC ODM XML format
$data = REDCap::getData('odm');
// Use alternative passing of parameters as an associate array
$params = array('return_format'=>'json', 'filterLogic'=>'[age] >= 18', 'exportDataAccessGroups'=>true);
$data = REDCap::getData($params);
// Use alternative passing of parameters as an associate array
$params = array('project_id'=>563, 'exportSurveyFields'=>true,
'fields'=>array('dob','record_id'), 'records'=>array('101','102'));
$data = REDCap::getData($params);
REDCap 14.9.1 - © 2024 Vanderbilt University