panelData()

array panelData()

The function panelData() returns information from the Addresslist if the interview was started by a personalized hyperlink (e.g., from a mailing).

The function panelData() returns a note from the list of Access Codes, if the questionnaire uses the access restriction “Access Code”.

The panelData () command returns in an array including the address entries subgroup, the time of the mail dispatch, and the data stored as user-defined data in the address entry.

array (
  0 => (string) Subgroup
  1 => (string) User-defined data 1
  2 => (string) User-defined data 2
  3 => (string) User-defined data 3
  4 => (string) User-defined data 4
  5 => (string) User-defined data 5
  'subgroup' => (string) Subgroup
  'mailing' => (int) number (ID) of the mailing in which the invitation link was sent
  'mailsent' => (int) Unix timestamp when the mail was sent
 
    // Only available for respondents with data protection mode "Personal", otherwise NULL
  'firstname' => (string) firstname
  'lastname' => (string) lastname
  'gender' => (string) gender ('female', 'male', 'other' or '')
  'email' => (string) email-address
  'email.cc' => (string) email CC-address
  'mobile' => (string) Mobiltelefonnummer
  'serial' => (string) personID
)

Important: The function provide a value only, if the interview was started by click at the personalized link in a mailing (else NULL). In case the participant is forwarded automatically to the survey, after an Opt-In-Confirmation, (Multi-Wave Surveys with Self-Recruited Respondents), than this is equivalent to the click at the personalized link in a mailing.

Note: If the data protection mode is set to “anonymous” for the addressee, panelData() does not return any data (NULL).

Note: If individual sending times are used for the mailing, the information on the sending time (like certain user-defined data) can remove anonymity and should not be stored in the data set. If the address entry is not anonymous, the sending time is automatically stored in the MAILSENT variable in the data set and 'mailsent' returns the same value as value('MAILSENT'). For address entries with data protection mode “pseudonym” or “make anonymous at the end of the interview”, the sending time is only available via panelData() to avoid accidental de-anonymization.

Note: If the respondent has received an invitation and a reminder, 'mailsent' will indicate the time when the original invitation was sent and in 'mailing' is the ID of the original invitation – regardless of whether the respondent calls up the link in the invitation or in the reminder.

If the questionnaire uses the access|restricted access “Access Codes”, panelData() will return the access code used and a note that may be attached to it:

array(
  'serial' => (string) access code
  'note' => (string) note to access code
)

Important: The questionnaire must use the access restriction “Access Codes”, the specification of an access code in the link to the questionnaire is not sufficient. The placeholder %caseSerial% on the other hand will provide the access code even if the questionnaire is public.

The following example is based on the assumption, that the name of the company is placed in field 1 of the address record. Now, the name of the company should be used as the content of the placeholder %company%.

$data = panelData();
if ($data === null) {
  // Error message and abort of the questionnaire,
  // if the questionnaire was not called up with a personalized link
  text('no data');
  buttonHide();
  pageStop();
}
$company = $data[1];
replace('%company%', $company);

In this example, participants register themselves for a study (Multi-Wave Surveys with Self-Recruited Respondents). In the following, participants of the control and experimental group will receive different emails as experimental stimulus. Therefore, their address entries must be assigned to different subgroups. This is done by displaying one of two opt-in questions, depending on a randomly drawn code (Random Generator).

Note: An [:en:create:questions:opt-in|Opt-in question]] can automatically assign a newly registered participant to a subgroup.

if (value('RG01') == 1) {
  question('OI01'); // Opt-In question OI01 sets subgroup "EG".
} else {
  question('OI02'); // Opt-In question OI02 sets subgroup "CG"
}

After opt-in confirmation of the e-mail address, the participant is automatically forwarded to a second questionnaire. Depending on the group affiliation, the stimulus from text module “textEG” or “textCG” is to be displayed and either mailing 2 or 3 is to be sent.

$info = panelData();
if ($info) {
  $group = $info['subgroup'];
  if ($group == 'CG') {
    text('textCG');
    mailSchedule(false, 2);
  } else {
    mailSchedule(false, 3);
  }
} else {
  // Display error message that the questionnaire does not contain a valid participation key.
  // (e.g. when not started from a mailing) or that the address entry was called after
  // the address record had been deleted from the List of Contacts
  text('some-error');
}

For easier analysis, it would make sense to store the group membership via put() in the data set of the second questionnaire. For example, the following PHP code would be added to the IF part of the previous PHP code after an internal variable IV01_01 was added in the List of Questions.

$group = $info['subgroup'];
put('IV01_01', $group);

In this example, mailings are sent to the participants at random times as part of random experience sampling. It is important for the evaluation whether the participant has completed the questionnaire within 30 minutes or not. However, the dispatch time should not be saved in the data record because this could jeopardise anonymity.

With the help of panelData () the exact sending time can now be determined and thus the delay between sending the email and the participation. The PHP function time () returns the current time as a Unix timestamp, the difference is the delay in seconds. If the delay is more than 30 minutes (1800 seconds), the code 2 will be stored in the internal variable IV01_01, otherwise the code 1.

If the sending time cannot be determined, code -1 is stored. This can happen if the interview was not started from a mailing link or if the address entry has been deleted in the meantime by the project manager or the respondent.

$info = panelData();
if ($info) {
  $sent = $info['mailsent'];
  $delay = time() - $sent;
  if ($delay <= 1800) {
    put('IV01_01', 1);
  } else {
    put('IV01_01', 2);
  }
} else {
  put('IV01_01', -1);
}