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 command panelData() returns an array with the address entry's 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
  'smstime' => (int) Unix timestamp of the SMS's delivery report (if available)
 
  // Only available for respondents with the privacy mode "individual-related", 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) mobile phone number
  'serial' => (string) personID
)

Important: The function only returns an array if the interview was started by clicking the personalized link in a mailing (otherwise NULL). If the respondent is automatically forwarded to a questionnaire after an opt-in confirmation (Multi-Wave Surveys with Self-Recruited Respondents), this is technically equivalent to clicking the personalized link in a mailing.

Note: If the privacy 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 break the confidentiality of pseudonymous address entries and should not be stored in the data set. If the address entry uses the privacy mode “individual-related”, 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.

Note: If the login to the questionnaire is done via single sign-on (SSO), panelData() only returns information immediately after the start of the questionnaire; in this case, place the function on the first page.

If the questionnaire uses the access restriction “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 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 an error message that the questionnaire was not called up with a valid
  // participation key (e.g., not from a mailing) or that the address entry
  // has been deleted from the list of contacts in the meantime
  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);
}