Preload/Hidden Variables and Preloaded Participant Data

Preload/Hidden variables store data that can be saved with a participant’s submitted survey data.   These are not questions that appear on the screen to the respondent, rather data for hidden variables comes from the following places:

1.  The participant list into the participant’s survey.
2.  Data appended to the survey URL
3.  A survey calculation that sets the value of the Preload/Hidden Variable using the DatStat.SetResponseData command
4. Multi-Control Questions and Question Tables use hidden variables to store response data.
5. Custom software developed with the Illume SDK (software development kit) can read and set values stored in hidden variables.

Preloading Data from Participant Lists

Participant Lists are made up of information about the participants invited to take a survey. There may be situations in which it is valuable to load pre-known participant information into a survey, so that this information can be used for show-if logic, calculations, or simply to be stored in the data set.  For example,  if you already know the gender of each respondent, do not burden them by asking that question in the survey.  Rather, you can “preload” that information by putting it onto your participant list, and then creating a variable in Illume (a “Preload/Hidden Variable”) to capture the information off of the participant list.

To preload data from a participant list into a survey, follow these steps:

1. From the Survey Designer’s Survey menu, choose Preload/Hidden Variables

2. Click Add to add a new variable.

3. Type in a name for the variable to load. The variable name must be unique: that is, no other questions or objects in the survey can have the same name as this variable.  The Unique name of the Preload/Hidden variable need not be the same as the name of the column on your participant list, though it is typical for users to give the Preload/Hidden variable the same name.

4. Choose the Value Type to use
   • Single-value will utilize the data type from the drop-down menu. This refers to a Preload/hidden variable that will have exactly one value.

Note: You must carefully select the data type that matches the type of data on your participant list.  If there is not a match in data types, the preloading may fail.  Data type Text will work for any value that is pre-loaded from a participant list. However, if preloaded data is going to be used in a numeric calculation later in the survey, choose either Whole Numbers or Decimal Numbers. Illume cannot perform numeric calculations on Text data-type data.

• Multi-Value (Check All) assumes that data will be passed into the survey in a comma-delimited fashion and, the values correspond to the scale that defined in the Scale tab.

4. Choose a default value for the variable. The following options are available:
   1. None – When participants start the survey, the variable will have no value.
   2. User data – When each participant begins the survey, the variable will be set to a value found in the participant’s participant list entry.   Enter the name of the participant list column from which to populate the data. In the image above, the value for the variable GENDER comes from the participant list column called GENDER. When a participant starts the survey, Illume copies the participant’s gender from the participant into the Preload/Hidden variable.  YOU MUST ENTER THE NAME OF THE PARTICIPANT LIST COLUMN EXACTLY AS IT APPEARS ON THE PARTICIPANT LIST.
   3. Custom – Choosing Custom enables the setting of the default value of the variable to any value you choose. Simply enter the value in the box next to the word Custom. Illume will set the value of this variable to the value entered for all participants starting the survey.

When choosing the Custom option, be sure the value entered matches the variable’s data type. For example, If using Whole Numbers as the data type, be sure to enter a number as the default value; otherwise, the default value will be “unanswered.”

6. (Optional) Check any of the checkbox options described under Special Options for Preloaded Data section below.
7. Type a description for this variable. Unless this is a runtime only variable, the description will appear in the data dictionary along with the descriptions of all other survey questions.

Steps to Create a Scaled Preload/Hidden Variable

1. To add a Preload/Hidden Variable begin by selecting Survey / Preload/Hidden Variables
2. Click Add
3. The Unique name can be anything – this is the name that will appear in the dataset
4. Select the Value Type as Multi-Value
5. The Default Value should be User Data, with the field being the same as the column in the participant list
6. Enter a Prompt Description
7. Click the Scale Tab
8. Enter the Name and visible text for each Value and Click Add
9. The Values should appear in the lower field as they are added.
10. After adding all of the Values, Click OK

 

Special Options for Preloaded Data and Hidden Variables

Disable this preload – This disables the preload without deleting. This may be useful for temporarily turning off a preload.

Automatically generate a scale as unique values are discovered – This option is useful if it is known ahead of time that the number of possible values for this variable will be limited. For example, if preloading the US state in which a participant lives, there are only 51 possible values (including DC). The scale that Illume generates appears in the Data Manager’s Data Dictionary. In the Data Manager, items with scales can be included in cross-tab queries and summary statistic results. This is one of the most common reasons for generating scales for preloaded data.

If the number of possible values is very large, checking this option may cause Data Manager queries to run slowly.

Runtime only (do not store the value of this item) – This option makes the preloaded value available while the survey is running, but does not submit the value to the database when the participant submits the survey. This can be useful for data that is required for calculations, show-if conditions, or runtime display but that should otherwise be kept separate from results.

Conditions Under which Preloads Will Fail

Illume Next will not preload data if either of the following conditions are true:

1. There is no data to preload for the current participant. E.g. The survey preloads each participant’s phone number from the participant list into the survey, but the participant list has no phone number for participant 9999. The preload for participant 9999 will be empty.
2. The data that Illume Next is trying to preload does not match the data type specified in the preload variable. E.g. The survey preloads each participant’s weight into a variable called WEIGHT, whose data type is “Whole Number.” In the participant list, participant 9999’s weight appears as “N/A”. Because “N/A” is not a whole number, Illume Next loads no value into the WEIGHT variable for participant 9999.

The second problem is most likely to occur with variables of type Date, Time and Date/Time. Date and time values must be properly formatted before they can be loaded. See Date and Time Data for more information.

Preloading Data through the Survey URL

It is possible to pre-load data by embedding it in the URL a participant uses to access the survey. There are two things to keep in mind when pre-loading data through the URL:

1. First create the variable in the Preload Editor. Otherwise, Illume Next has no place to store the value it receives in the URL.
2. If the variable name exists in both the participant list and in the URL, Illume Next will use the value in the URL if it is available. If there is no value in the URL, Illume Next will use the value in the participant list, if available.

Passing data to a Multi-Value Preload/Hidden Variable from a Query String

Like all Preload/Hidden Variables, it is possible to pass the information directly from a Query string into the variable.

Use the name added in the Multi-Value Preload/Hidden Variable Userdata field and the Scale Values separated by commas. If the Scale value is not passed it will be assumed to be not selected.

In the example Query String, the Multi-Value Preload/Hidden Variable CRITERIA will be Yes for OPTION1 and OPTION2 and No for OPTION3

Example: http://lorien/46Test-collector/Survey.ashx?Name=MVPreloadTest&LoginID=123455&CRITERIA=OPTION1,OPTION2