To create a new question in an empty survey:

1. Click the Add Question  icon in the toolbar.

2. Set the desired options for the questions.

3. Click OK .

To insert a question into a survey that already contains questions:

1. In the left pane of the Survey Designer, select the folder in which the new collection is being added. Click once on the name of the folder to select it.

2. Click the Add Question  icon in the toolbar.

3. Set the desired options for the questions..

4. Click OK .

 

Mouse and Keyboard Shortcuts

Once the collection has been selected in which a new question is to be added, use any of the following methods to create a new question:

Response options appear on the Response Options tab of the Question Editor. This is where a question’s list of available responses are defined. The options available on this tab vary, depending on the type of question. For Text Field and Commentary questions, the only item on the response options tab will be the Data Type list.

This section focuses on configuring response options for ‘Select One’ and ‘Check all that apply’ type questions.

To set response options:

1. Choose a data type. A data type can only be chosen if the question uses the ‘”Select One’ or ‘Text Field’ display type.

2. If a numeric data type is chosen, add scale values, as described below. If the Yes/No data type is chosen, define the Yes/No values, as described below.

3. If the response options for this question are to be ordered randomly for each participant, check Randomize Display Order.

Choosing a Data Type

The type of data chosen here is the type of data that will end up in the data set for this particular question. Generally, whole numbers are used for Select One type questions.

Illume Next  recognizes the following data types:

 

Setting a Default Value

A default value can be set for a question by typing the value into the Default field. Default values are optional. The value entered in the default field will be pre-selected the first time the participant sees this question on the survey. The participant is free to change or accept the default selection. Use one of the following two methods to set the default value:

See “Piping Data” for general information about piping, or “Setting Dynamic Defaults and Bounds” for more specific issues to consider when piping data into a question’s default value of response guides.

 

Adding/Editing Scale Values

Scale values are the options from which participants may choose when responding to a question. To add numeric scale values, follow these steps:

1. Type the value in the small text box to the left of the equal sign.

2. Press the Tab key to move the cursor into the display text field, then type the text the participants should see for this option.

3. Press the Enter key. This adds the value to the list of scale values below, and returns the cursor to the value text box.

4. Repeat steps 1-3 until all of the options wanted for this question have been added.

Note that for each response option, the value is what will be stored with the data set, while the display text is what participants will see when they are reading through the question’s available answers.

If a user does not want to type a value for each individual response option, and it is known that the values will be in sequential order, check the box labeled “Generate values automatically”, and indicate the number at which the values should begin. Then response options can be added by typing them into the display text field and pressing Enter.

 

Response Options for Check All That Apply Questions

For each checkbox in a “Check all that apply question,” a name must be supplied for the checkbox as well as the text that should appear next to the checkbox.

Choose a name for each checkbox that will be helpful during data analysis, so the data analyst can see instantly what the participant was saying yes to when they checked the box.

 

Mutually Exclusive Response Options for Check All That Apply Questions

A Check All That Apply question can include one or more mutually exclusive check box responses. Mutually exclusive check boxes allow survey designers to specify “Does not apply” or “Refuse to answer” type responses in Check All That Apply questions. When one of these responses is checked no other responses can be checked.

To make a response option mutually exclusive, click the Response Options tab in the question editor and then click the checkbox in the Exclusive column for the desired response option.

When JavaScript is enabled, the client web browser prevents having a mutually exclusive check box being checked when other check boxes are checked. If JavaScript is not enabled both types of check boxes (exclusive and non-exclusive) are able to be checked at the same time and this condition will be caught on the server and an error message will be displayed. The error message can be edited by clicking Edit Preferences and the Error Messages tab. In the drop-down menu select the error for: A mutually exclusive check box is checked when other check boxes are checked.

When a mutually exclusive checkbox is selected, the response guide for minimum # of responses is ignored if set to a value greater than 1.

 

Setting Show-if Conditions on Responses

A user may want to display response options only under certain conditions. To set show-if conditions on a response option:

1. Click on the option in the list at the bottom of the Response Options tab.

2. Click on the Show-if… button to get to the show-if editor.

In this image above, the circle to the left of the first option is yellow because this option includes a show-if condition. Once the Show-if button is clicked, the process is the same as setting a show-if condition for a question, which is described in detail in “Setting Show-if Conditions”.

Once a show-if condition is set for a response option, the Survey Designer displays a yellow control-type image next to the question to indicate that some response options have display conditions attached. In the image below, the question FREQ includes response options that display conditionally. For the other questions, all response options always appear.

Attaching a Text Field to a Scale Value

A text field may be attached to a scale value question to allow participants to explain their responses. For example, if one of the response options is “Other (please specify)”, participants should be given a place to specify what they mean by “other.” If the response option has not yet been added to the list, create the option as described above then check the “Attach text field” box and click the Add button to add the option to the list. In the list of response options, notice that when an item has an attached text field, the Text Field box next to that item is checked. To add a text field to an item that is already in the list of response options, simply check the “Text Field” box next to the item in the list. To delete the text field, uncheck the box.

 

Setting Properties for Attached Text Fields

After attaching a text field to a response option, the user may want to set some properties for the text field. To do so, follow these steps:

1. In the list of available response options, click once on the option whose text field is to be configured.

2. Click on the Text Field Properties button.

3. Set the desired properties (described below).
4. Click OK .

 

The General Tab of the Scale Text Question Editor enables you to configure the following properties:

 

The Response Guides tab of the Scale Text Question Editor enables the following properties to be configured:

 

Attached Text Field Properties in Multilingual Surveys

If a survey includes multiple translations, the user will want to separate translations for any labels and error messages belonging to attached text fields. Generally, this is done by creating a Translation Package, but in some cases, these items may need to be edited individually.

To set the label, description, and error message for an attached text in a specific language:

1. Open the question to which the text field is attached in the Question Editor.

2. Click the Response Options tab.

3. Choose the translation to work with from the list at the bottom of the Question Editor.

4. Click on the scale value whose attached text field is being edited.

5. Click Text Field Properties.

6. Edit the label, description, and/or error message in the Scale Text Question Editor.

7. Click OK to close the Scale Text Question Editor.

8. Click OK in the Question Editor to save changes.

The changes made to attached text field properties affect only the language that was selected when the Scale Text Question Editor was opened.

Randomizing Display Order and Anchoring Options

By default, Illume Next presents response options to participants in the same order they appear in the Question Editor. If the Randomize Display Order box is checked, Illume Next will present the options in random order. Even when response options are presented in random order, a user may want to fix the location of certain options. For example, if a question includes an “Other” or “I choose not to answer” option, it may be appropriate for this option to always appear last. To ensure an option appears in a particular place within a randomized list, check the option’s Anchored box. In the screenshot above, the 4th option, “Other,” is anchored as the last item on the list. While the other three options are shuffled around, “Other” will always appear as the last option. Checking the Anchored box caused the corresponding option to appear on the survey in the same position in which it appears in the Question Editor. Thus, clicking the Anchored box next to the second option in the list, “I work part time,” would cause “I work part time” to always be displayed as the second option. Similarly, dragging “Other” to the top of the list of options, and leaving the Anchored box checked would cause “Other” to always be displayed as the first response option.

Editing an Existing Response Option

To edit an existing response option:

1. In the list of existing response options, click once on the text of the option being edited.

2. The option’s text and value will be loaded into the editable fields above the list. Edit these as necessary.

3. (Optional) Check Attach text field to attach a text field.

4. Click the Replace button. The old option details will be replaced by the new option details in the list of existing options.

Deleting a Response Option

To delete a response option:

1. In the list of existing response options, click once on the text of the option to be deleted. The option should be highlighted after it has been clicked on.
2. Click the Remove button.

Configuring Yes/No Response Options

The only available data type for Yes/No questions is Yes/No. Unless these values are redefined, “No” answers are stored as zero (0) and “Yes” answers are stored as one (1) in the survey results.

If desired, this can be changed by assigning scale values as described below. In some cases, a user may want the value 1 to represent No. For example, if there is a calculated variable that adds up all the No answers, you’ll need to set No to 1, or the calculated variable will just keep adding up zeros, which doesn’t do any good.

The text typed next to the No option (i.e. next to the zero) will not be displayed in the survey . It will appear in the data dictionary to describe what it means when a participant did not check the checkbox for this question.

The text typed next to the Yes option (i.e. next to the one) will appear next to the checkbox in the participant’s survey.

Setting the default state for a Yes/No item to “None” or to “0” leaves the checkbox unchecked by default. Setting the default to “1” leaves the box checked by default.

Date and Time Data

Text questions can be of virtually any data type, including Date, Time, and Date/Time. Illume Next uses Microsoft’s .NET DateTime object to store dates and times. The .NET DateTime object can represent dates between 12:00 a.m. January 1, 0001 CE and 11:59:59 p.m. on December 31, 9999. Illume Next considers dates outside of this range to be invalid. The range can be narrowed by setting minimum and/or maximum dates in a question’s Response Guides. Non-existent dates are also invalid. For example, February 29, 2005 is invalid because 2005 is not a leap year. A participant must enter dates or times in a format that .NET recognizes. In general, for the United States locale, dates in the following formats are valid:

Other date formats will also work in the US. It is best, however, to suggest a format that will work in either the question prompt or in the question label. For example, a prompt that suggests a valid format would be: Please enter your date of birth (mm/dd/yyyy).

Illume and .NET recognize both 12- and 24-hour time format, though Illume may ignore the seconds. The following time formats are valid in the US locale:

.NET uses the same standard set of date and time formats that other Microsoft products use. This means that any Date, Time, or Date/Time format produced by an application like Microsoft Excel, Access, or SQL Server will work in Illume Next. Use the Date data type only for variables that must include a day, month, and year. If a variable requires only one of these values (day or month or year), choose the whole number or text data type. Choose Date/Time data type only for variables that require a day, month, and year value with an optional time value.

Dates, Times, and Localization

Illume Next and .NET use the locale settings of the Illume Next server to determine dates and times. This can cause some confusion if a survey is not designed correctly. For example, if a survey is being administered to participants in both the US and the UK, be aware that the two locales use different date formats. A US participant entering 06/12/2006 will mean June 12, 2006, while a British participant entering the same thing will mean December 6, 2006. If the survey is running on a server whose locale is set to EN-US (English, United States), the date will always be interpreted as June 12. If the server’s locale is set to EN-GB (English, Great Britain), the date will always be interpreted as December 6. This will be a problem if the question includes a minimum and/or maximum date. The British user or the US user may not be able to get past the date question simply because the participant and the server do not agree on what the date means.

One way to avoid date/time problems caused by local differences is to break dates and times into separate questions, each of which is of type whole number. For example, instead of asking for a participant’s birth date, ask for his or her year of birth, then month of birth, then day of birth.

Display of Date and Date/Time Datatype Questions

Questions of Date datatype automatically display to the participant with a calendar icon for easy selection of dates and times.  The rendering of this calendar will appear differently depending on the type of device utilized to launch the survey.

Desktop rendering:

Mobile rendering:

General options appear on the General tab of the Question Editor and include a question’s display type and prompt. The prompt is the text to which the participant is supposed to respond (e.g., “What is your name?”).  A question’s prompt will appear in a participant’s browser exactly as it is typed in the prompt field. Note, however, that HTML tags within a prompt will be ignored when the question is displayed.

When a display type is selected, an example of the display type appears in the yellow box to the right of the Display Type list.

Display types include the following:

If editing a multilingual survey, and the translation tools are enabled, there will be a list of languages at the bottom of the Question Editor. Choose the language to be edited from the list, and the prompt for that language will appear, if the question has been translated. The prompt may be edited, and the edits will apply to that translation of the prompt only.

 

It is possible to import response options for questions and question tables, from Microsoft Word documents formatted in a variety of different layouts. A custom Word format can be specified and saved as a default import template for future questions.

Importing from Clipboard

1. Select, and Copy, the responses from the Microsoft Word document or other text document.

2. On the Response Options tab of the Question Editor Click on the Import button and select Import From Clipboard.

3. The copied responses will be listed with automatically generated values starting with “1” unless a starting value is specifically set.

4. Select a response to edit the value or text if desired.

Importing from Clipboard Special

There may be times when responses in a MS Word document will not conform to the standard layout. The values may be on the right, the values may have specific numerical significance or other formatting differences.

1. Select, and Copy, the responses from the Microsoft Word document or other text document.

2. On the Response Options tab of the Question Editor Click on the Import button and select Import From Clipboard Special.

3. The Import Response Options From Clipboard Editor window will open.

4. For the example in the graphic above, select Right from Value Position.

5. The values will be replaced with the ones copied.

6. Click Save as Default if there will be more responses imported with this format.

7. Click Import to add.

Other Examples of Special Layouts

Likert/Top Response Type

Likert/Bottom Response Type

Importing Response Options from another Question

There are two ways to import the responses from one question to another.

Steps to Import from another Question

1. While in the Response Options tab of the new question, click the Import Button and select Import From Question.

3. Select the Question to import from in the top pane.

4. Select the Import Options.

5. Click Import.

Importing Responses

There are four different options that can be selected in combination when importing responses from another question within a survey:

When importing from a Check All That Apply question type, it is possible to check the Prefix for new checkbox variable names to ad a prefix to each of the responses in the second question.

Importing across Display Types

It is possible to import responses across Select One and Check All that Apply display types.

Check All that Apply to a Select One: All of the responses will come over with the logic option.  The Values will be set in a sequential order starting at 1.

Select One to a Check All that Apply: All or the responses will come over with the logic options. The names of the responses will be the Prefix with sequential numbering e.g. C1, C2, C3… – if C was the prefix set.

 

The Display Properties tab of the Question Editor enables the user to control some aspects of a question’s appearance. The available display options are described below.

 

General: Label and Label Position, Anchor When Randomized

The Label options apply to questions of Text display type only. If a label is typed in the Label field, the text of the label will be displayed to the left of the text box, to the right of the text box, or inline (meaning displayed within the text box). For example, a “$” label might display to the left of a text box in which participants are expected to enter a dollar amount; a “%” label would appear after a text box in which participants are expected to enter a percentage amount.

In the example below, MM/DD/YYYY appears inline:

Checking the box ‘Anchor this item when randomized’ ensures that when items on a page are randomized (by putting those items into a collection and selecting the option to randomize the options within the collection), that this specific item retains its position on the page.

Text Display Width

Text display width applies only to questions of text and commentary display type. The display width is the width, measured in characters, of the Text Field or Commentary.  For text display type, only display width is enabled.  For commentary questions, users may also alter the display height.

Checking ‘Hide Text (Password Style)’ ensures that when participants enter text into the field, it is replaced with security bullets, as in the screenshot below:

Columns

This applies to select one and check all that apply display types only.  By default, Illume displays all of checkbox/radio options in a single column. When there are many options in a list, it can be beneficial to display the options in multiple columns to save space on the screen and minimize vertical scrolling.  This can be overridden by changing the number of columns.

Select One Style

This option applies to select one type questions only. Select one questions can be displayed in any of the following formats:

Radio button: Radio buttons have the advantage of allowing participants to see all of the available options at once.

Likert scale: Likert scales convey to the participant that he or she is choosing a value from a continuum in which the two ends represent opposing extremes.

Poplist: Poplists have the advantage of being able to present a large number of options in a small amount of space.

Column Width

This applies to select one display type questions wherein the likert scale select one style is selected.  The likert scale style essentially creates a one row table, with each of the options being the columns of the table.  By default the width of each column sizes to the length of the column header/label.  It is important that columns display with equal width, as there are data to show that participants are more likely to choose options listed under the column of greatest width, despite the option that column represents.

The Response Guides tab of the Question Editor enables a user to define what constitutes a valid response for a given question. This tab includes the following properties:

 

Response Required

This indicates whether the current question requires a response. By default, all questions inherit the survey-wide required setting. In the example above, the survey-wide preference is set to not required. The question itself is set to required.

Minimum Length (chars)

The minimum number of characters required for a valid response to this item. This applies only to text field and commentary items.

Maximum Length (chars)

The maximum number of characters allowed for a valid response to this item. This applies only to text field and commentary items.

Min # of Responses

The minimum number of items that must be checked in a group of checkboxes. For example, if participants are asked to select at least three items from the list of checkboxes, the minimum number of responses should be set to 3. This applies only to ‘Check all that apply’ type questions.

Max # of Responses

The maximum number of items that may be checked in a group of checkboxes. For example, if participants are asked to select no more than three items from the list of checkboxes, the max number of responses should be set to 3. This applies only to ‘Check all that apply’ type questions.

Format (meta-type)

Check this option and select a meta-type from the accompanying list if participants’ responses should be of a particular type (such as email address, phone number, etc.).

Custom Expression

To have a participant’s response match a regular expression, enter the regular expression here. Writing regular expressions generally requires specialized knowledge. However, regular expressions to validate US and international phone numbers, zip codes, and other types of meta-data can be found by searching the Internet.

Lower Bound

The minimum allowable value for a numeric response. Note that it is possible to specify whether responses may not be less than (<) or may not be less than or equal to (<=) the minimum value.

Upper Bound

The maximum allowable value for a numeric response. Note that it is possible to specify whether responses may not be greater than () or may not be greater than or equal to (=) the maximum value.

A user can set both the upper and lower bounds to compare against values that a participant has entered in response to prior questions. That is, it is possible to require that the answer to the current question must be greater than (or less than) the answer to a previous question. See Setting Dynamic Defaults and Bounds for details. If setting bounds for a question that uses the Date, Time, or Date/Time data type, see ‘Date and Time Data’ in Setting a Question’s Response Options for some important considerations.

Custom Error Message

This is the message participants will see if 1) they fail to enter a response when the response is required, or 2) the response they enter does not meet the question’s validation requirements.

If this is left blank, Illume Next will use the appropriate system-wide default error message defined in the Survey Preferences. See Customizing Survey Error Messages for more information about survey-wide error messages.

Illume Next enables the piping of relevant data from the current question directly into a custom error message. This makes the error messages more useful to participants, and relieves survey designers of the burden of having to update error messages when questions change.  See the section on Piping Data for a detailed description of how to pipe data into custom error messages.

Enforcement of Response Guides

Illume Next surveys enforce response guides both in the participant’s browser and on the server. If the participant’s browser does not support JavaScript, response guides will be enforced by the server. When an error occurs, participants will be presented with the page they just submitted, with error messages printed above the question.

Users who have JavaScript enabled (typically more than 95% of users) will see both a JavaScript alert and the red-text error message.

On the Response Guides tab, under Text Bounds select “Format (meta-type)”.  Open the provided pop-list and select Custom.  This will enable a text box wherein Users can enter custom RegEx.

For additional Information:

http://msdn2.microsoft.com/en-us/library/1400241x.aspx

All formulas begin with “^” and end with “$”

Examples:

Illume Next surveys include a Data Dictionary, which is automatically generated. The Data Dictionary lists all variable names, question prompts, and response options. The Data Dictionary is available to view and print.

 

Unique Name

This is the name of the variable in which responses to the current question will be stored. For example, if this question is given the name HOMEPHONE, then the data that participants give in response to this question will be stored in a database field called HOMEPHONE.  The name supplied here will also appear as the name of the current question in the Survey Designer. Although Illume Next generates the data dictionary automatically starting with Q1 for questions, it may be beneficial to exercise some additional control over what goes into the data dictionary to assist your analysts.

A unique name must start with a letter, and can contain any combination of letters, numbers, underscores (_), or hyphens (-). Unique names must be 20 characters or less in length.

Description

If the description is left blank, Illume Next automatically uses the question prompt as the description in the data dictionary.  At times, however, the user may want to provide more information than the prompt can give.

If a description is typed here, that description, rather than the question prompt, will appear in the data dictionary. This can help quite a bit when analyzing data and trying to determine how the variable AGE1 differs from AGE2.

Runtime Only

By default, the data collected in a survey question is persisted into the data set.  Check the runtime only box if responses to the current question should not be stored with the rest of the data collected in the survey. Runtime only data are available to Illume Next when a participant is taking a survey and are discarded when the survey is submitted. This type of data is often used in calculated variables and show-if conditions.  Runtime only variables will not appear in the data dictionary, and will not be available for download in the Data Manager.

It is possible to set conditions on when Text/HTML items, Questions and Collections will appear, as well as, when/if specific responses are available to a participant. Each of the editors for these items include a Show-if tab that enables a user to define when the item should be displayed.  The show-if tab allows users to specify that an item should be always shown, conditionally shown, or never shown (disabled).

Show State

An item set to ‘Always shown’ will be presented to all participants, and will appear in the Survey Editor with a green circle next to its name. By default, all questions, collections, Text/HTML items and page breaks are always shown.

An item set to ‘Never shown’ will not be shown to any participants, and will appear in the Survey Editor with a red circle next to its name.  It will still be in the data dictionary, and any data collected in that field prior to it being set to never shown will be available for download in the Data Manager.

Adding Show-if Conditions to Items

An item set to ‘Only show if’ will be displayed only if the conditions that have been defined are met and will appear in the Survey Editor with a yellow circle next to its name. Follow these steps to set show-if conditions:

1. Check the ‘Only show if’ option at the top of the Show-if tab.

2. In the Collection list, click once on the name of the collection that contains the question to be tested. The  questions in the collection will appear in the item list to the right.

3. Click once on the question to be tested. The name of the question appears in bold blue type beneath the Collection list. Underneath the question name will be a pop-up list with the words “was-not-answered”.

4. Select the test type from the pop-up list. Notice that if any test type other than “was-answered” or “was-not-answered” is chosen, a list of responses to the selected question appears to the right. (This is true only if the question being tested has multiple response options.)

5. Select the value to test from the list on the right. If testing a text or Yes/No question, the value being tested must be typed in. If testing whether the response “is-any-of” or “is-none-of,” multiple options can be checked in the list on the right.

6. Click Add to apply this condition.

7. (Optional) Add more conditions by repeating steps 2-6.

8. (Optional) If more than one condition has been defined, then how to group the conditions must be decided. If ‘And’ is selected from the list labeled ‘Group all expressions with’, then the current question will be shown only when ALL of the conditions defined have been met. If ‘Or’ is selected, the question will appear when ANY of the conditions have been met. Custom groupings for conditions may also be defined.

9. Click OK to save the conditions.

Editing Existing Show-if Conditions

To edit existing Show-if conditions:

1. In the Survey Editor, double click on the item to be edited.

2. Click on the Show-if tab.

3. In the list of conditions at the bottom of the Show-if tab, click on the condition to be edited.

4. Follow steps 2-5 under Adding Show-if Conditions above.

5. Click Replace (not Add) to replace the condition.

6. Click OK to save changes.

Removing Individual Show-if Conditions from an Item

To remove individual show-if conditions:

1. In the Survey Editor, double click on the item to be edited.

2. Click on the Show-if tab.

3. In the list of conditions at the bottom of the Show-if tab, click on the condition to be removed.

4. Click the Remove button.

5. Click OK to save changes.

Removing All Show-if Conditions from an Item

To quickly remove all of an item’s Show-if conditions:

1. In the Survey Editor, double click on the item to be edited.

2. Click on the Show-if tab.

3. Check the Always shown option.

4. Click OK to save changes.

Setting Show-if Conditions for Prompts within a Question Table

To set show-if conditions on the individual prompts within a question table, follow these steps:

1. In the left pane of the survey designer, click on the Question Table to be worked with. Note in the image below that the MATRIX question table is selected in the left pane, and the prompts belonging to the MATRIX question table appear in the right pane.

2. In the right pane, double click on the prompt.

3. Click the Show-If tab in the Prompt Editor.

4. Follow the instructions under ‘Adding Show-if Conditions’ above.

5. Click OK.

If creating a question table with many prompts that will share the same show-if conditions, save time by creating one prompt with the show-if condition, then copying it repeatedly and changing the prompt text. To copy a prompt, right click on the prompt and choose Copy, then right click again in the right pane of the Survey Editor and choose paste. Change the name and the prompt for the new item when it is pasted. The new item will have the same show-if conditions as the original.

Adding Show-if Conditions to Responses

It is possible to assign show-if conditions to individual responses, or multiple responses, in Select One and Check All type questions.

To set show-if conditions on responses:

1. Open the question with the responses to set show-if conditions on by double clicking on the question in the right pane of the Survey Editor.

2. Select the Response Options tab.

3. Click on the response to assign the Show-if conditions. To Assign the same logic to multiple responses at the same time, hold the Control Key and select all of the Responses to set.

4. Click the Show If Button.

5. Select the radio button for Only Show-if.

6. Set the Show-If conditions with the same steps as setting them for a Survey Item. See above ‘Adding Show-if Conditions to Items’.

7. The responses will show the Show-If Icon in the list.

8. When the question is saved the question type icon will appear yellow showing conditions set to responses and not the question itself.

Custom Grouping of Show-if Conditions

Custom grouping enables the mixing of AND and OR in show-if conditions.

To use custom grouping:

1. Define all of the conditions that will be tested, as described above.

2. Choose the Custom group expression option under Expression Grouping.

3. Use labels, parentheses and the words “and” and “or” to group expressions, as described below.

When the conditions to test are defined, the Question Editor will assign a label to each condition. In the image below, “GENDER = [Male]” is labeled as A. “AGE_RANGE = [36-45]” is labeled as B and “MARITAL = [Single]” is labeled as C.

If the question should appear to all participants who are Male, or 36-45 and Single, type the following under Custom group expression: A or (B and C). This means, display the question if condition A is true (participant is male) or if both B and C are true (36-45 and Single).

In this example, Illume Next will first check to see if both conditions B and C are true. If both are true, Illume Next will go on to see if condition A is also true. If either one of B or C is false, and A is true, Illume Next will display the question.

The following grouping would give a completely different result: (A and B) or C. In this grouping, Illume Next will display the question if both A and B are true (participant is male and 36-45) OR if C is true (participant is single).

Further Notes About Custom Grouping

If an expression uses nested parentheses, the more deeply nested parentheses are evaluated first. For example, in the following expression: A and (B or (C and D)), Illume Next first checks to see if conditions C and D are both true. Illume Next then checks to see if B is true (if necessary– this expression requires only that one item inside the blue parentheses be true). Finally, Illume Next checks to see if A is true.

Each parenthesized expression is always reduced to a single true or false value. In the following example, let’s assume that underlined conditions are false and non-underlined conditions are true. (A and (B and (C or D or (E and F)))) Here is how Illume Next interprets the expression: Starting within the deepest parentheses, Illume Next  sees that condition F is false. Because E and F are not BOTH true, the entire expression within the deepest parentheses is then false. So now we have this: (A and (B and (C or D or false))).

Illume Next then looks at the items in the set of parentheses. Because these are grouped with OR, if any one of the conditions is true, the whole parenthesized expression is true. Illume sees that false is not true. It sees that condition D is not true. It sees that condition C is true. Now the entire group within the red parentheses is true. (A and (B and (true))) Illume Next then sees that both B and the condition that follows B are true, so the entire expression in the highest parentheses becomes true. (A and (true)) Now Illume Next sees that both A and the condition that follows A are true, so the entire expression is true. Illume Next has reached the outermost condition, and it is true, so Illume Next will display this item.

 

A question table is a group of questions that shares a common set of response options. Generally, a question table will have three components: instructions, prompts, and a set of response options.

Instructions tell the participant what type of response is expected. For example, “Please indicate the extent to which you agree or disagree with the following statements.”

Prompts are the individual items to which participants respond. A question block that uses the instructions above may include prompts such as:

 

The final component in a question table is a set of response options shared by all of the prompts. In the example above, each of the prompts might include the following options:

Choosing a Display Type

The general tab of the Question Table Editor provides a list of display types. When you choose a type from the list, you’ll notice that a sample appears to the right of the list showing what the selected display type looks like.

The Select One display type actually shows two samples: one with radio buttons and one with poplists. When you choose the Select One display type, you must use the ‘Select-one style’ list in the Display Properties tab to indicate whether the collection should use radio buttons or poplists.

Creating Instructions

Type the instructions for your question table into the Instructions entry under the General tab. These instructions will appear above the table.

Creating Prompt Headers

The prompt header appears above the table’s set of prompts.  For example, the Instructions of a table might be “Rate the following aspects of your hotel stay”, whereas the prompt header might be “Aspects”, under which the hotel stay aspects are listed as the prompts.

Creating and Editing Prompts

To add prompts to the collection, click the Prompts tab. For each prompt you want to add, type the prompt into the Prompts box and press Enter (or click the Add button). You’ll see that each new prompt appears in the list of prompts at the bottom of the Question Table Editor.

To edit an existing prompt, click on the prompt in the list, make your changes to the prompt’s text in the Prompts box, and click Replace . (Note that if you press the Enter key instead of clicking Replace, you will create a new prompt.)

Deleting Prompts

To delete a prompt, click on the prompt you want to delete (it should be highlighted against a blue background once you click on it) and then click the Remove button.

Importing Prompts from the Clipboard

It is possible to copy a group of prompts from another document and then using the “Import From Clipboard” button paste them into the Prompts area. Because it is coming directly from another document it may require some formatting.

Setting Show-if on Prompts

You can set show-if conditions on the individual prompts within a question table, so that the rows conditionally show based on prior responses or pre-known participant information.  To set show-if conditions on a prompt:

1. Create the question table by entering the Instructions, Response Options and Prompts.

2. Once the table has been created, click on the table on the left pane, so that the prompts populate the right pane.

3. Double click on a prompt, and go to the show-if tab for the prompt.

Display Properties: Setting Columns of Equal Width

It is important to ensure that the columns of a table are of equal width.  By default, columns will size to the widest column header.  To prevent this, make sure to enter something in the “Column Width” field on the Display Properties tab.  You will need to enter a value in pixels, such as 80px, 90px, etc.  You may have to try a number of pixels and then preview the table to see whether that number is just wide enough to keep columns equal, but not so wide that it uses up screen real estate unecessarily.

Display Properties: Repeat Column Headings

If a table has many rows, the respondent may be forced to vertically scroll to see all of the rows, and in doing so may lose sight of the column headers – this can lead to error.  To mitigate that error, repeat the column headings every 5 or so rows so that respondents can always see the column header

Display Properties: Randomize Prompts

There may be some cases where it is beneficial to randomize the order in which the prompts are displayed in the table.  To do so check the ‘Use custom display order for prompts in this table’.

Sub-Grouping and Response/Prompt Headings in Question Tables

Questions Tables may have both Response Headers as well as Prompt Headers.  Response Headers are labels that apply to multiple column headers, e.g. ‘Gender’ might be a response header for the column headers ‘Male’ and ‘Female’.  Prompt headers serve to group the prompts into categories.  For example, a table may ask respondents to rate how much they like various foods.  Those foods might be grouped into Fruits, Vegetables, Meats, etc.

Adding Response Headers to a Question Table

Response Headers are added to Question Tables in the same way as  standard response options.  They are only available for Select One and Check All That Apply display types.

To add a response header:

1. On the Response Options tab type appropriate text.

2. Check ‘Group header’ box.

3. Click Add.

4. Drag where appropriate among the list of response options

Adding Prompt Headers to a Question Table

Prompt Headers can be used with all of the Display Types in a Question Table. Prompt Headers are created by selecting the Prompts tab in the Question Table Editor and checking the “Group header” box. Prompts can me moved up and down in the list by clicking and dragging.

Example Question Table with Response and Prompt Headers

 

Every item in an Illume Next survey must have a unique name. Items include questions, collections, Text/HTML objects and survey resources. Illume Next  automatically assigns a unique name to each object when it is created, but it may be desirable to assign a more meaningful name.

A unique name must start with a letter, and can contain any combination of letters, numbers, underscores (_), or hyphens (-). Unique names must be between 2 and 30 characters in length.

To edit an existing question:

1. In the left pane of the Survey Designer, navigate to the question to edit.
2. In the right pane of the Survey Designer, double click on the question to edit.

 

Why Can’t I Edit a Question?

Some questions in the right pane of the Survey Designer may appear to be grayed out. This means that the question is only partially editable. There are two reasons for this:

Editing Questions on a Published Survey

Certain parts of questions belonging to published questions cannot be edited without potentially corrupting the survey data. Within a published survey you cannot:

If you must make these types of edits, you must either clone the survey and make your edits in the clone, or disable (i.e. set to “never shown”) the problematic items and create new items.

Editing a Repository Item

Repository items have the same editing restrictions as published survey items. Repository items are intended to be the same across all of the surveys in which they appear. This allows data analysts to query a consistent set of data across multiple surveys. Changing the prompt or scale values of a repository item would violate this guarantee, introducing inconsistencies to the data. If you must edit the question’s prompt or scale values, you can:

Both of these options have consequences. Breaking the question’s link to the repository makes the question unavailable for cross-survey queries. This affects only the survey you are working on. Editing the question in the repository changes how the question will appear in all future surveys that use it. Follow the links to Repository Overview, Editing Repository Items, and Breaking a Link to the Repository below.

To quickly find a survey item by name, use the ‘Go to item list’ at the bottom of the survey designer. Start typing the name of the item you want to find, or simply click the arrow to browse the list. The survey designer will find and highlight the item selected in the list.

An Illume Next survey can store up to 12,000 variables. The survey can include additional variables explicitly marked as runtime only.  Variables are typically marked as runtime only when they are used only  in calculations and show-if conditions, but not saved when a participant submits a survey. When determining the number of variables in the survey, keep in mind the following rules:

Data Manager Variable Limit

There is a restriction as to the number of variables that can be used in a query or downloaded within the Data Manager.  This number is 4000 and is based on a SQL Server restriction (number of columns in a SELECT statement).  Users will see an error if this occurs.  In this case the user must query and download subsets of variables as to not exceed the limit.

 

Piping usually refers to the practice of inserting information from one place into another place.   For example, if a participant indicates in question #3 that he drives a Toyota, that information can be piped into the prompt for question #10, which may ask “How satisfied are you with your Toyota?”

Illume Next enables the piping of several types of data into a variety of locations.

How to Pipe Data

A User can pipe data by including a variable name enclosed in curly brackets in the text where they want the data to appear. Illume Next will replace the variable with its value while the survey is running. See the specific descriptions and examples below for more information.

Where Can Data Be Piped?

Illume Next can pipe data into question prompts, scale values, Text/HTML objects, error messages, question default values, and the upper and lower bounds of a question’s response requirements.

What Data Can Be Piped

Illume Next supports the piping of:

Each type of piping is described in more detail below.

Participant Responses

To pipe a participant response into a question prompt, or into a Text/HTML object, use the tag {Response:QuestionId}, where QuestionId is the unique name of the question whose response is to be piped in.

For example, there is a question with the unique name “AUTOMOBILE” that asks what type of car a participant drives. The list of responses includes Ford, Chevy, Toyota, etc.  It is desired to pipe this question’s response into a later question that asks how satisfied a participant is with his or her automobile.  The prompt for the satisfaction question would be written like this:

How satisfied are you with your {Response:AUTOMOBILE}?

Participants who indicated that they own a Ford will see “How satisfied are you with your Ford?” Those who said they own a Chevy will see “How satisfied are you with your Chevy?”

Piping tags are not case sensitive. That means {RESPONSE:QUESTIONID} and {response:questionid} will yield the same result.  The entire RESPONSE tag can be shortened to the letter R, e.g. {R:AUTOMOBILE}.

Special Behavior for Check All That Apply Questions

Because Check All That Apply questions permit a participant to potentially select multiple responses, the Response tag produces a comma-separated list of responses.

For example, a checkbox question FOODS asks a participant to check each of the foods he or she has eaten in the past week (from a list including Peas, Carrots, Potatoes, Apples, Chocolates, and several other foods).

If the participant checks 3 items, then {Response:FOODS} or {R:FOODS} will produce a comma-separated list of those 3 items.  The list includes the labels that the participants saw, not the numeric codes that are stored in the database. Therefore {Response:FOODS} would produce a piece of text like Peas, Carrots, Potatoes.

The {Value} tag also behaves differently when applied to checkboxes, returning the number of items checked. Continuing the example above, the tag {Value:FOODS} would return the number 3 because the participant checked 3 items in the list.  The tag Value can be replaced with the letter V, as in {V:Foods}

User Data

Illume Next allows for the creation and upload of participant lists, which information about participants who will be permitted to take your survey.  These participant lists may contain information such as first and last names, email addresses, or any other data that may be available.

Users may want to pipe user data into a sruvey.  For example, users may want to welcome participants by name, or to display their respondents’ email addresses for verification.

Let’s assume the participant list includes a piece of user data called DATSTAT_FIRSTNAME that contains a participant’s first name. To greet participants after they log in, a Text/HTML object would be included with the following text:

Greetings {UserData:DATSTAT_FIRSTNAME}! Thank you for taking the time to visit our survey!

NOTE: As with the Response and Value tags, the UserData tag can be replaced with the letter U, as in {U:DATSTAT_FIRSTNAME}.

Preload/Hidden Data

Preloaded and hidden data can have several purposes. For example:

1. Illume Next can preload data from the participant list into the participant’s survey.  As opposed to simply piping from the participant list, which makes the participant information appear but doesn’t store it, Preloading data stores the participant information into the survey data set.

2. Illume Next can read data appended to the survey URL and store it in a hidden variable.

3.  Custom software developed with the Illume Next SDK (software development kit) can read and set values stored in hidden variables.

The article on Hidden Variables and Preloaded Participant Data provides information on how to create these variables.

Parameter Values

Parameter values are described in detail in the section Working with Survey Parameters. To pipe parameter values into the text, use the tag {ParamValue:PARAMNAME}, where PARAMNAME is the name of the parameter whose value is to be piped in.  The tag can be shortened to “P”, as in {P:PARAMNAME}.

Attributes of the Current Question

The following information about a question can be piped into the question’s custom error message:

 

For example, if the question requires a numeric answer between 1 and 100, a custom error message could be written like this:

The value “{Value}” that you entered for question #{QNum} is not valid. Please enter a value between {MinValue} and {MaxValue}.

Participants will see an error message like this:

The value “I don’t know” that you entered for question #12 is not valid. Please enter a number between 1 and 100.

This type of custom error message is helpful to both participants and survey designers. The message is specific enough to inform the participant of exactly what is wrong, and where.

The use of parameters ensures that the designer will not have to rewrite the error message if the question’s minimum and maximum values change, or if the question is assigned a new question number.

Piping Responses into Other Questions

As noted under Participant Responses above, responses can be piped from one question into the prompt for another question. Values can be piped into the default value of a question. For details, see Setting a Question’s Response Options. In addition, values can be piped into the upper and lower bound fields of a question’s response requirements. This enables the survey designer to say that the answer to question C must be a value greater than the answer to question A and less than the answer to question B. For details, see Setting a Question’s Response Guides.

Piping Data from Built-in Objects

Illume Next surveys includes built-in objects that can be piped into question prompts, responses, error messages, and/or Text/HTML objects:

Special Built-ins for Email Jobs

See Composing an Email Message for details about the context in which these tags may appear.

Special Built-ins for the Save Page and Save Email

See Setting up Save and Restore for information about the context in which these tags may appear.

The Save Email that Illume Next sends to the participant is an HTML formatted email. Illume Next does not send a plain text version.

Piping Data from Attached Text Fields

Data can be piped from a text box that is attached to a checkbox or radio button. For example, the following question whose name is ASSOCIATION:

Which associations do you belong to?

NBA

CBA

USBA

Other Professional Association

Other Amateur Association

Other Misc. Association

It is possible to pipe the text a participant entered into the text fields attached to each of the “Other” options by referring to one of the following variables: {Response:Association.Text}Retrieves the response from the text box next to Other Professional Association. {Response:Association.Text2} Retrieves the response from the text box next to Other Amateur Association.  {Response:Association.Text3} Retrieves the response from the text box next to Other Misc. Association.

If the radio button or checkbox question has only one attached text field, the tag to retrieve the text from that field will always be {Response:QuestionID.Text}, where QuestionID is the unique name of your radio button or checkbox question. You can get the text from any subsequent attached text fields by using {Response:QuestionID.Text2},{Response:QuestionID.Text3}, etc.

The number of the text field (Text2, Text3, etc.) refers to the order in which the field was created, not the order in which the field appears. This allows reordering of the responses in the checkbox/radio button question without having to modify any of the piping tags that exist elsewhere in the survey.

Abbreviated Piping Tags

The survey designer recognizes abbreviated tags for some of the most common ‘replacement’ functionalities:

 

Survey designers can set a question’s default response, upper bound, or lower bound:

1. A default response is an already-selected or entered response to a question.
2. An upper bound is the highest allowed value to be entered into a text display type question
3. A lower bound is the lowest allowed value to be entered into a text display type question

The default or bound value may come from one of the following sources:

• Participant Response Data – Data the participant has entered in response to a prior question. This includes calculated variables, as long as Illume Next has enough data to calculate the variable before piping it in.  For example, a participant may say she drinks 5 alcoholic drinks per day.  This response may become an upper bound to a subsequent question asking how many of those drinks were wine.
• User Data – Data associated with this participant in a User’s participant list.  For example, participant’s known years of education may be piped into a question as the default value, allowing the respondent to verify this known value or change it.
• Survey Parameters – Data from survey-wide variables that the User assigns in Survey Preferences.

Use the following tags to pipe values into defaults and bounds:

• {Value:QuestionId} – This will pipe in the value of any question the participant has answered. Change QuestionId to the name of the question whose answer is to be piped in. E.g.{Value:HEIGHT} will pipe in the answer to the question named HEIGHT.
• {UserData:FieldName} – This will pipe in data from the User’s participant list. Change FieldName to the name of the field to be piped in. For example, if a User’s participant list includes a field called LASTNAME for each participant, they can pipe the current participant’s last name by typing {UserData:LASTNAME}.
• {ParamValue:ParameterName} – This will pipe the value of a survey parameter. Survey parameters are survey-wide variables. Each has a name and single value that will be the same for all participants. To pipe the value of a survey parameter called PRODUCT, use the tag {ParamValue:PRODUCT}.

Case does not matter for these tags: {Value:HEIGHT} and {value:height} produce the same result. The curly braces do matter! Piping tags must be enclosed in curly braces {}!

Dynamic Bounds

Questions that use a numeric data type allow survey designers to define the upper and lower bounds of a valid response. Designers set the bounds in the Response Guides tab of the Question Editor, or in the Response Guides tab of the Attached Text Field editor (if working with a text field that is attached to a select-one or check all question).

For example, a question called CURRENTWEIGHT that asks a participant’s current weight. Earlier questions asked for the participant’s minimum weight (MINWEIGHT) and maximum weight (MAXWEIGHT) over the past 12 months. To ensure that the participant enters a current weight that is between his minimum weight and maximum weight, set the Lower Bound of CURRENTWEIGHT to {Value:MINWEIGHT} and the Upper Bound to {Value:MAXWEIGHT}.

When the participant is taking the survey, Illume Next substitutes the participant’s answers to the MINWEIGHT and MAXWEIGHT questions for the {Value:MINWEIGHT} and {Value:MAXWEIGHT}tags. There is some risk in doing this: if the participant did not answer MINWEIGHT or MAXWEIGHT, or if the answers to those questions were not numeric, Illume Next will not try to validate the answer.

To take advantage of dynamic bounds, adhere to the following practices:

1. The question with the set bounds must have a numeric data type. Any numeric type will work. E.g., an appropriate data type for CURRENTWEIGHT would be “Whole numbers 0.”
2. The question whose is piped into the bounds should have the same data type as the question itself. E.g., when setting the bounds for CURRENTWEIGHT, whose type is “Whole numbers 0,” be sure that MINWEIGHT and MAXWEIGHT also use data type “Whole numbers 0.” The validation may work if the data types do not match, but the chances are significantly better if the data types do match.
3. The piped questions (MINWEIGHT and MAXWEIGHT) should require a response. If a participant doesn’t answer these questions, Illume Next has no data to pipe into the bounds and cannot perform the validation. In fact, Illume Next will not even try to perform the validation if it does not have all of the data it needs.
4. When setting defaults and bounds, try to avoid piping from checkbox questions. When applied to checkbox questions, the {Value} tag actually returns the number of items checked. The{Response} tag returns a comma-delimited list of the labels associated with each checked item in a checkbox question. Generally, this is not what is desired for defaults, and will certainly not work with bounds.

Dynamic Default Values

Dynamic default values work just like dynamic bounds: it is possible to pipe a participant response using the {Value:QuestionId} tag, data from the participant list using the{UserData:FieldName} tag, or a survey parameter using the {ParamValue:FieldName} tag.

 

As with dynamic bounds, there are a few things to keep in mind when piping one question’s response into the default value of another question:

1. The question whose answer is used to pipe into the default value has the same data type as the question itself. E.g., if the current question uses the whole number data type, the value piped into the default should be a whole number.
2. Use the {Value:QuestionId} tag to get the numeric value associated with the item a participant selected in a select-one question. This is usually what is desired when setting the default of a question whose data type is numeric.
3. Use the {Response:QuestionId} tag to get the text that appeared next to the option the participant chose. This is usually what is desired when setting the default of a question whose data type is text.
4. The question used for piping should require a response. If Illume Next has no data to pipe into the default, then it will leave the default value empty.
5. When setting defaults and bounds, avoid using the {Value} tag to get the value of a checkbox question. When applied to checkbox questions, the {Value} tag actually returns the number of items checked. The {Response} tag returns a comma-delimited list of the labels associated with each checked item in a checkbox question. Generally, neither of these values are useful in setting defaults.

Other Notes About Default Values

If a question uses response options and no default option is set, the option that will be selected when a participant first sees the question is the “unanswered” option. You can set the text of the “unanswered” option on the Data tab of the Survey Preferences editor. See “Customizing Labels for Unanswered Items”. The “unanswered” option exists only when the text for the unanswered option is not empty. To remove the default value, simply delete whatever is typed into the default field.

 

 

Inserting Special Characters

If a survey requires special symbols, accented letters, or characters that do not belong to the Latin alphabet, use Microsoft’s built-in character map to add the characters to the survey.

1. From the Windows toolbar, choose Start / Programs / Accessories / System Tools / Character Map
2. For each character to add, click on the character and click Select to copy it into the Characters to copy field.
3. After selecting all of the characters to copy, click the Copy button.
4. Click once in the Question Designer, or HTML editor and move the cursor to the point to insert the special characters.
5. Hold down the control key and press the letter v (Ctrl-V) to paste the special characters into the text.

 

NOTE: It is possible to paste special characters into almost any Windows application using this method.

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

Overview

A jump causes a participant to jump from one part of a survey to another, skipping everything in between. Jumps can be conditional, occurring only when a participant meets certain criteria, or unconditional, in which case they always happen for all participants. A jump can move a participant forward or backward through a survey. Each survey can contain multiple jumps.

Warnings

While jumps are convenient, they can make a survey excessively complex, difficult to test, and difficult to maintain. In general, it is advised to use show-if conditions rather than jumps, for these reasons:

• Show-if conditions appear as yellow circles next to survey objects in the survey designer. They are easily recognized, and it is easy to see the conditions attached to them. This makes them easier to maintain and edit.  In other words, you can mouse over the object and immediately know the conditions under which it will be shown.
• Unlike show-if conditions, jumps are not attached to any particular object. While a show-if condition can suppress only the object to which it is attached, a jump can suppress all objects between its point of origin and it’s destination. If a certain question is not appearing in the survey, it’s easy to look at the question to see if a show-if condition is attached. It’s much more difficult to hunt through the entire survey looking for a particular jump that contains a condition that might cause the question not to display.
• Poorly implemented jumps can leave participants in an infinite loop. For example, if a jump sends certain participants back to question #2 after they answer question #10, some participants may never be able to get past question #10 of the survey.
• Having numerous jumps used for navigational purposes within your survey will get you in trouble upon submission of the survey. Data cleaning runs through the survey straight through upon submission. Any questions that are jumped over are not going to be included in your data set.

When to Use Jumps

There are two particular cases in which jumps are preferable to show-if conditions:

1. When a participant should be moved directly to the end of a survey.
2. When a single jump will prevent having to create many identical show-if conditions.

How to Use Jumps

To add a jump to a survey, follow these steps:

1. In the Illume Survey Designer, choose Jump from the Add menu

2. Give the jump a unique name. A descriptive name will help to remember the purpose of this jump.
3. (Optional) Type in a description. This can help users understand the reason for the jump.

4. Choose the jump’s destination.

• Jump to the end of the survey -Jumps to the very last page of the survey, the page that contains the Submit button.  Participants can still navigate back in the survey from this page.
• Jump to the end of the survey and automatically submit – Submits the participant’s survey and displays the end page content (the page participants see after submitting a survey). Participants cannot go back from the end page.  The submit status of the survey will be “Completed”, unless the Terminate Survey Session box is checked on the Options tab of the jump editor (see below)
• Jump to the selected survey item – Jumps to the survey item selected in the Select Survey Item list.
  • If Jump to the selected survey item is selected, select the item to which the participant should jump. This can be any type of item: a question, a collection, or a text/HTML item. It is possible to jump to another jump.

5. Set the Jump-if conditions. Participants will jump only if the conditions specified are met. Set Jump-if conditions in the same manner as setting show-if conditions.
6. Click OK to close the Jump Editor and save the changes.
7. Move the jump to the point in the survey where the jump should occur.  For example, if a jump should occur after a participant answers a question asking if they smoke, then drag the jump in the Illume Survey Designer so that it appears immediately beneath the SMOKE question, as in the image below.

 

Notice that in the Illume Survey Designer, the Jump appears with its name: JMP1, its destination: Jump-to: DEMOGRAPHICS and its description: Participants who do not smoke Jump directly to Demographics. The yellow circle to the left indicates that this jump is conditional. Hold the mouse pointer over the yellow circle to see the jump-if condition.

Using a Jump to Mark a Participant as Terminated

There are times when a submitted survey session is not considered a completed survey because the Participant did not meet specific screening or other defined criteria and was therefore jumped out of the survey. This can be marked as a Terminated session.  The value of marking the session as Terminated is two fold:

1. Terminated sessions do not count towards the Transaction count in your Illume license

2. Marking the session as terminated allows you to filter and query on the variable DATSTAT.SUBMISSIONSTATUS to identify survey sessions that are Complete vs. Terminated.

To Mark and Jumped Survey As Terminated:

NOTE: This option will only be available for the Jump Type of “Jump to the end of the survey and automatically submit.”

1. Create a Jump by following the steps above
2. While in the Jump Editor click on the Options Tab
3. Check Terminate survey session

4. Click OK to save

Using the Terminate check will set the DATSTAT.SUBMISSIONSTATUS variable to ‘Terminated’.

Setting a Preload/Hidden variable to a value for a Jump

This allows users to use a preload/hidden variable for purposes of storing the reason for termination, screen out or any other type of Jump.  Thus although the DATSTAT.SUBMISSIONSTATUS variable will tell you whether the participant terminated, the Preload/Hidden variable will tell you why the participant terminated.

To Set a Preload/Hidden Variable:

1. Follow the steps in creating a Preload/Hidden variable.  In the example below, the name of the Preload/Variable is TERMINATE_REASON_CODE.  It has 3 scale values: Smokes, Pregnant, Opt Out.

NOTE: This option requires a preload/hidden variable of type “select-one”, with a scale defined on the scale tab. 

2. While in the Jump Editor click on the Options Tab
3. Select Set preload/hidden variable to a value specified below
4. Select the Variable Name of the variable just created above
5. Select the appropriate Value of the selected Variable
6. Click OK to save

Viewing the Data Dictionary

To see a survey’s Data Dictionary, choose Review Data Dictionary from the Tools menu. This displays the same data dictionary that appears in the Data Manager.

 

The Data Dictionary is organized by Collection.  It can be printed via the Print button.  There is no save button, however you may print to PDF (if you have a PDF-maker on your device) and save that PDF.

DatStat Auto-Generated Internal Variables

These variables are created automatically with every survey and are found in the Data Dictionary.  They can be queried and downloaded as any other variable.

DATSTAT.SUBMISSIONID – The unique id of this data submission. No other submission on this or any other survey shares this submission id.

DATSTAT.SESSIONID – The session id a unique alpha numeric string assigned by the web server to a participant’s session.  Every survey session has a single unique session ID.  This value is important within the Data Import feature in the Data Manager, as it can be used to update an existing survey submission.

DATSTAT.VERSION – The version of the survey that the participant submitted. A survey gets a new version number each time it is published. This number may be important in some cases. For example, if a participant submitted version 2 of a survey, you know that the participant did not see any of the edits or new questions that appeared on version 3 of the survey.

DATSTAT.LOCALE – This is the locale setting on the participant’s computer. This may not always be available. The locale setting determines, among other things, what language the computer uses, and how it formats dates and times. Microsoft provides more information about locales in its Locales & Languages page (http://www.microsoft.com/globaldev/DrIntl/faqs/Locales.mspx).

DATSTAT.LANGUAGE – This variable indicates the four digit LCID for the participant, which is the Locale ID – it represents the language in which the survey was taken.  By default this is English.

DATSTAT.BROWSER – This is the browser the participant used to enter data. This is actually the text of the browser’s “user agent” string.

DATSTAT.STARTDATETIME – This variable indicates the date and time the survey the participant first logged on to begin the survey – when the Login button was clicked either by the participant, or by way of clicking a unique link delivered in an Illume email.  The date and time the participant began entering data.

DATSTAT.ENDTIME – This indicates the date and time the survey was submitted (clicked the Submit button)

DATSTAT.ELAPSEDTIME – This indicates the time (in minutes) the participant took taking the survey.  The total number of minutes it took the participant to finish entering data. Note that this cannot always be a reliable figure. If a participant spends 10 minutes answering questions, then takes an hour break for lunch, then spends another 10 minutes completing the survey, this field will show 80 minutes, even though only 20 minutes of that time was spend answering questions.

DATSTAT.SUBMISSIONSTATUS – This indicates the submission status of the participant’s survey (1 = completed; 2 = partially completed; 4 = not started; 5=terminated

This field contains one of three values:

• 1 indicates the participant completed the survey
• 2 indicates the participant started the survey but did not submit a complete survey.
• 4 indicates that the participant did not start the survey
• 5 indicates that the participant was terminated and did not complete

DATSTAT.LOGINCOUNT – This shows the number of times the participant logged in to this particular survey.

DATSTAT.JAVASCRIPT – A value of 1 indicates that the participant’s browser had JavaScript enabled. A value of 0 indicates that JavaScript was disabled or not supported in the participant’s browser.

DATSTAT.TIMEPERIOD – This shows the time period during which the survey was submitted. Time periods apply primarily to longitudinal surveys (those where a single participant submits the survey more than once over time). Time period names are arbitrary (e.g. “P1” or “Spring 2008”) and are set at the time of publication by the user who publishes the survey. If you publish your survey under multiple time periods, you can filter your survey results by time period when querying the data.

DATSTAT.PCTCOMPLETE – The percentage of questions that the participant completed. If the survey includes a progress bar, this is the figure that drives the progress bar. For incomplete (a.k.a. “partial”) submissions, this shows how far the participant progressed.

DATSTAT.LOGINDATETIME – This shows date and time when this participant last logged in.

DATSTAT.UPLOADDATETIME – The date and time if and when this submission was uploaded either via Remote Data Collection or imported with Data Import.

DATASTAT.UPLOADUSER – The name of the user that uploaded this submission.

DATSTAT.UPLOADTYPE – The type of upload 1 = Remote Data Collection; 2 – Imported with Data Import.

DATSTAT.IMPORTDATETIME – The date and time this submission was imported. This applies only to surveys that were imported into Illume from another application or data source. This value will be empty if the participant submitted his or her survey directly via a web browser.

DATSTAT.NUMPRESENTED – This indicates the number of items the participant was presented while logged into the survey. Show-if conditions and conditional jumps can cause this number to be lower than the total number of questions in the survey for a specific participant.

DATSTAT.NUMANSWERED – This indicates the number of items answered by the participant, including the “I choose not to answer” option.

DATSTAT.NUMUNANSWERED – Number of questions unanswered by this participant.

DATSTAT.PCTUNANSWERED – The percentage of questions left unanswered by this participant. This number does not include items that were never presented to the specific participant because of show-if conditions or jumps.

DATSTAT.SITE – Participant site at the time when this survey was started.

DATSTAT.INTERVIEWER – User that interviewed the participant.

DATSTAT.RMSSURVEY – Only relevant for Discovery product users.  Identifies the Illume survey utilized in the Survey Study task

DATSTAT.RMSMILESTONE – Only relevant for Discovery product users.Identifies the milestone in which the Survey Study task resides.

DATSTAT.RMSSTUDYARM – Only relevant for Discovery product users. Identifies the study arm in which the Survey Study task resides.

DATSTAT.RMSINSTANCE – Only relevant for Discovery product users. Identifies the instance of the survey study task within the study milestone.

DATSTAT.RMSSTUDY – Only relevant for Discovery product users. Identifies the Discovery study in which the Survey Study task resides.

 

How Illume Constructs the Data Dictionary

Every Illume survey includes a collection called Root, which contains all of a survey’s items.

Each of the collections within the Root collection can become a Section in the Data Dictionary.  When defining a collection, users have the option to check a box to make the collection a section in the data dictionary (see below).  By default, collections are not sections in the data dictionary.

If your survey contains collections C1, and C2 under the Root collection, the Data Dictionary will display sections C1 and C2. If C1 contains another collection called C1_Subsection, that sub-collection will not appear in the Data Dictionary.  Rather, all of the questions in C1_Subsection will be listed with the items in C1.

This may not always produce the best results. In some cases, a single section of the data dictionary may wind up with hundreds of questions, making it difficult for data analysts to find specific items. Customizing the sections of the Data Dictionary solves this problem.

 

Customizing the Data Dictionary

Any collection in a survey can appear as a section in the Data Dictionary with a unique name assigned by the designer.

1. Double click a collection in the right pane of the Survey Designer to bring up the Collection Editor.
2. Check “Make this collection a section in the data dictionary”.
3. Type a name in the Section title field.
4. Click OK.

To see how this appears in the Data Dictionary, choose Tools / Review Data Dictionary from the Survey Designer menu.

Adding Comments to a Question or Item

The comments feature allows Illume users to communicate with each other regarding the items contained within a survey.    It is possible to add comments to any question or Text/HTML item in a survey. Comments are available only to those editing the survey; participants cannot see them.

Once a survey is checked into the database, any comments added in the most recent round of editing become read-only. Others may contribute additional comments, but comments cannot be altered once checked in.

Adding Comments from within Survey Designer

To add comments from within the Survey Designer:

1. In the right pane of the Survey Designer, click on the item to which to attach a comment. (If the item is not currently showing in the right pane, click on the collection that contains the item in the left pane of the Survey Editor.)

2. Click the Add/Edit Comments icon  in the toolbar.

3. Type comments in the Add Comments area at the bottom of the Comment Editor.

4. Click OK .

Adding Comments from the Survey Previewer

In the Previewer, Comments can be added only to questions.

To add comments from the Survey Previewer

1. Go to the Preview menu and select Preview Survey

2. Click the Comments icon  next to the question prompt.

3. Type your comments in the Add Comments area at the bottom of the Comment Editor.

4. Click OK .

 

Reviewing and Editing Comments

You can review and edit comments to any question, Text/HTML item, or page break in a survey. Comments are available only to those editing the survey; participants cannot see them.

To review all survey comments at once, select Tools – Review All Comments from the Survey Designer menu.

Adding Comments from within Survey Designer

To edit or review comments from within the Survey Designer:

1. In the right pane of the Survey Editor, click on the item to which you want to attach a comment. (If the item is not currently showing in the right pane, click on the collection that contains the item in the left pane of the Survey Editor.)

2. Click Comments to the left of the item.

3. (Optional) You can add your own comments by typing them into the Add Comments area at the bottom of the Comment Editor.

4. Click OK to close the Comment Editor.

Adding Comments from the Survey Previewer

In the Previewer, you can add comments only to questions. To review or edit comments from the Survey Previewer, simply click the Comments icon next to the question prompt.

 

Using the Spell Checker

Checking the Text Which is Currently being Edited

The spell checker checks spelling while typing in any of Illume’s HTML editors, underlining misspelled words with a wavy red line. The spell checker checks spelling while typing question prompts, response options, and Text/HTML items.

To correct the spelling of any misspelled word, right-click on the word, and choose one of the suggested spellings from the list.

If the correct spelling is not in the list, click within the HTML editor to make the context menu disappear, then manually correct the spelling.

If the spelling of the word is correct, but the spell checker identifies it as incorrect, the context menu provides two options:

• Ignore all will ignore all further instances of the word in the current document. (Unless you are checking the entire survey at once, the current document includes the text in the current HTML editor.)
• Add to Dictionary will add the word to your dictionary of known words. Microsoft Word and other Office applications share this system-wide dictionary, so any words you add from Illume will be added to your Word/Office dictionary as well.

Spell Check Options

When Include item descriptions is checked, Illume will find and replace text within the data dictionary descriptions of questions and question tables. This is the text that appears on the Description tab of the question editor and in the description field of each item in the data dictionary.

Checking an Entire Survey At Once

Illume can spell check an entire survey at once, including:

• All question prompts
• All response options
• Text/HTML items
• Header and footer text
• End page content
• The survey launch page
• The resume/restore page
• The “survey suspended” page

To spell check an entire survey at once click Tools / Spell Check… Illume will read through the survey, stopping at each potential misspelling. Illume loads the text containing the misspelling into the HTML editor, with the misspelled words underlined in red. Right-click on any misspelled word to view the list of suggested spellings.

The survey-wide spell checker includes a Revert to Saved button that will undo any changes made by the spell checker in the text currently displayed.

After correcting a word in the survey-wide spell checker, click Next Error to resume spell checking.

Checking Selected Items

You can limit the spell check operation to a single item or to a group of items by selecting the item(s) in the survey designer before choosing Spell Check… from the Tools menu.

To choose a single item for spell checking, simply click on the name of the item in the Survey Designer. To choose multiple items, hold the Control key and click each item individually. Holding the Shift key while you click selects every item between the item you are clicking on and the last selected item.

When working within a group of selected items, checking Include items within selected collections will extend the find and replace operation into each of the collections that you have selected.

Known Issues with Spell Checking

Because Illume uses Microsoft Word’s spell checker, you must have Microsoft Word 2000 or later installed in order to use spell check.

When the spell checker replaces an individually formatted word (for example, an italicized, bolded or underlined word), Illume may not preserve the formatting when it replaces the word.

Multilingual Surveys

The spell checker will work for each language in a multilingual survey, provided:

• Microsoft Word 2000 or later is installed on the computer.
• Microsoft Word dictionary is installed for the language being checked.

Find and Replace

The Survey Designer’s Find and Replace feature can find and replace text in any of the following items:

• Question prompts
• Response options
• Text/HTML items
• Data dictionary descriptions
• Variable references

By default, Find and Replace operates on the entire survey. Find and replace can be limited to a single item or to a group of items by selecting the item(s) in the survey designer before choosing Find and Replace… from the Edit menu.

To choose a single item for find and replace, simply click on the name of the item in the Survey Designer. To choose multiple items, hold the Control key and click each item individually. Holding the Shift key while you click selects every item between the item you are clicking on and the last selected item.

Using Find and Replace

To find and/or replace all instances of a word throughout a survey, follow these steps:

1. Choose Edit / Find and Replace…
   

2. Type the word to find into the Find field.

3. To replace the word, type the replacement word into the Replace with field.

4. Click Find Next to find the next occurrence of the word. Click Replace to replace the next occurrence of the word. Click Replace All to replace all occurrences of the word throughout the survey.
   

Find Next and Replace display the next result of the word search in the HTML editor, allowing a chance to review the text before deciding to make a replacement. To replace the highlighted word, click Replace again to make the replacement.

Clicking Replace All will replace all instances of a word within the survey without asking to confirm. Illume simply reports the number of occurrences replaced when the operation is complete. The Replace All operation cannot be undone.

The Start Over button begins a new search from the beginning of the survey document.

Search Scope

By default, find and replace operates on the entire survey. If one or more survey items have been selected before starting Find and Replace, only the Selected Items will be checked if the ” Selected items only” option to limit the operation has been checked.

When working within a group of selected items, checking Include items within selected collections will extend the find and replace operation into each of the collections that you have selected.

Search Options

• When Match Case is checked, Illume will perform a case-sensitive search in which upper- and lower-case letters must match exactly. E.g. A search for “Washington” will not find the word “washington” when Match Case is checked.
• When Match whole word is checked, your search will match whole words only. E.g. A search for “was” will match only the word “was” when this box is checked; otherwise, the search will match words like “Washington” that simply contain the letters “was” in succession.
• When Include variable references is checked, Illume will replace piping references. You should generally avoid this option unless you have a specific need like the one described under Replacing Variable References below.
• When Include item descriptions is checked, Illume will find and replace text within the data dictionary descriptions of questions and question tables. This is the text that appears on the Description tab of the question editor and in the description field of each item in the data dictionary.

Replacing Variable References

The Include variable references is useful in surveys that include near-identical collections of questions.

For example, the survey may ask the same 10 questions about a participant’s mother and father. The easiest way to build this survey would be to create a collection of the 10 “mother” questions first, and then to copy that entire collection and name the copy “father.”

When copying the collection, Illume asks to rename each of the questions. In this example, the question names may change from “AGE_MOTHER,” “OCCUPATION_MOTHER,” etc. to “AGE_FATHER,” “OCCUPATION_FATHER,” etc. There may be several places in the original collection that pipe data from reponses to previous questions. The piping might look like this:

How many years has your mother been working as a {OCCUPATION_MOTHER:Response}?

In the collection of questions about the father, you would obviously want the reference in the new collection to look like this:

How many years has your father been working as a {OCCUPATION_FATHER:Response}?

Running Find and Replace with the Include variable references option checked will make this replacement.

Undoing Find and Replace

To undo a find and replace operation:

1. Click Done to close the Find and Replace dialog if it is not already closed.
2. Right click in the right pane of the Survey Editor and choose Undo Find and Replace from the context menu.

The Revert to Saved button at the bottom of the Find and Replace dialog undoes changes to the text currently being displayed in the HTML editor.

Undoing Changes

Illume Survey Designer keeps track of up to 8 previous changes. To undo any of these changes choose the Edit Undo icon  from the Survey Designer menu, or press Control-Z. To redo any action that has been undone choose the Edit Redo icon  from the Survey Designer menu, or by pressing Control-R.

Setting Response Requirements on a Group of Questions

All questions inherit a survey-wide “required” setting which describes whether questions are optional or required. Each individual question within a survey can override the survey-wide option. (See the links below for more information on survey-wide and question-specific settings.)

Illume also provides a convenient way to set whole groups of questions as “required” or “optional.”

1. Select several items in the right pane of the survey editor. This can be done by holding down the Control key while clicking on each of the items, or click a single item, then hold down the shift key while clicking another item. Holding the shift key causes everything between the first and second items clicked to be selected.

2. Right click anywhere within the selected group and choose Set Required from the context menu.

3. Choose one of the two “Response Required” options to apply to the selected group.The Use preferences setting option causes the questions to inherit the survey-wide default setting, which appears in red text.The Always use the following setting option overrides the survey-wide setting.

4. If selecting a mix of questions and collections, and the setting to apply to all of the items within the collections selected, check the box labeled Include items in selected collections.

5. Click OK to apply the settings.

 

When checking the Always use the following setting option, the setting continues to apply to the selected questions, no matter what the survey-wide “required” setting. The only way to change the setting is to manually change the “required” setting for the specific question or group of questions.

NOTE: The settings applied to a selected group does not apply to attached text fields. These are always optional by default.

In a multilingual survey, response guides, such as whether or not a question is required, apply across all translations of the survey. The error messages may be set individually for each translation, as described in Setting a Question’s Response Guides.

 

Renaming Multiple Questions

To rename a several questions at once, follow these steps:

1. Select the collection or the group of questions to rename in the right pane of the Survey Designer.

NOTE: To choose multiple items, hold the Control key and click each item individually. Holding the Shift key while clicking selects every item between the first and last items selected.

2. Right-click on the selected items and choose Rename from the context menu.

3. If the selection includes collections that contain items to rename, check Include items within selected collections.

4. Choose the types of items to rename from the list of checkboxes. Notice that checking and unchecking different options causes the items to appear or disappear from the Rename Summary at the bottom of the Rename dialog.

5. Follow the Steps in Renaming Options to change the Suffix or Prefix of the questions.

6. Click Generate Names to preview the changes. The Rename Summary list at the bottom of the dialog shows the new names that will be applied to each of the selected items. Scroll down to see the entire list if it is a large list.

7. When satisfied with the changes, click Rename to rename the items.
   

Renaming Options

1. Prefix will add whatever prefix specified to the name of each item that appears in the Rename Summary list.

2. Suffix will append whatever suffix specified to the name of each item that appears in the Rename Summary list.

3. Name applies prefixes and suffixes to the current variable names that appear in the Rename Summary list. It is also possible to replace text within existing variable names when this option is chosen.
   

The Generate sequence option will replace the current names in the Rename Summary list with a customizable alphabetic or numeric sequence. Prefixes and suffixes will be applied to the letters or numbers of the sequence.

4. The Adjust Current Name fields appear only when the Use current name option is chosen. Illume will replace the text typed into Replace with the text typed into With in all of the names listed in the Rename Summary list.

5. The Sequence options appear only when Generate sequence is chosen from the Name list. The Numeric option generates a numeric sequence starting with the number in Start sequence with and using at least the number of digits specified in Minimum digits. (Illume adds leading zeroes until the minimum number of digits is satisfied.) The Alphabetic option starts an alphabetic sequence starting with the letter you specify in Start sequence with. When using sequences, any prefixes and suffixes specified will be applied to the sequence.

Undoing a Rename Operation

As noted above, Illume does not actually rename any items until the Rename button has been clicked.

To undo the changes, choose Edit Undo Rename Items from the Survey Designer menu, or press Control-Z.

The Undo the renaming operation will not work after performing another undoable action such as Spell Checking or Find and Replace.

 

 

This page describes the concepts of unauthenticated and authenticated surveys, and how to set up each type in the Illume Survey Designer.

What is an Unauthenticated Survey?

An unauthenticated survey is one in which:

• No credentials are required to take the survey
• A respondent may take the survey multiple times, as the survey does not “know” who the respondent is, or that the respondent has previously taken the survey.

This type of survey might be a link on a website like Facebook, wherein the respondent simply clicks on the link and is taken immediately to a series of questions

Configuring an Unauthenticated Survey

Every Illume survey contains a Login Collection, which is the one and only collection that cannot be deleted.  It is within this collection that authentication is handled.  The purpose of the login collection is to ask participants for credentials to log in. By nature of being an unauthenticated survey, no credentials are required to log in.  Thus, to configure a survey to be unauthenticated, you simply need to ensure you create no questions in the Login Collection.  Your login collection may contain a text object, such as a welcome page, but should not capture any information.

If you do not want/need your participants to see the login collection page of the survey, you can add a tag to the end of the URL: &LoginID=1.  For example, if your survey URL is:

https://demo.datstat.com/collector/Survey.ashx?_n=SaraSurvey

Then the URL to use when you want to bypass the login collection is:

https://demo.datstat.com/collector/Survey.ashx?_n=SaraSurvey&LoginID=1

What is an Authenticated Survey?

An authenticated survey is one in which:

• Access is controlled and limited to a defined set of participants
• A passcode or unique combination of passcodes/IDs must be entered to launch the survey
• The passcode (or unique combination of passcodes) can only be used once – one submission per participant

Configuring an Authenticated Survey

Setting up a survey to be authenticated requires implementation steps in the Survey Designer, as well as steps in the Enterprise Manager.  This page will cover the steps in the Survey Designer.

The first step in configuring an authenticated survey is determining on what participant variable, or combination of variables, do you want to authenticate.  There are two options in this regard:

1. Use a customer-defined pre-assigned ID schema (Custom ID authentication)
2. Have Illume generate a unique ID for each participant (System-Generated ID authentication).  This method is typically only used when the survey link is being distributed via an Illume Email Job, wherein Illume automatically generates a unique URL per participant, allowing the participant to click on the link and be taken directly to the first page of the survey without ever seeing the Login page or needing to enter an ID.

Custom ID Authentication

When using this method of authentication, you have pre-defined a single participant variable, or a combination of participant variables, that uniquely identify your respondent.  For example, you may have a file containing the first and last names of all participants, along with their email addresses and employee ID numbers. Let’s assume these fields are named FIRSTNAME, LASTNAME, EMAIL, and EMPID. Let’s also assume you want participants to log in using their email address and employee id number. To do this, you would create two questions in the Login Collection: one name EMAIL that asks for the participant’s email address, and another named EMPID that asks for employee id.  When a participant types in his or her email address and employee id, Illume checks that the following two things are true:

1. The list of participants associated to the survey contains a participant with  the given email address and employee id.
2. The participant with the given email address and employee ID has not already taken the survey for the current Time Period (see Academy section on Time Periods)

You may use any field or combination of fields in your participant list to authenticate participants. For each field you want to use:

1. Add a question to the Login Collection (in the standard way you would create any type of question)
2. Make sure the question’s data dictionary name matches the desired field name in the participant list.

The recommended data dictionary name to utilize for a single custom authentication variable in the login collection is DATSTAT_ALTPID.  DATSTAT_ALTPID is a built-in participant property on Illume participant lists designed to capture and store the participant’s alternate participant ID.

If utilizing DATSTAT_ALTPID in the login collection, ensure the data type utilized on the Response Options tab is “Text” to match the data type of the participant property.  Utilizing this property instead of building your own custom property for authentication provides advantages in regards to ease in updating participants via flat files.

Manual vs Auto-Authentication

Manual authentication involves sending your participants to the survey URL, and requiring your participants to enter their ID or unique combination of IDs in order to enter the survey.  Auto-Authentication involves having Illume’s Email Job generate a unique survey URL per participant, and having each participant click on that link and be taken immediately to the first question in the survey, bypassing participant visibility of the Login page (see section below on System-Generated ID Authentication)

Regardless of whether you are using manual or auto-authentication, you must build a question or question in the login collection to capture the ID(s).  Therefore your only other design consideration is in regards to what other content you may or may not choose to place in the Login collection.  If your survey uses manual authentication, then the first page your participants will see is whatever is in the login collection.  Given this, you may want to put a welcome page, logo, or or other information in the Login Collection.  If your survey uses auto authentication, then your participants will never see what is in the login collection.  Given this, any welcome pages or other instructional text should not be placed in the Login Collection, but rather should be placed just outside of the login collection.

System-Generated ID Authentication

This method of authentication is to be used when you do not want to create unique ids for all of your participants, but you do want to ensure that only people on your participant list can take your survey (and can take it only once).

When you upload a participant list in the Enterprise Manager of Illume, a unique ID is automatically generated for each participant on the list.  That ID is an alpha-numeric string and it is stored in a field called DATSTAT_PID.  System-Generated ID Authentication takes advantage of this automatically generated identifier by utilizing it for authentication.

The first step is to create a single question in the login collection. The question must have the display type “Text”, and the question’s unique name must be “DATSTAT_PID”. Your participants  will never see this question, as the first thing the participant will see when he/she clicks on the link generated in the Email Job is the first question in the survey.  That being said, you will still need to enter something for the prompt of the DATSTAT_PID question.

In the Enterprise Manager you will upload and associate a participant list to this survey.  It will not need a column for an ID.  The only required column is a column to contain the email addresses of each participant.

When you create an Email Job, Illume will send out email invitations to your survey with the unique ID appended to the URL.  Here is an example URL:

https://demo.datstat.com/collector/Survey.ashx?_n=SaraSurvey&LoginID=1

Important Cautions

1. Do not include duplicate entries in your participant list.For example, if you are requiring participants to provide an email address and employee id to access your survey, do not include in your participant list more than one participant with the same combination of email address and employee id, even if other data for these two participants differs. When a participant logs in, Illume looks for a unique participant in the list who matches the supplied credentials. If Illume cannot find a unique entry matching the credentials, the participant will not be allowed in.

2. Do not include questions in the Login Collection whose data dictionary names are not column names in the participant list.The example above used EMAIL and EMPID as the unique names of questions in the Login Collection. These matched the EMAIL and EMPID fields in the participant list. If the EMPID question had been named EMPLOYEEID, no participants would be able to log in, because the participant list contains no EMPLOYEEID column.

3. Do not include survey questions in the Login Collection. The Login Collection is only for authentication. Survey questions should live outside of the login collection.