01 - Creating recruitment and profiling surveys
All recruitment and profiling surveys should be "checked" as "Is Profiler", and the proper Q_Panel database needs to be selected in the Panel dropdown.
You can only have recruitment and profiler surveys for 1 particular panel in each project, however you can of course have multiple projects set up.
- All interviews should be started with a link that supplies an "altid" parameter
- For a Recruitment survey, the "altid" parameter should be a unique identifier (typically a GUID) that is used to create the panelist. This is what will be the "ExternalPanellistID" in the panel database and is the identifier to be used by e.g. API's and any other function where you want to uniquely identify the panelist. If one does not have a system for creating such identifiers, typically a GUID should be created and used
- For Profiling surveys, the "altid" should always be "ExternalPanellistID"
- Surveys are to be started with a special link as well: https://survey.quenchtec.net/qpr?ineID&qsid=QSurveyID&altid=ExternalPanellistID (where "qif", "qsid" and "altid" are required parameters)
- As soon as a questionnaire is completed, it is placed on a queue, and the relevant data is transferred to Q_Panel, either to create a new panellist, or to update or add profiling data
- As soon as the data has been transferred, the interview is deleted. No backup or data is kept! The reasons for this is to make it easy to comply with GDPR requirements. In Q_Panel all panellist data can be anonymised and deleted, and special fields can be marked as sensitive. It is then easy to comply to panellist requests about what data you have on file about them, and also it is easy to delete the panellist if they so wish
- All the data that you want to transfer from the questionnaire to the panel database, must be "tagged" (see screenshot below where you need to add this):
- There are reserved tag names that are e.g. mandatory when creating a panellist
- All other tag names should match the existing or desired variable name in Q_Panel. Variable names that exist will be updated, and the ones that does not exist will be created
- For multiple and single choice questions, the "tag" must be on the "sub-question" element (not the question element)
- For all other types, like open-ended text, numeric and grids, the "tag" must be on the row
- Questions that are not "tagged" will not be transferred. Such questions can typically be used for logic
- There can only be one sub-question in a tagged question hence if you have more sub-questions, these must be “transferred” and auto-filled into new questions / sub-questions in order to be tagged correctly
Please note
For Multi and Response questions there is a different default order for QPanel as for QSurvey.
In QPanel the answers start at position 0, in QSurvey this is position 1.
Best to start in QSurvey also with position 0 to prevent any mismatches.
For a recruitment questionnaires there are a number of required and reserved tag names that must be used.
| Special Column Name | Triple-S Variable Data Type |
Max. Size | Description | Q_Survey Question Tag |
Q_Survey Question Type |
|---|---|---|---|---|---|
| character | 255 | The Triple-S variable name storing the panellist's email address | QT_ProfilerEmail | Open | |
| firstName | character | 50 | The Triple-S variable name storing the panellist's first name | QT_ProfilerFirstName | Open |
| lastName | character | 50 | The Triple-S variable name storing the panellist's last name | QT_ProfilerLastName | Open |
| loginName | character | 255 | The Triple-S variable name storing the panellist's login name | QT_ProfilerLoginName | Open |
| password | character | 64 | The Triple-S variable name storing the panellist's password | QT_ProfilerPassword | Open |
To allow panellists to be created in Kentico (e.g. Recruitment questionnaire) the panellist's email address and / or first name & last name must be supplied as well as the password. The Q_Survey question identifiers are required (case insensitive) and these questions must be of type single or multi.
In order to create "Date" or "Boolean" (logical) variables in the panel database, the following suffix should be appended to the tags:
- Boolean: ”_profilerlogical” should be appended to the tag-name (see screenshot below). Such a question should have 2 rows. Yes/No. If the first row has been answered, the variable will be set as "True", if not answered or if row two has been selected, "False" is stored.
E.g tag="carflag_profilerlogical" will address a panel variable called "carflag" - Date: ”_profilerdate” should be added to the "row" tag name on a numeric or open-text row. Such variables will be converted to a date variable in Q_Panel.
E.g. tag="created_date_profilerdate" will address a date variable called "created_date". Date variables should be in the format "YYYYMMDD".
When you have created or changed your profiler survey make sure to "publish" your survey and check if this has run correctly.
In the project folder click on "Profiler Info", you see the status and messages.
Profiling questionnaires initiated from Kentico or Umbraco.
Panel has a mechanism for tracking panelist's completion of profilers, and to set rules for e.g. awarding points for completed profiles. This concept is called VGID (version guid) which is a unique version identifier, each time a panelist tries to complete a profiler questionnaire. This parameter is passed in the QPR link to start the profiler, as "vgid". This parameter comes in addition to the ExternalPanelistId that is passed in the "altid" parameter.
In order to track progress, the profiler questionnaire should report the "Started" once the survey is started, and "Completed" on the last page.
The API call is done through a "reference to question element", with the following script.
\script:QPanelProfilerStatus([BaseURL],[APIToken],[PanelID],[VGID],[Status])
BaseURL - is the URL to the panel database, and is typically fetched from a prefilled question
APIToken - is the API token to communicate with the panel database (also often prefilled into a questions)
VGID - the value from the "vgid" parameter used to start the profiler. Can be referenced directly by "\@sms_vgid", or by referring to a question with the value prefilled.
Status - 'Started' as the first use (e.g. on the "info" welcome page), or 'Completed' on the very last page (typically an "info" thank you page)
Example: \script:QPanelProfilerStatus(\BaseURL.a,\APIToken.a,\PanelID.a,\@sms_vgid,'Started')
Note: References to questions or "sms_" variables are without single quotes. Literals should always be enclosed in single quotes.
If the panelist should just fill in the profiler from scratch every time, just ensure the tagging is done according to the above description. Please note that if a "tagged" question, has no answer (value) the variable will be "blanked" in Panel. So if e.g. you filter questions based on answers to prior questions the "tagged" questions not asked (or where you allow no response), implies that the corresponding variable in Panel will be "blank".
Allowing "updates" to previously conducted profilers.
If you want the panelist to be able to be presented with the current value from Panel, and update it if there are changes, a rather complex approach needs to be taken. This involves fetching the relevant data from Panel, preselecting that value in the relevant question. We have created a set of API calls that should be used in the "reference to question" element, in order to "fetch" the relevant value from Panel. Then one needs to call a JavaScript function, that 1) hides the value returned from the "reference to question" and 2) preselects or fills in this value in the question, so the user sees it selected/filled in, and can update if needed. The JavaScripts we have created, all base themselves on just displaying one variable on a page, except for the single choice and multiple choice grids, that can have a selection for each row. If you are going to display multiple questions on a page, you need to create new javaScript functions that handle this accordingly.
The functions to be used in "reference to question" in order to fetch data is:
To be used to fetch a single character variable from Panel, like "name".
GetSingleExternall([FullURL],[ExternalPanelistId],[ExternalName])
To be used to get a single value (single response, boolean or a numeric)
GetMultipleExternal([FullURL],[ExternalPanelistId],[ExternalName])
To be used to fetch a mutiple response type variable
GetMultipleExternalCodes([FullURL],[ExternalPanelistId],[ExternalName],[noAnswerValue])
To be used to fetch a mutiple response type variable, with a explicit code to be used if no codes are found
GetGridMultipleExternal([FullURL],[ExternalPanelistId],[ExternalName],[numberOfRows])
To be used to fetch the "internal" panelist id based on the ExternapPanelistId.
These functions are intended to be used on a page with just one "tagged" Panel variable (except for the grid versions), so if there is a need for displaying multiple items, a special JavaScript must be created.
If you use iQuests (interactive questions) the call to the JavaScript function must be done "prior" to the iQuest fire function. This means that you need to update the iQuest JavaScript. This is done via "Edit advanced functions" when you click on "Specify" of the iQuest.
At the very end of the iQuest definition, you will find the "iQuestFire" function.
The relevant JavaScript function needs to be inserted as the first line of this function:
In the case of using the "pageReady" function, insert the appropriate call as the first line of the "pageReady" function
All these functions does the following:
1) They hide the "reference to question" element that is used to fetch the data from Panel.
2) reads the data, and copies it or selects the appropriate radio/check box on the page, so it is "Prefilled".
The JavaScript functions are created to just work with one question displayed at the time, e.g just one numeric row, or one open-ended row. Meaning only one "reference to question" also. If this is not the case, the JavaScripts need to be amended in order to handle these. The grid functions can have multiple rows, in case there must be the same number of "reference to question" elements as there are rows. NB, none of the questions should have any "randomization" of rows set.
The JavaScript functions are:
fncSetPanelOpen();
Sets the value for an open-ended question. Normally this is a single-choice question, with one row, The row should be of type "Other". The "tag" should also be on the "row/other" element
fncSetPanelNumeric();
Sets the numeric value into a numeric question, with one row. Again, the "tag" should be on the "row".
fncSetPanelSingle();
Selects a radio button in a single-choice question. The "tag" should be on the "sub-question" element.
fncSetPanelDropdown();
Selects the appropriate value, if the single-choice question is displayed as a dropdown. The "tag" is on the "sub-question".
fncSetPanelDropdownNumeric();
Selects the appropriate value, if the single-row numeric question is displayed as a dropdown. The "tag" is on the "row".
fncSetPanelMultiple();
Selects the appropriate checkboxes in a multiple-choice question. The "tag" is on the "sub-question" element.
fncSetPanelGridSingle();
Selects the appropriate radio button in each row of a single-choice grid question. There must be the same number of "a reference to questions" elements as there are "rows". The "tag(s)" are on the "row" element(s).
fncSetPanelGridMultiple();
Selects the appropriate checkboxes in each row of a multiple-choice grid question. There must be the same number of "a reference to questions" elements as there are "rows". The "tag(s)" are on the "row" element(s).
fncSetPanelMSubMultiple(X);
This is a special one for multiple multiple-choice sub-questions displayed at the same time. "X" must be replaced with the number of sub-questions displayed. The same number of "reference to question" elements must be present too. The "tag" should be on each "sub-question".
Script to adjust points:
If you manually want to adjust a panelist's points, e.g. after a "manual" recruitment, you can use the following script:
\script:AdjustPoints(url, token, panelId, panellistId, points, description)
Script to directly update panel variables:
From both profiler and normal questionnaires, you may call upon scripts to directly update variables. Note: that you here need to use the responseID (NOT the panelistID) in the calls (in a normal invitation to a survey, the responseID is passed as the "altid" parameter in the link, but profilers have the "panelistID" as the "altid" parameter. You must make sure you use the correct variable:
The following functions are available, to update a multiple-choice numeric, single or text variable: