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::getSurveyReturnCode
(REDCap >= 5.11.0)
REDCap::getSurveyReturnCode
— Obtains the return code for a specific record on a specific survey instrument (and for a specific event, if a longitudinal project), in which the "Save & Return Later" feature is enabled for the survey - assumes the record already exists
Description
string REDCap::getSurveyReturnCode ( string $record, string $instrument [, int $event_id = NULL [, int $repeat_instance = 1 [, int $project_id = NULL ]]] )
Obtains the return code for a specific record on a specific survey instrument (and for a specific event, if a longitudinal project), in which the "Save & Return Later" feature is enabled for the survey. This method assumes the record already exists.
Parameters
record
The name of the record/response to which the survey return code belongs.
The name of the record/response to which the survey return code belongs.
instrument
The name of the data collection instrument (i.e., the unique name, not the instrument label) to which the survey corresponds. This corresponds to the value of Column B in the Data Dictionary.
The name of the data collection instrument (i.e., the unique name, not the instrument label) to which the survey corresponds. This corresponds to the value of Column B in the Data Dictionary.
event_id
(longitudinal projects only) The event ID number that corresponds to a defined event in a longitudinal project. For classic projects, the event_id is not explicitly required, and thus it will be supplied automatically since there will only ever be one event_id for the project.
(longitudinal projects only) The event ID number that corresponds to a defined event in a longitudinal project. For classic projects, the event_id is not explicitly required, and thus it will be supplied automatically since there will only ever be one event_id for the project.
repeat_instance
(only for projects with repeating instruments/events) The repeat instance number of the repeating event (if longitudinal) or the repeating instrument (if classic or longitudinal).
(only for projects with repeating instruments/events) The repeat instance number of the repeating event (if longitudinal) or the repeating instrument (if classic or longitudinal).
project_id
(optional) The project ID number of the REDCap project. If the project_id parameter is not provided, it will use the PHP constant
(optional) The project ID number of the REDCap project. If the project_id parameter is not provided, it will use the PHP constant
PROJECT_ID (assuming the method is called in a project context).Return Values
Returns the return code (alphanumeric string of text) for this record-instrument[-event], else it returns NULL if the return code was not found (i.e., if any parameters are incorrect) or if the "Save & Return Later" feature has not been enabled for the survey.
Restrictions
This method can ONLY be used in a project context (i.e. when "pid" parameter is in the query string of the plugin URL) or else a fatal error is produced.
Examples
Example #1:
This example illustrates how to obtain the survey return code for a specific record for a specific survey instrument in a classic (non-longitudinal) project.
// We have our record name and instrument name $record = '101'; $instrument = 'participant_info_survey'; // Get the survey return code for this record-instrument $return_code = REDCap::getSurveyReturnCode($record, $instrument);
Example #2:
This example demonstrates how to obtain the survey return code for a specific record-survey-event longitudinal project.
// We have our record name, instrument name, and event_id $record = '101'; $instrument = 'participant_info_survey'; $event_id = 339; // Get the survey return code for this record-instrument-event $return_code = REDCap::getSurveyReturnCode($record, $instrument, $event_id);
REDCap 14.9.1 - © 2024 Vanderbilt University