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:
- Participant Responses: A participant’s answer to one question can be piped into another part of the survey.
- User Data: User data (data from a User’s participant list) can be piped into email jobs and surveys.
- Preloaded/Hidden Data: The values of variables defined as preloads or hiddens can be piped into your survey.
- Survey Parameters: Survey-wide variables, called survey parameters, can be set and the values of those variables can be piped into the survey.
- Current Question Attributes; Certain attributes of the current question can be piped into the question’s error message.
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:
- 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.
- Illume Next can read data appended to the survey URL and store it in a hidden variable.
- 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:
- {Response} The label associated with the participant’s response to the current question. For example, if the participant selected the response labeled “Toyota,” {Response} will contain the text “Toyota.” For checkbox questions, {Response} contains a comma-separated list of all of the items the participant checked. For text questions, {Response} contains the text the participant typed into the text box.
- {Value} The value associated with the participant’s response to the current question. For example, if the participant selected the response labeled “Toyota,” and that response has a value of 4 in the scale values for the current question, {Value} will contain the number 4. For checkbox questions, {Value} contains the number of options the participant checked. For text questions, {Value} contains the text the participant typed into the text box.
- {Score} For text, numeric, and date/time questions, {Score} yields the value of the response, just like {Value} above. However, {Score} will never be null. If a question was not answered, the {Score} will be zero. This is useful for arithmetic calculations in which null variables may cause problems. For Check all that apply questions, the {Score} tag gives the number of items checked. For individual checkboxes, the {Score} tag yields a value of 1 if the item is checked and 0 if the item is not checked.
- {RScore} The response’s reverse score. See the article on Calculations for details on how to use {RScore}.
- {QNum} The number of the current question (as displayed on the HTML page that the participant sees).
- {MinValue} The minimum value allowed as a response to the current question. (Applies to all question types except checkboxes.)
- {MaxValue} The maximum value allowed as a response to the current question. (Applies to all question types except checkboxes.)
- {MinRequired} The minimum number of options that must be checked in a group of checkboxes. (Applies to checkboxes only.)
- {MaxRequired} The maximum number of options that may be checked in a group of checkboxes. (Applies to checkboxes only.)
- {MinLength} The minimum length (in characters) allowed in response to the current question. (Applies to Text Fields only.)
- {MaxLength} The maximum length (in characters) allowed in response to the current question. (Applies to Text Fields only.)
- {Prompt} Returns the prompt of the variable after the colon. Can be used to restate a prompt.
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:
- {ProgressBar} An image representing how far a participant has progressed toward the completion of the survey. Because this is an image, you cannot embed it in an error message.
- {PercentComplete} A numeric value indicating the percentage of survey questions the participant will have completed upon submitting the current page.
- {PercentDisplayed} The percent of questions that have been displayed
- {SurveyName} The name of the survey
- {SessionID} The unique session ID associated to the submission
- {IpAddr} The participant’s IP (Internet Protocol) address. This is a usually looks something like “192.168.1.212.”
- {FormElement} This tag gives the id of the question’s HTML form element. For example, to get the id the form element for a question called AGE, use {FormElement:AGE}. This is useful primarily for client-side JavaScript. See “Custom Validation” for a practical example.
- {CustomFormElement} Outputs ID and instructs the Collector to process the variable.
- {Answered}
- {ResourceURL}
- {BaseURL} This tag is used to help with redirects to other surveys in the same system and will work in RDC and while previewing surveys. Example: If your survey is named Test_Survey, your normal URL would be: https://demo.datstat.com/Collector/Survey.ashx?_n=Test_Survey. The BaseURL for this survey would be: https://demo.datstat.com/Collector.
- {Random} Can be used to generate a random number in a specific range. Example {Random:1,10} will generate a random number between 1 and 10.
- {ShowIf} Can be used to pipe a value without having to create a calculation. Example {ShowIf:PART_STILL,=1,has} if the variable PART_STILL is 1 then the word “has” will be piped.
- {Loop} If used inside a Loop Object, can return the value of the current iteration of a Pre-defined or Follow-up Loop Object. Outside the Loop Object will return the specific name of the current iteration, or number of iterations.
Special Built-ins for Email Jobs
See Composing an Email Message for details about the context in which these tags may appear.
- {SurveyURL} This is used within the message body of an email job. Illume Next replaces this with a unique URL for each participant that takes the participant to the survey and automatically logs him/her in. This tag produces a clickable link. For example, {SurveyURL:Click Here to Start} produces a link with the text Click Here to Start.
- {SurveyRawURL} This is used within the message body of an email job. Illume Next replaces this with a unique URL for each participant that takes the participant to the survey and automatically logs him/her in. This does not produce a clickable link. It produces a URL suitable for cutting and pasting into a browser.
- {LaunchPageURL} This is used within the message body of an email job. Illume Next replaces this with the URL of the survey launch page. This is for surveys you want to run in a browser window that has no forward and back buttons, no menu or address bar, and no other user controls. This creates a clickable link. E.g. {LaunchPageURL:Click Here} produces a clickable link with the text Click Here.
- {LaunchPageRawURL} Used in the message body of an email job, Illume Next replaces this with the full (non-clickable) URL to the survey launch page. (See LaunchPageURL above.) This does not produce a clickable link; it does produce a URL suitable for cutting and pasting in a browser.
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.
- {SavePageEmailAddress} This is used in on the Save page only, in the error message that appears when a participant enters an invalid email address.
- {SavePageEmailText} This tag is for the Save Page. Illume Next replaces it with a text entry box in which a participant can type his or her email address. After supplying an email address and clicking the Send Email button, Illume Next sends the participant a message containing a link back to their survey in progress.
- {ResumeURL} This appears on the Save Page or in the Save Email. The Save Page appears after a participant sees after clicking the Save button. The Save Email is an email from the Illume Next system to the participant containing a link or URL the participant can use to resume a saved survey. Illume Next replaces this tag with a clickable link the participant can use to resume his or her survey. For example, Illume Next replaces {ResumeURL:Finish Your Survey} with a clickable link that says Finish Your Survey.
- {ResumeRawURL} This appears on the Save Page or in the Save Email. Illume Next replaces this tag with a unique URL the participant can use to resume his or her survey later. The URL will be a clickable link in most email clients (such as Microsoft Outlook). Participants can also cut and paste it into a browser to resume their survey.
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:
- {P:NAME} in addition to {ParamValue:NAME} to pipe in a parameter
- {U:NAME} in addition to {UserData:NAME} to pipe in user data
- {V:NAME} in addition to {Value:NAME} to pipe in a value from a question
- {R:NAME} in addition to {Response:NAME} to pipe in a response from a question