Survey Scripting Best Practices

1. Overview

CAPI surveys are dynamic and often include complex logic across multiple levels of the questionnaire. SurveyToGo provides an extensive scripting framework that helps you implement a wide variety of common survey scenarios efficiently.

This article outlines recommended scripting best practices to help you build robust, maintainable, and efficient survey scripts. Following these guidelines can reduce development time, improve script readability, and help prevent production issues and data structure errors.

2. Variable Names

Assign a unique variable name to every question in your survey.

Although SurveyToGo automatically generates a variable name when a question is created, it is recommended that you replace the default name with the corresponding variable name or question number used in the questionnaire. You can do this from the Variables tab of the question.

Using meaningful variable names makes your scripts easier to read and maintain, and ensures that the same names appear in the exported survey data.

If the questionnaire contains multiple questions with the same variable name (whether intentionally or by mistake), inform the client and request that the questionnaire be updated so each question has a unique variable name.

In some cases, additional questions may be added to the survey script for technical or structural purposes, such as dummy questions or helper questions that do not exist in the original questionnaire. Assign meaningful, unique variable names to these questions as well instead of leaving the default generated names.

When assigning variable names, ensure they follow the valid naming conventions (primarily due to SPSS limitations):

• The variable name must begin with a letter.

• Do not use whitespace characters (such as spaces or tabs).

• Do not use special characters.

• Use only letters, numbers, and underscores (_).

3 Short IDs Display

In a survey script, each question has an ID called "Short ID", in addition to the Variable name. Unlike the Variable name, the Short ID doesn't have to be unique, but it is common to set it the same as the Variable name:

In the Survey Properties tab, there's an option to display the question's index on screen:

This allows the question index to be displayed at the beginning of the question text as part of the question body.

To enable this, set the Short ID property to display the question's index.

When both Display Question Index and Use Short ID as Question Index are enabled, the Short ID is displayed at the beginning of the question text.

Displaying the Short ID makes it easy to identify the current question in the survey, which is especially useful during script development, testing, and troubleshooting.

4. Answer Scales

It is common for the same list of answer options to be used across multiple questions. Instead of recreating the list each time, define it as an Answer Scale. Once created, the scale can be reused wherever needed.

Benefits:

• Enter the answer list only once.

• If the answer text or structure changes, update the Answer Scale once instead of modifying every question that uses it.

• Makes the survey script easier to read and maintain by clearly showing which questions share the same Answer Scale.

• Simplifies loop implementations that iterate through answers or topics.

5. Write Generic Code

Whenever possible, write scripts that are generic and reusable. Avoid hard-coded values that may change later or make the script difficult to maintain.

For example, it is common for a list of brands to include a "None of the above" option as the last answer in the list. Assume this option is answer index 10. Because this answer often requires special handling, you might be tempted to write code such as:

SetAnswerVisible(CurrQues, true, false, 10);

The value 10 is hard-coded. If additional brands are inserted into the list before "None of the above", the index changes and the script must be updated manually.

Instead, use the GetAnswerCount() function, which always returns the total number of answers in the question:

SetAnswerVisible(CurrQues, true, false, GetAnswerCount(CurrQues));

This approach keeps the script dynamic and ensures it always references the last answer, even if the answer list changes.

6. Multiple Filtering Methods

A common filtering scenario is displaying only the answers selected in a previous question. This can be accomplished using:

FilterAnswersByAnswers(QRef(2), QRef(1));

Sometimes multiple filtering operations must be applied to the same question.

For example:

• Q1, Q2, and Q3 use the same answer scale.

• The first nine answers are brands.

• The tenth answer is "None."

The logic for Q3 is:

• Show only the brands selected in Q1.

• Hide any of those brands that were also selected in Q2.

• Always display the "None" option.

Begin by filtering the answers selected in Q1:

FilterAnswersByAnswers(CurrQues, QRef(1));

To hide the brands selected in Q2 without removing the previous filter, use:

FilterAnswersByAnswers(CurrQues, false, false, QRef(2));

The third parameter (false) specifies that previous filtering should not be reset.

Finally, display the "None" option without resetting the existing filters:

SetAnswerVisible(CurrQues, true, false, GetAnswerCount(CurrQues));

7. Dummy Questions

Dummy questions are hidden questions that exist in the survey script but are not displayed to the interviewer.

Dummy questions simplify scripting, improve readability, and make complex logic easier to maintain.

Common uses include:

• Combining answers from multiple questions into a single question that can be referenced elsewhere in the survey.

• Storing randomly selected answers so they can be exported and reused throughout the survey.

• Simplifying complex entrance rules and filtering logic.

8. Expression Questions

Expression questions are commonly used to perform calculations, save values, or execute actions at specific points during the interview.

Because expression questions are not displayed, they are attached to either the previous or the next visible question. As a result, their code may execute later than expected.

To ensure expression questions execute at the intended point, enable the appropriate setting in the Survey Properties.

Alternatively, enable Start a new page on the following visible question. This separates the expression question from adjacent questions and ensures it executes when expected.

9. Random Calculations

Always save the results of random calculations in exported variables.

For example:

• If a random number determines survey flow, save that number.

• If a random selection of brands is displayed, store those selected brands in a dummy question.

Although these values may not be needed initially, they are often required later for validation, troubleshooting, or data analysis.

10. Remember That Text Piping Is for Display Only

Text piping dynamically displays text during the interview but does not save the displayed text as part of the survey data.

If the piped text is generated dynamically—for example, through calculations or randomization—save it to a variable or dummy question if it will be needed later for reporting or analysis.

11. Consider the Impact of the Back Button

Interviewers do not always progress through a survey in a straight line. They may navigate backward and change previous answers, so always consider how your script behaves when the Back button is used.

When updating dummy questions or calculated values, clear the existing value before setting a new one. For example, call ClearAnswer() before assigning new values to prevent outdated data from remaining after backward navigation.

Always test scenarios involving the Back button to ensure the survey behaves as expected.

12. Determine Whether a Question Was Answered

In some scenarios, your script must determine whether a question has actually been answered before executing additional logic.

Use the Answered() function to determine whether a question contains a valid response.

For example:

Answered(QRef(2))

When backward navigation is possible, use:

Answered(QRef(2), true)

Passing true as the second parameter causes Answered() to treat null response questions as unanswered, preventing logic from executing incorrectly after the interviewer navigates backward.

13. Answer Codes

Each answer has two important properties: Index and Code.

• Index represents the answer's position in the answer list, beginning with 1.

• Code is the value exported to the survey data.

By default, the answer code matches the answer index. However, some questionnaires use different codes. For example, the fifth answer may have a code of 99, or a brand listed third in the answer list may have a code of 300.

Whenever the questionnaire specifies answer codes that differ from the answer indexes, update the answer codes in SurveyToGo to match the questionnaire. This ensures the exported data contains the correct values.

Coca-Cola[c]300
Pepsi[c]301
Sprite[c]302
None of the above[c]99

14 Tracker Projects Keep variable names consistent

When scripting a tracker project, ensure that brands used as answers and topics retain consistent codes and variable names across all survey waves. Maintaining this consistency is essential for accurate data comparison and analysis over time.

To achieve this, set the Topic/Answer Variable Format property to use the Short ID and the Internal Item Code. This setting can be found in the survey's Advanced tab.

15 Tracker Projects Keep codes consistent

Like variable names, the items codes should remain consistent between different waves.

When updating an answers list between waves (brands etc.), you need to ensure you ‘lock’ the codes before adding new items to the list.

This property is enables by default in the Survey Properties tab:
It can also be enabled for each scale individually:
Set the “Use coding format in Iteration export” option in the survey properties so that the code is used to represent iteration on the brands rather than their indexes.

16 Tracker Projects Update lists without removing / overriding items

When updating answer lists or scales in a tracker project, always preserve the existing variable names, internal IDs, and answer codes to maintain consistency across survey waves.

When adding new items to a list or scale:

• Add the new items to the end of the list.
• Move them to the correct position using the Up and Down arrows.
• Assign the appropriate answer codes in the Coding column.

Do not delete existing items and recreate them. Removing and re-adding items generates new variable names and internal IDs, resulting in inconsistencies between survey waves.

Using Multi-Update

The Multi-Update feature updates only the text of existing items. It does not change their indexes, variable names, internal IDs, or answer codes. Each line in the Multi-Update list corresponds to the existing item at the same index.

For example, if the existing list is:

A (Index 1)
B (Index 2)
C (Index 3)

and you use Multi-Update with:

New A
B
New C

the list becomes:

New A (Index 1)
B (Index 2)
New C (Index 3)

The indexes, variable names, internal IDs, and answer codes remain unchanged.

When using Multi-Update in tracker projects, ensure that every existing item remains in its original position unless you intentionally want to change only its label.

For example, suppose the existing list is:

A
B
C

and the updated questionnaire requires:

A
New C

where B is removed and C is renamed.

It is incorrect to use the following Multi-Update list:

A
New C

In this case, New C replaces the item at Index 2, inheriting the variable name, internal ID, and answer code that originally belonged to B, causing data inconsistencies.

Instead, update the list as follows:

A
B
New C

Then hide B in the survey if it should no longer be displayed. This preserves the original mapping of indexes, variable names, internal IDs, and answer codes, ensuring consistency across tracker waves.

17 "Null Response" Questions

A null response is a question that is considered unanswered. In the exported data, null response questions are assigned the configured missing value (by default, -1, unless a different missing value has been defined).

A question is considered a null response in the following situations:

• Before it has been answered during the interview.
• If it is skipped and never displayed because of an entrance rule, jump rule, or other survey logic.
• When the interviewer navigates backward using the Back button.

When the Back button is used, the current question is automatically set to null response. If the question had previously been answered, its data is temporarily retained internally but is not included in the exported data while the question remains in the null response state. If the interviewer returns to the question and answers it again, the null response status is removed and the updated answer is exported.

18 "Null Response" Answers/Topics

By default, any answer or topic that is hidden before the question is displayed is treated as a missing value. This means that even if the answer or topic is automatically set by script before the question is shown, it is still considered a null response if it is hidden at that time. As a result, the exported data will contain the missing value instead of the value that was set.

If you need to automatically set the value of a hidden answer or topic and have that value exported, perform the auto-setting after the question has been displayed. A common approach is to place the code in the question's End script, where the value is assigned after the question has been shown to the interviewer.

19 Review the Data Before Going Live

It is essential to have your Data Processing (DP) team review the survey data before the script is released to production. Otherwise, issues with the data structure may not be discovered until fieldwork has been completed, making them much more difficult and costly to correct.

Before production, complete several test interviews and export the data for your DP team to review. This allows them to verify that the data structure, variable names, answer codes, and exported values meet the project requirements.

Alternatively, you can generate test data using the SurveyToGo Dummy Data Generator. For more information, see Using the SurveyToGo Dummy Data Generator.

20 Exported Questions

By default, every question in a survey is included in the exported data (with the exception of Empty question types).

In some cases, certain questions are used only to support the survey logic and are not required for data analysis. Examples include dummy questions, helper questions, and some expression questions. Excluding these questions from the export reduces the size of the exported dataset and keeps the data structure cleaner.

To exclude a question from the exported data, open the question's Variables tab and clear the Export checkbox.