| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| en:create:functions:paneldata [03.02.2018 22:15] – Full update admin | en:create:functions:paneldata [25.04.2025 19:33] (current) – [Return Value (Adresslist)] admin |
|---|
| ====== panelData () ====== | ====== panelData() ====== |
| |
| ''array **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 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 [[en:create:access|access restriction]] "Access Code". |
| ===== Return Value ===== | ===== 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. | 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> | <code php> |
| array ( | array ( |
| 0 => (string) Subgroup, | 0 => (string) Subgroup |
| 1 => (string) User-defined data 1, | 1 => (string) User-defined data 1 |
| 2 => (string) User-defined data 2, | 2 => (string) User-defined data 2 |
| 3 => (string) User-defined data 3, | 3 => (string) User-defined data 3 |
| 4 => (string) User-defined data 4, | 4 => (string) User-defined data 4 |
| 5 => (string) User-defined data 5, | 5 => (string) User-defined data 5 |
| 'subgroup' => (string) Subgroup, | '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 | '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 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> | </code> |
| |
| **Important:** The function provide a value only, if the interview was started by click at the personalized link in a mass mail (else ''zero''). 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. | **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 (Access Codes) ===== |
| | |
| | If the questionnaire uses the [[en:create:access|access|restricted access]] "Access Codes", ''panelData()'' will return the access code used and a note that may be attached to it: |
| | |
| | <code php> |
| | array( |
| | 'serial' => (string) access code |
| | 'note' => (string) note to access code |
| | ) |
| | </code> |
| |
| **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')''. | **Important:** The questionnaire must use the access restriction "Access Codes", the specification of an access code in the [[:en:survey:url|link to the questionnaire]] is not sufficient. The [[:en:create:placeholders|placeholder]] ''%caseSerial%'' on the other hand will provide the access code even if the questionnaire is public. |
| |
| |
| |
| |
| ===== Example: Experiment in two-wave survey ===== | ===== 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]]). | 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]]). |
| // Display error message that the questionnaire does not contain a valid participation key. | // 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 | // (e.g. when not started from a mailing) or that the address entry was called after |
| // the address record had been deleted from the address list | // the address record had been deleted from the List of Contacts |
| text('some-error'); | text('some-error'); |
| } | } |
