====== 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 **serial numbers**, if the questionnaire uses the [[en:create:access|access restriction]] "serial number".
===== Return Value (Adresslist)=====

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.

<code php>
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
)
</code>

**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, ([[:en:survey:opt-in-live]]), than this is equivalent to the click at the personalized link in a mailing. 

**Note:** If the [[en:survey:mailing#data protection mode|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.


===== Return Value (Serial nNumbers) =====

If the questionnaire uses the [[en:create:access|access|restricted access]] "serial number", ''panelData()'' will return the serial number used and a note that may be attached to it:

<code php>
array(
  'serial' => (string) serial number
  'note' => (string) note to serial number
)
</code>

**Important:** The questionnaire must use the access restriction "serial number", the specification of a serial number in [[:en:survey:url|link to questionnaire]] is not sufficient. The [[:en:create:placeholders|Placeholder]] ''%caseSerial%'' on the other hand will provide a serial number even if the questionnaire is public.

===== Example: Importing data =====

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%''.

<code php>
$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);
</code>


===== Example: Experiment in Two-Wave Survey =====

In this example, participants register themselves for a study ([[:en:survey:opt-in-live]]). 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 ([[:en:create:questions:random]]).

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

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

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.

<code php>
$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');
}
</code>

For easier analysis, it would make sense to store the group membership via ''[[:en:create:functions: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 [[:en:create:questions:internal|internal variable]] IV01_01 was added in the **List of Questions**.

<code php>
$group = $info['subgroup'];
put('IV01_01', $group);
</code>


===== Example: Time between invitation and participation =====

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 [[:en:create:questions:internal|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.

<code php>
$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);
}
</code>