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::getProjectXML
(REDCap >= 6.12.0)
REDCap::getProjectXML
— Returns the contents of an entire project (records, events, arms, instruments, fields, and project attributes) as a single XML file, which is in CDISC ODM format.
Description
mixed REDCap::getProjectXML ( [ int $project_id, ] [, bool $returnMetadataOnly = FALSE [, mixed $records = NULL [, mixed $fields = NULL [, mixed $events = NULL [, mixed $groups = NULL [, bool $exportDataAccessGroups = FALSE [, bool $exportSurveyFields = FALSE [, string $filterLogic = NULL [, bool $exportFiles = FALSE ]]]]]]]]] )
Returns the contents of an entire project (records, events, arms, instruments, fields, and project attributes) as a single XML file, which is in CDISC ODM format (ODM version 1.3.1). While the project metadata (fields, forms, events, arms) will always be returned, it is option to have record data returned, in which case the data may be limited to specific records, fields, events, and/or data access groups. The XML that is returned may also be used for creating a clone of the project using the the Create New Project page or the Create Project API method. NOTE: The current user accessing the hook/plugin will have their user rights applied if they have limited data export privileges (e.g., De-Identified), in which some fields in the data may be removed in the XML that is returned.
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.
returnMetadataOnly
Specifies if it should return only metadata for the project (events, arms, instruments, fields, and project attributes) without any record data, as opposed to metadata AND data. If FALSE (default), it will return both metadata and data for the project.
Specifies if it should return only metadata for the project (events, arms, instruments, fields, and project attributes) without any record data, as opposed to metadata AND data. If FALSE (default), it will return both metadata and data for the project.
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.
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".
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".
exportFiles
Specifies whether or not the resulting XML will include all uploaded files and signatures. TRUE will cause the XML returned to include all files uploaded for File Upload and Signature fields for all records in the project, whereas FALSE will cause all such fields not to be included. By default, FALSE is used. NOTE: Setting this option to TRUE can make the export very large and may prevent it from completing if the project contains many files or very large files.
Specifies whether or not the resulting XML will include all uploaded files and signatures. TRUE will cause the XML returned to include all files uploaded for File Upload and Signature fields for all records in the project, whereas FALSE will cause all such fields not to be included. By default, FALSE is used. NOTE: Setting this option to TRUE can make the export very large and may prevent it from completing if the project contains many files or very large files.
Return Values
Returns the contents of an entire project (records, events, arms, instruments, fields, and project attributes) as a single XML file, which is in CDISC ODM format.
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 and metadata in XML file (in CDISC ODM format) $xml = REDCap::getProjectXML(44);
REDCap 14.9.1 - © 2024 Vanderbilt University