| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| en:create:functions:paneldata [03.02.2018 22:15] – Full update admin | en:create:functions:paneldata [23.10.2026 14:44] (current) – external edit 127.0.0.1 |
|---|
| ====== 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 (List of Contacts) ===== |
| |
| ===== Return Value ===== | 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. |
| | |
| 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 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 |
| ) | ) |
| </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 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 ([[:en:survey:opt-in-live]]), this is technically equivalent to clicking the personalized link in a mailing. |
| | |
| | **Note:** If the [[:en:survey:mailing:privacy|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 [[:en:survey:mailing:privacy|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. |
| | |
| | |
| | ===== Return Value (Access Codes) ===== |
| | |
| | If the questionnaire uses the [[:en:create:access|access restriction]] "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]]). |
| |
| **Note:** An [:en:create:questions:opt-in|Opt-in question]] can automatically assign a newly registered participant to a //subgroup//. | **Note:** An [[:en:create:questions:opt-in|opt-in question]] can automatically assign a newly registered participant to a //subgroup//. |
| |
| <code php> | <code php> |
| } | } |
| } else { | } else { |
| // Display error message that the questionnaire does not contain a valid participation key. | // Display an error message that the questionnaire was not called up with a valid |
| // (e.g. when not started from a mailing) or that the address entry was called after | // participation key (e.g., not from a mailing) or that the address entry |
| // the address record had been deleted from the address list | // has been deleted from the list of contacts in the meantime |
| text('some-error'); | text('some-error'); |
| } | } |
