An Illume survey can capture any data passed in through the query string of the survey URL. This data is treated as if it came from the participant list. Participant list data and data that comes in through the query string of the survey URL have the following characteristics:
- The data are NOT saved with the participants’ responses, unless it is explicitly made to happen (see Saving Data From the Query String below)
- The data are available throughout the survey for use in piping, calculations, and show-if conditions.
NOTE: Information passed in a Query String is NOT encrypted.
A Practical Example
Assume there is a survey with 2 different email invitations: one invitation offers participants a free music CD for completing your survey, and the other invitation offers participants a $10 check.
The first invitation includes the following survey URL:
https://www.datstat.com/Collector/Collector.ashx?Name=SurveyName&LoginId={userdata:LOGINID}&INCENTIVE=FREECD
The second invitation includes this URL:
https://www.datstat.com/Collector/Collector.ashx?Name=SurveyName&LoginId={userdata:LOGINID}&INCENTIVE=CHECK
It is possible to get the values of these variables anywhere in a survey by typing {UserData:Incentive} or {UserData:Criteria.OPTION1}. (The case of the letters does not matter. The curly braces do!)
A question can be created in the survey that asks which music CD the participant would like to receive, then set a show-if condition on that question so that it appears only when {UserData:Incentive} equals “FREECD”. While variable names in the URL are case-sensitive in most web-based applications, variable names in the URL of an Illume survey are not case sensitive. The Illume server does not differentiate between INCENTIVE=CHECK and incentive=CHECK.
Saving Data from the Query String
Like data from the participant list, data from the query string is not automatically saved with the participant’s responses.
To save the Incentive data from the example above, follow these steps:
- Decide ahead of time what the name of the variable will be! For this example, we will use the variable name INCENTIVE.
- In the Survey Designer, choose Survey / Preload/Hidden Variables….
- Click the Add button.
- Enter a unique name for the data. This name will appear in the Data Dictionary and will be the name of the variable in which the data are stored in the Data Manager. For this example, we will call the variable PAYMENT_TYPE.
- Choose a data type that matches the data that is expected to be passed in the query string. For the INCENTIVE example above, choose Text.
- Under Default Value, choose the User data option.
- In the text box next to User Data type the name of the variable that will appear in the URL. For example, if the variable in the URL is called INCENTIVE, then type INCENTIVE here. This tells Illume to take the data from the INCENTIVE variable in the survey URL and to store them in the variable PAYMENT_TYPE when the participant submits the survey.
- (Optional) Click the Scale tab and choose a scale option for this variable. A scale can be useful for creating calculated variables, show-if conditions, and data queries. The scale options include: Do not use a scale for this item – This is a good choice when the list of potential values for the variable is large. Automatically generate a scale as unique values are discovered. This is useful if the variable may include an unknown set of responses within a limited range. For example, if passing the name of a partner site through the URL, it may not be known ahead of time who all the partner sites will be, but it is known that there will not be more than a few dozen of them. Predefined – Use this if it is known ahead of time all of the possible values that the variable may store.
- Click OK.
NOTE: The Preload Editor first looks in the participant list for the field named in User data name, and then it looks at the contents of the survey URL. If the participant list already contains a field called INCENTIVE, and a value of INCENTIVE is passed on the URL, then {UserData:Incentive} will contain the value passed in through the URL rather than the value from the participant list. In short, the value from the URL overrides the value from the participant list.
General Notes about URLs and Query Strings
The query string portion of a URL consists of everything after the first question mark in the URL.
In the example below, the query string appears in bold italics:
https://www.datstat.com/Collector/Collector.ashx?product=gadget&incentive=freecd&source=yahoo+shopping This query string includes 3 variables: product (this might indicate the type of product the participant purchased), incentive (which may indicate the type of payment the participant has been promised) and source (which may indicate the page or web site on which the link to the survey appeared). Each variable is represented by the variable name, followed by an equal sign =, followed by the variable’s value. Each name-value pair in the query string is separated by an ampersand &. Variable names should include only letters, numbers and underscores. Spaces in variable values must be represented by a plus sign +. (Notice that the source in the URL above, yahoo shopping, appears as yahoo+shopping.)
Reserved Words
The following variable names are reserved for use by the Illume server. These variable names cannot be used in the URL:
- Name
- Path
- XmlDocument
- LoginId
- PageLayout
- PrintPreview
Words with Special Meaning
The following words have special meaning in the URL. You may use them, but you should understand first what they do.
- TESTDATA – If this is set to 1, the survey will be marked as test data when it is submitted.
- Translation – If this is set to a numeric or character LCID, Illume will attempt to present the survey in the language represented by that LCID.
- LCID – This has the same effect as Translation above.
Adding a Test Data Flag in the Survey URL
If the URL used to access a survey includes TESTDATA=1 in the query string, the data from that survey will be marked as test data.
For example, in a survey that uses the variable DATSTAT_ALTPID to authenticate participants, the following survey URL would give participant 9999 access to the survey:https://www.datstat.com/Collector/Collector.ashx?DATSTAT_ALTPID=9999
When the participant submits the survey that he or she accessed through this link, the data will be saved as normal response data.
For testing purposes, the participant could access the survey through this URL:
https://www.datstat.com/Collector/Collector.ashx?DATSTAT_ALTPID=9999&TESTDATA=1
Any data the participant submits after accessing the survey with this URL will be treated as test data. The Data Manager separates normal participant data and test data so that test data does not skew actual results.
NOTE: Each participant can only take an authenticated survey once, unless this participant is a test participant or the survey session is marked as a test session by appending “&TESTDATA=1” to the URL.
Avoid using real participants to submit test data, because doing so could prevent the participant from being able to take a survey and will possibly skew your non-test data.
Other Query String Parameters
Name – Name of survey to be taken
LoginId – Specifies credentials for auto-authentication
Translation – Displays a specific language of survey
TestData – Setting to ‘1’ (e.g. TestData=1) will ensure this is a test survey session
TestSurvey – Allows a test survey to be viewed
_RS_ – Suppresses the resume survey page from appearing
_LNP_ – Displays launch page of the survey. Used if chrome-less survey is desired
_LNPD _ – Set on the launch page of the survey. Done with launch page.
PageLayout – Used by Survey Designer when displaying the survey in page layout mode
PrintPreview – Used by Survey Designer when displaying the survey in print preview mode
DATSTAT.RMSPSID – Id of scheduled survey for a specific participant in RMS
DATSTAT.INTERVIEWER – Id of Illume user that is the interviewer for this survey (value is stamped in the survey session)