Survey Solutions for SurveyCTO Power Users

What exactly is Survey Solutions?

You already know how to build surveys. This module is about understanding the product you are moving into: what it is, why organizations use it, which account you actually need, and what is different from simply signing up for SurveyCTO.

Why would a project choose Survey Solutions?

It is not universally “better” than SurveyCTO, ODK, KoboToolbox, or other platforms. Its strengths are especially relevant when a project has a formal field hierarchy, complex household or establishment instruments, large samples, strong supervision requirements, or institutional requirements around World Bank-supported workflows.

Where SurveyCTO may still feel easier to you

Accounts: the first thing that confuses new users

Your Designer account and your project data-server account are not the same account. This distinction is fundamental.

Your recommended setup for this course

A simple picture of the identities involved

YOU
│
├─ Designer account
│    └─ create / collaborate / test questionnaires
│
└─ Project data-server account
     ├─ Administrator
     ├─ Headquarters
     ├─ Supervisor
     ├─ Interviewer
     ├─ Observer
     └─ API User

Designer account ≠ automatic access to project server

Before you continue: make sure you can answer these

How your Designer questionnaire gets onto the project server

This is the Survey Solutions step that is closest to SurveyCTO's Upload form definition. The idea is familiar, but the transfer is initiated from Headquarters.

Google Sheet / XLSForm
        ↓
Upload form definition
        ↓
SurveyCTO server
        ↓
Collect / web form

Questionnaire in Designer
        ↓
HQ imports questionnaire
        ↓
Project data server
        ↓
Assignments
        ↓
Interviewer / Web Interviewer

Set up your Personal Demo Server before the practical modules

A Personal Demo Server (PDS) gives you Administrator and Headquarters controls for a private practice environment. Use it for the course lab because the public demonstration server is mainly for observing existing content and cannot provide the same controlled setup.

Create the course practice team

Sign in to the PDS as its administrator and create these synthetic accounts. Choose unique temporary passwords and do not reuse a real work password.

Create users in the current PDS interface

1. Open the administrator area, select Users, and choose ADD USER for one account or UPLOAD USERS for a tab-delimited batch.
2. For a manual account, select the workspace and role, enter the login, enter the compliant password twice, then optionally add the full name, email and phone number.
3. Create sup_train before creating or uploading interviewers whose supervisor column contains sup_train.

Choose the account workflow. ADD USER creates one account; UPLOAD USERS opens the batch-user workflow.

Required account fields. Workspace, role, username and the two password fields are required. The full-name field lower on the page is optional operational metadata.

Batch-user dependency check: create the supervisor first

Why the batch failed. Interviewer rows name sup_train, but that supervisor did not yet exist in the selected workspace. Create the supervisor first or include a valid supervisor account in the batch as supported by the current template.

Verification after correction. Do not assume an upload succeeded because the file was accepted. Read the result and confirm the expected number and roles of created accounts.

The practice deployment cycle

Personal Demo Server guidance ↗

First version: step by step

Real PDS import sequence

1. Enter Survey Setup. Open Survey Setup in the black navigation bar and choose Questionnaires.

2. Start the import. An empty server shows no questionnaire rows yet; select IMPORT QUESTIONNAIRE.

3. Choose the Designer questionnaire. HQ lists the questionnaires accessible to the authenticated Designer account.

4. Confirm the copy into HQ. Review the questionnaire summary, optionally add a comment, and select IMPORT.

5. Verify the result. The questionnaire row now shows Version 1 and CAPI mode. Importing succeeds only when this server-side row appears.

So how are the two accounts linked?

They are connected at the moment of import rather than through one permanent shared login:

Signed in to project server as HQ
        ↓
HQ asks for Designer login
        ↓
Designer checks questionnaires you can access
        ↓
You select questionnaire
        ↓
HQ copies it onto the project server

This is why the same person may have a Designer login and a different project-server login.

What happens when you update the questionnaire?

This is the closest equivalent of uploading a revised XLSForm in SurveyCTO.

Versioning

Household Survey
Version 1   imported Monday
Version 2   imported Wednesday
Version 3   imported Friday

What about assignments that have not started?

When a newer questionnaire version is imported, Survey Solutions can offer to upgrade eligible assignments. If an assignment can be moved, the old assignment is archived and the remaining workload is recreated using the newer questionnaire version. Started interviews are not converted.

SurveyCTO comparison

Who can import?

The import is performed from Headquarters. The Designer login used during import must have access to the questionnaire. A collaborator with either View or Edit access in Designer can import that questionnaire to Headquarters.

Common reasons an import fails

Architecture: stop thinking “form upload”

The first job is to replace your SurveyCTO mental model with the Survey Solutions operational model.

Big-picture component flow

This visual helps tie together the main Survey Solutions components: Designer for questionnaire authoring, Tester/Web-Tester for testing, and the fieldwork chain of Headquarters → Supervisor → Interviewer.

Google Sheet / XLSForm
        ↓
SurveyCTO server
        ↓
Collect
        ↓
submission

Questionnaire Designer
        ↓
Headquarters
        ↓
Assignment
        ↓
Interviewer
        ↓
Interview
        ↓
Review / approval
        ↓
Export

Core actors

Designer: create, edit, test, and collaborate

Build your own questionnaire first, then learn to collaborate. Work through parts 4A–4F with Designer open in a second tab. Modules 5–8 extend these skills with expressions, calculations, rosters, and linked questions.

4A. Create your first questionnaire

Sign in to Designer. On its home page choose Create new, name the instrument Household practice — your name, and select Create. Reopen it later by selecting its title in your questionnaire list. Designer home page ↗

Open Settings, enter a questionnaire variable such as hh_practice, and Save. This variable names the main exported data file; it is different from the visible questionnaire title and from each question's variable name. Questionnaire settings ↗

Plan your sections before adding questions. The Cover holds deliberately chosen identifying information; interview content belongs in sections such as Consent and Household. Add these sections using the section controls. The tree below illustrates how the instrument will grow; you will learn roster construction in Module 7.

Questionnaire
├─ Cover
│  ├─ enumeration_area
│  └─ household_id
├─ Section: Consent
├─ Section: Household
│  ├─ hhsize
│  └─ Roster: members
│     ├─ name
│     ├─ age
│     └─ sex
└─ Section: Remittances
   └─ ...

4B. Edit questions and organize sections

The tree selects what you work on; the right editor changes that element; the narrow left rail opens questionnaire-wide tools. Start by building a small instrument you understand.

1. Select Consent and choose Add question. Create a categorical single-select named consent with text “May we begin this practice interview?” and question-specific options 1 = Yes and 2 = No. Save.
2. Select Household. Add a Text question named respondent_name, then an Integer numeric question named respondent_age. Give each clear question text and Save.
3. Select a question in the tree to reopen it. Question text is the interview wording; variable name identifies it in expressions and exports; variable label provides descriptive metadata. Change wording, then Save. Cancel discards an unsaved edit.
4. Add interviewer instructions for procedural guidance and Static text for information that needs no answer. Calculated variables are introduced in Module 6.
5. Drag to reorder within a section. To move to another section, select the element and use Move to. Review its new context, especially if moving into or out of a roster. Use Search for question to locate questions in a large instrument.
6. Before deleting or renaming an element, inspect references to it. After copying an element, review its name, categories and logic. Compile after structural changes.

Drag-and-drop is useful for local organization. Drag an element by its handle to change its order or place it in an accepted visible container. Watch the indentation before dropping: an item indented under a roster becomes roster-level and is repeated.

Right-click a group for its context menu. A section, sub-section, or roster can offer commands such as Add question, Add sub-section, Add roster, Add static text, and Add variable, plus Copy, Paste after, and Delete. The exact enabled commands depend on the selected container and nesting rules.

Keep this first build simple. Modules 5–6 teach enabling and validation expressions; at this stage you are mastering the editor. Elements and ordering ↗

Variable name, variable label, and question text

These three properties describe the same question for different purposes. The name identifies its data; the label describes that data; the question text supplies the interview wording.

Ordinary variable labels are not shown on the tablet; identifying-question labels on the Cover are an exception. Question properties ↗

SurveyCTO reference: the XLSForm name corresponds to the variable name, while the respondent-facing label corresponds to Question text. Do not map SurveyCTO's label to Designer's Variable label merely because both use the word “label.”

When should they be similar—and when should they differ?

Identical short wording can work for identifiers. For longer questions, write a concise analytical label that preserves units, population and reference period, while keeping natural interview wording in Question text. Put procedural guidance in Interviewer instruction, rather than burying it in an export label. In multilingual instruments, review translated question wording separately from the team's analytical naming convention.

Published limits are 80 characters for a variable label and 2,000 for question text. Keep both concise and check the exported statistical dataset rather than assuming a CSV header carries a variable label. Length limits ↗

Variable names

Questions, calculated variables and rosters use identifiers that are referenced directly in expressions and appear in exports. Build a naming convention early, just as you would in XLSForm.

hh_size
hh_member_age
remit_received
sender_country

Formatting question and static text

Survey Solutions allows a limited set of HTML tags inside question text and static text. This is the closest equivalent to using formatting markup in SurveyCTO labels. It is not arbitrary CSS: unsupported tags are removed by Designer. Formatting text ↗

Transfer recipient:
<strong><font color="#2E4085">%recipient_name%</font></strong>

<i>Please confirm the name before continuing.</i>

4C. Categories and questionnaire-wide tools

Reusable categories are named sets of numeric codes and labels stored at questionnaire level. The same set can serve more than one categorical question. This practice reference uses a synthetic education example; you create it yourself in Designer.

Where the set lives and what a change affects

1. In your practice questionnaire, open Reusable categories in the far-left panel of advanced instruments.
2. Create grade_codes manually or download Designer's XLSX/TAB template and upload a tab-delimited list with value and title headers.
3. Bind current_grade and highest_grade to that set. Filter out codes that are valid only for highest completed grade from the current-enrollment question.
4. Save, compile, and test both bound questions. If changing an existing set, download a backup first: an upload replaces its categories.

The SurveyCTO connection: choice lists versus preloaded data

The closest everyday analogy is a named list in SurveyCTO's choices sheet: several select questions can use the same list. Uploading a category file is also useful for the long lists that SurveyCTO programmers often maintain externally.

SurveyCTO can load choices during an interview from an attached CSV or dataset using search(). A Designer category upload instead incorporates a static list into the questionnaire. It does not establish a live connection to the original spreadsheet or reproduce SurveyCTO's dataset filtering automatically. SurveyCTO preloaded choice lists ↗

When adapting a SurveyCTO list, map its choice-value column to value and label column to title. Designer requires numeric category codes: preserve a documented crosswalk for string or leading-zero identifiers rather than silently converting them. Rebuild and test dependent filtering explicitly. Subsequent category changes require the intended updated questionnaire version to reach HQ; editing the source file alone does not update deployed interviews.

Do not confuse four category and reference mechanisms

The complete left sidebar: Panel of Advanced Instruments

From top to bottom, after the Designer logo, the rail in the screenshot opens these ten tools. Icon artwork can change between releases, so learn the tool name and purpose as well as its position. Panel of Advanced Instruments ↗

4D. Compile, test, and revise

Use the cycle edit → Save → Compile → Test → revise. Saving preserves an edit; compilation checks the questionnaire structure and expressions; testing checks the interview experience. A successful compile does not establish that the survey logic is correct.

1. Compile the instrument. Open reported issues, fix their causes, save and compile again. Review warnings too.
2. Choose Test and enter synthetic answers. Check wording, options, ordering, changing an answer, and returning to a question. Consent does not yet skip Household: you will add that logic in Modules 5–6.
3. Record expected and observed results. Later, repeat tests for both consent outcomes, missing values and invalid ages after adding logic.
4. Inspect your own revisions in History. Extract a revision into an independent copy for experiments; reverting changes the working document.

4E. Share your questionnaire with colleagues

Once your draft is ready for review, open Settings → Access. Enter your colleague’s exact registered Designer email or login, choose View or Edit, and select Invite. They must already have a Designer account. View permits inspection; Edit permits changes and Designer comments.

Sharing gives access to the same document; copying creates an independent instrument. Agree who edits which sections and use History to follow changes. An editor can share further. To change View to Edit, revoke access and invite again with Edit. Ownership transfer is separate from sharing. Sharing controls ↗

4F. When someone shares their questionnaire with you

Others can also share their instruments with you. Open the questionnaire from your Designer list or their link. The editor, categories and testing tools work as described above. What changes is your permission, responsibility to the owner, and need to understand an existing instrument.

Reading and writing Survey Solutions expressions

This module builds the expression language from the ground up. By the end, you should be able to identify what an expression must return, recognize the type of each value, read a roster lambda such as person => person.age >= 18, and diagnose the most common logic errors.

1. Start with the job of the expression

Before writing syntax, ask what Designer expects the expression to produce. Most logic errors begin when an expression returns the wrong kind of result.

An enabling condition cannot return a person's name or a count. A String calculated variable cannot return true. Designer's compiler uses types to catch many such mismatches.

2. What @optioncode means in an option filter

@optioncode is a special Survey Solutions context value available while Designer evaluates an option filter for an ordinary categorical question. It means: the numeric code of the candidate category being considered right now. It is not a questionnaire variable that you create, and it is not the respondent's answer.

If list_fruits contains codes 1 and 4, the filter is true while Designer tests Mango and Kiwi and false while it tests Oranges and Pineapples. The later question therefore displays only Mango and Kiwi.

Code, label and position are different

Common patterns

@optioncode != 99

list_fruits != null &&
list_fruits.Contains(@optioncode)

Do not confuse the context symbols

• Write @optioncode exactly as shown. Do not put it in quotes and do not use SurveyCTO's ${...} notation.
• The option filter controls which categories are offered; it does not enable or disable the whole question. Add a separate enabling condition when needed.
• When one question filters another, their codes must carry the same meaning. Reusable categories are the safest way to keep the codes aligned.
• A linked categorical question built from a List question or roster has a different candidate context. Do not assume every linked-source filter can use an ordinary @optioncode recipe.
• After changing an earlier answer, test what happens to a choice already selected in the filtered question on both Web Tester and Interviewer.

The official syntax guide calls @optioncode a substitution variable for non-linked categorical questions. Filtered answer options ↗

3. Variable names replace ${...}

${resp_age} >= 18
${sex} = 2
selected(${assets}, '3')

resp_age >= 18
sex == 2
assets.Contains(3)

• resp_age, sex and assets are variable names assigned in Designer.
• Do not add ${...}. Braces belong to the XLSForm/XPath convention.
• Answer codes such as 2 and 3 are values, not row positions and not labels.
• Text literals use double quotes, for example district_name == "Pavia".

4. Know what kind of value you are handling

A method or operator only makes sense for particular types. You cannot use .Contains(3) on a numeric age, add two text labels as though they were numbers, or compare a multi-select array directly with one code.

The exact underlying types vary by question kind. In the official type tables, a question mark such as int? means the value may be unanswered. Survey Solutions data types ↗

5. Operators and grouping

6. Missing is a state, not zero or empty text

Numeric, date and categorical questions can be unanswered. Survey Solutions documents them as nullable types. Decide what an unanswered value should mean in the particular rule instead of assuming it is zero.

IsAnswered(resp_age)

resp_age.HasValue

IsAnswered(resp_age) &&
resp_age >= 18

Do not translate SurveyCTO's ${income} != '' mechanically. For a numeric Survey Solutions question, use IsAnswered(income) or income.HasValue. A validation is evaluated only when the question has an answer, so IsAnswered(self) does not make an unanswered question mandatory. Use critical questions/rules or downstream enabling when requiredness matters.

7. self means the answer being validated

8. Scope: one row versus the whole roster

Inside the current members roster row, a bare reference such as age means the age in that current row. Outside the roster, there are many ages, so you must say how the whole collection should be evaluated.

age >= 18

members.Any(person =>
    person.age >= 18)

9. What exactly is person?

Break the expression into five pieces:

These are identical because the temporary name can be chosen freely:

members.Count(x => x.age >= 18)
members.Count(member => member.age >= 18)
members.Count(person => person.age >= 18)

You must use the chosen name consistently. members.Count(person => x.age >= 18) fails because the expression declares person but then refers to an undeclared x.

10. Choose the collection operation from the question you are asking

Official LINQ and lambda guide ↗

11. Translate in small steps

resp_age >= 18 && remit_channels.Contains(1)

Expression troubleshooting checklist

1. Location: must the expression return Boolean, text, a number, or a date?
2. Name: does every reference exactly match a Designer variable name?
3. Type: is the value scalar, nullable, multi-select, text, or a roster collection?
4. Scope: are you in one roster row or querying the full roster?
5. Missingness: what should happen while a dependency is unanswered?
6. Grouping: do parentheses preserve the intended AND/OR logic?
7. Behavior: after it compiles, did you test true, false, unanswered, and changed-answer cases?

Compilation proves that Designer can interpret the expression. It does not prove that the expression implements the intended survey rule. Syntax overview ↗

Calculated variables and reusable questionnaire logic

Module 5 taught how to read an expression. This module shows when to save an expression as a calculated variable, how to choose its type, how it reevaluates, and how to connect the result to questionnaire flow and quality checks.

1. Decide whether you need a calculated variable

consent == 1

is_eligible

For example, instead of repeating members.Any(person => person.age < 18) in four sections, create Boolean variable has_child and reference that name.

2. Build the variable in five deliberate steps

1. State the rule in ordinary language. Example: “Count household members aged 18 or older.”
2. Choose the output type. A count is a Long Integer.
3. Choose a meaningful name. Example: adult_count.
4. Write only the expression. Do not put an XLSForm field declaration or assignment statement in the expression box.
5. Test dependency changes. Add an adult, change the adult to age 17, remove the row, save and reopen.

type: calculate
name: adult_count
calculation:
count-if(...)

Type: Long Integer
Name: adult_count
Expression:
members.Count(person =>
    person.age >= 18)

3. Choose the output type from the meaning

4. Start with scalar calculations

Double variable total_sender_cost:

amount_sent + transfer_fee

Because the questions are nullable, the result is not a meaningful total until its dependencies are answered. Do not silently turn missing into zero unless that is the questionnaire's defined rule. If missing really means zero for both components, state that explicitly:

(amount_sent ?? 0) + (transfer_fee ?? 0)

5. Build a Boolean flag, then use it

Boolean variable is_eligible:

IsAnswered(resp_age) &&
resp_age >= 18 &&
recent_remit == 1

A later section can now use the readable enabling condition is_eligible. The variable centralizes the definition, but changing it also changes every dependent section, validation, filter or text substitution. Test all consumers after editing it.

6. Working household-roster model

The rest of this module uses one consistent example. Assume the questionnaire already contains a roster called members. Module 7 will show how a numeric, list, multi-select or fixed source creates its rows.

The sample household is Amina, age 42, female and head; Bilal, age 18, male and child; and Sana, age 11, female and child. Their monthly incomes are 20,000, 5,000 and unanswered respectively. Keeping this model fixed makes each function's effect easier to see.

7. Collection-function map

Read a collection expression from left to right: start with a collection → optionally filter rows → choose or aggregate values → return the required type.

8. Contains, InList and Length: selection and membership

Contains becomes handy whenever one answer can contain several values. The object before the dot determines what “contains” means.

assets.Contains(3)

caseid.Contains("HH-")

A single-select has only one code, so compare it directly or use InList for several accepted codes:

relationship == 1

relationship.InList(1, 2)

The second expression means “head or spouse.” Do not use Contains on a normal single-select answer.

9. Any: does at least one member qualify?

members.Any(person =>
    person.age < 5)

This returns Boolean. It is useful for enabling a child-health section, setting an eligibility flag, or warning that an age-specific module is expected. In the sample household it returns false.

Any() without a condition asks whether the roster has at least one row:

members.Any()

Use Any when you need yes/no existence. Do not calculate Count(...) > 0 unless you also need the count.

10. All: does every existing row qualify?

members.All(person =>
    IsAnswered(person.age))

This is useful for a completeness flag before enabling a household summary. Be aware of the empty-collection rule: All(...) is true when there are no rows because no row violates the condition. If the household must contain at least one member, write both requirements:

members.Any() &&
members.All(person =>
    IsAnswered(person.age))

11. Count: total rows, qualifying rows and answered rows

For an ordinary multi-select question, use assets.Length rather than treating it like a roster. For a yes/no-mode multi-select, assets.Yes.Length, assets.No.Length and assets.Missing.Length count each response state.

12. Where: keep qualifying rows for the next operation

members.Where(person =>
    person.age >= 5 &&
    person.age <= 17)

Where produces a filtered sequence of school-age member rows. By itself it is not a number or Boolean. Chain another function according to the question:

// How many school-age members?
members
  .Where(p => p.age >= 5 && p.age <= 17)
  .Count()

// Do any school-age members not attend school?
members
  .Where(p => p.age >= 5 && p.age <= 17)
  .Any(p => p.school_attend == 2)

You can often express the second rule more simply as one Any predicate. Use Where when the filtered collection feeds a later projection or aggregation and improves readability.

13. Sum: household totals and conditional totals

Double variable household_income:

members.Sum(person =>
    person.monthly_income)

Survey Solutions' migration guidance states that unanswered numeric values are ignored by Sum. In the sample household the result is 25,000. If “nobody answered” must remain different from a genuine total of zero, guard that state explicitly:

members.Any(p => IsAnswered(p.monthly_income))
  ? members.Sum(p => p.monthly_income)
  : (double?)null

A conditional household total filters first:

members
  .Where(p =>
      p.age >= 18 &&
      IsAnswered(p.monthly_income))
  .Sum(p => p.monthly_income)

14. Min and Max: youngest, oldest and range checks

Long Integer variables for youngest and oldest answered age:

members.Any(p => IsAnswered(p.age))
  ? members.Min(p => p.age)
  : (long?)null

members.Any(p => IsAnswered(p.age))
  ? members.Max(p => p.age)
  : (long?)null

Unanswered values are ignored by these aggregates, but an empty set has no meaningful minimum or maximum. The Any guard makes that state explicit. These functions are useful for household eligibility, age-range QA, finding the latest event number, or checking the largest plot size.

15. Select: project one field from each qualifying row

Select changes a collection of member rows into a collection of values:

members.Select(person =>
    person.member_name)

This does not yet produce a String variable. It produces a sequence of names that another operation can consume. A conditional projection combines Where and Select:

members
  .Where(p => p.age >= 18)
  .Select(p => p.member_name)

Use Select when the next step needs values rather than entire roster rows.

16. String.Join: turn projected values into readable text

String variable adult_names:

String.Join(", ",
  members
    .Where(p =>
        p.age >= 18 &&
        IsAnswered(p.member_name))
    .Select(p => p.member_name))

In the sample household the result is Amina, Bilal. It can be piped into an instruction such as “The adults listed are %adult_names%.” This joins stored answer values; it is not a general way to retrieve localized categorical answer labels.

17. FirstOrDefault: retrieve one match carefully

If the design guarantees one household head, this expression obtains the head's age as a nullable value:

members
  .Where(p => p.relationship == 1)
  .Select(p => p.age)
  .FirstOrDefault()

FirstOrDefault is order-dependent and returns a default when no match exists. It can conceal zero matches or multiple heads, so pair it with a separate validation:

members.Count(p =>
    p.relationship == 1) == 1

18. Read and build a chain in a fixed order

String.Join(", ",
  members
    .Where(p =>
        p.sex == 2 &&
        p.age >= 15 &&
        p.age <= 49)
    .Select(p => p.member_name))

Change the final operation to change the question being answered: use Count() for how many, Any() for whether at least one exists, Sum(...) for a total, or String.Join(...) for a display list.

19. Function selection practice

20. Construct scalar text and classifications

resp_age >= 18
  ? "Adult"
  : "Minor"

first_name + " " + last_name

Insert a calculated value into a question or static text with Survey Solutions text substitution, for example %adult_count%. Calculated results are otherwise not interviewer-editable answers.

21. Understand reevaluation and failure behavior

• Calculated variables reevaluate automatically when a referenced dependency changes.
• Interviewers cannot override the calculated result.
• In logical expressions, an exception is treated as false; in calculations, an exception produces null.
• A variable used only as a helper can be marked Do not export; an analytic indicator can be retained with a clear variable label.
• Cycles are invalid: variable A cannot depend on B while B also depends on A.

22. Connect calculations to questionnaire behavior

is_eligible

self <= total_income

consent == 2 ||
IsAnswered(end_time)

23. Test the dependency graph, not just the formula once

24. SurveyCTO translation reference

Expression evaluation ↗ · LINQ in rosters ↗

survey!V634 · r_age_calc (calculate)
if(${r_age_unit}=3, ${r_age}, 0)
survey!V635 · r_age_calc_month (calculate)
if(${r_age_unit}=2, ${r_age}, 
if(${r_age_unit}=1, 0,'null'))
survey!V636 · r_age_calc_days (calculate)
if(${r_age_unit}=3, 'null', 
if(${r_age_unit}=2, ${r_age}*30, 
if(${r_age_unit}=1, ${r_age},'null')))

Proposed Long integer r_age_calc, with Numeric Integer source questions:
(r_age_unit == 3 && r_age.HasValue) ? (long?)r_age.Value :
((r_age_unit == 1 || r_age_unit == 2) && r_age.HasValue) ? (long?)0 : null

survey!V649 · spouse_count (calculate)
count-if(${new_hhmem},${r_relation}=2)
survey!V650 · head_count (calculate)
count-if(${new_hhmem},${r_relation}=1)
survey!V1230 · no_unearned_income (calculate)
sum-if(${inc_any_unearn_ltm}, ${inc_any_unearn_ltm} = 1)

Outside new_hhmem, Long integer:
new_hhmem.Count(p => p.r_relation == 1)

Validation of the intended single-head rule:
new_hhmem.Count(p => p.r_relation == 1) == 1

survey!V2187 · temp_icm_sale (calculate)
if(${icm_op} >= 0 and ${icm_no_sale} >= 0, ${icm_op} - ${icm_no_sale}, 
   if(${icm_op} = -999 or ${icm_no_sale} = -999, -999, 
      if(${icm_op} = -888 or ${icm_no_sale} = -888, -888, '')))
survey!V2190 · temp_icm_sale_high (calculate)
if(${icm_op} >= 0 and ${icm_prof_avg_n} >= 0, ${icm_op} - ${icm_no_sale} - ${icm_prof_avg_n}, 
   if(${icm_op} = -999 or ${icm_no_sale} = -999 or ${icm_prof_avg_n} = -999, -999, 
      if(${icm_op} = -888 or ${icm_no_sale} = -888 or ${icm_prof_avg_n} = -888, -888, '')))
survey!V2195 · add_months_to_twelve (calculate)
if(${icm_no_sale} != null and ${icm_prof_avg_n} != null and ${icm_prof_high_n} != null and ${icm_prof_low_n} != null, 
   if(${icm_no_sale} = -999 or ${icm_prof_avg_n} = -999 or ${icm_prof_high_n} = -999 or ${icm_prof_low_n} = -999, -999, 
      if(${icm_no_sale} = -888 or ${icm_prof_avg_n} = -888 or ${icm_prof_high_n} = -888 or ${icm_prof_low_n} = -888, -888, 
         ${icm_no_sale} + ${icm_prof_avg_n} + ${icm_prof_high_n} + ${icm_prof_low_n})), 
   0)

Proposed Double temp_icm_sale (same sentinel priority):
(icm_op >= 0 && icm_no_sale >= 0) ? (double?)(icm_op - icm_no_sale) :
(icm_op == -999 || icm_no_sale == -999) ? (double?)-999 :
(icm_op == -888 || icm_no_sale == -888) ? (double?)-888 : null

survey!V863 · count_confirmed_currenthh (calculate)
sum(${ph1_confirmed_final})
survey!V864 · need_new_phones (calculate)
max(0, 3 - ${count_confirmed_currenthh})
survey!V865 · repeat_count_new_phn (calculate)
min(${need_new_phones}, ${temp_r_phone_calc})

Long integer confirmed_count:
repeat_hh_phone.Count(p => p.ph1_confirmed_final == 1)

Long integer slots_needed:
confirmed_count.HasValue ? (long?)Math.Max(0L, 3L - confirmed_count.Value) : null

survey!V1602 · start_month (calculate)
int(substr(indexed-repeat(${nonagown_start}, ${repeat_nonagown2}, ${index_nonagownb3}), 0, 2))
survey!V1603 · start_year (calculate)
int(substr(indexed-repeat(${nonagown_start}, ${repeat_nonagown2}, ${index_nonagownb3}), 3, 7))
survey!V1605 · nonagown_mth_grant (calculate)
((int(format-date(today(), '%Y')) - 2025) * 12) + (int(format-date(today(), '%m')) - 6)
survey!V1606 · nonagown_mth (calculate)
((int(format-date(today(), '%Y')) - int(substr(indexed-repeat(${nonagown_start}, ${repeat_nonagown2}, ${index_nonagownb3}), 3, 7))) * 12) + (int(format-date(today(), '%m')) - int(substr(indexed-repeat(${nonagown_start}, ${repeat_nonagown2}, ${index_nonagownb3}), 0, 2)))
survey!V1607 · nonagown_possible_op (calculate)
min(${nonagown_mth}, ${nonagown_mth_grant})

Proposed Long integer months_apart, with Date/Time questions start_date and reference_date:
(start_date.HasValue && reference_date.HasValue) ?
(long?)((reference_date.Value.Year - start_date.Value.Year) * 12
+ reference_date.Value.Month - start_date.Value.Month) : null

survey!V611 · start_res_member_info (calculate_here)
once(duration())
survey!V2321 · end_icm_qx (calculate)
once(duration())
survey!V2322 · dure_icm_qx (calculate)
( ${end_icm_qx}-${start_icm_qx} ) div 60

Design decision, not a C# substitution:
Use paradata for a documented section-duration measure,
or explicit timestamp questions for a clearly defined operational event.
For a verified seconds difference, divide by 60.0 to retain fractional minutes.

Rosters: SurveyCTO repeats, but with a source that defines the rows

Modules 5 and 6 treated members as an existing collection so you could learn how to query it. This module now explains where those rows come from, how their identities behave, and what happens when the source changes.

The four roster patterns

Example 1 — dynamic repeat count from a numeric question

integer hhsize
begin repeat members
  repeat_count = ${hhsize}

  text name
  integer age
  select_one sex sex
end repeat

Numeric question:
hhsize

Roster:
members
Source type: Numeric
Source question: hhsize

Inside roster:
name
age
sex

If hhsize = 3, Survey Solutions creates three members rows. This is the closest equivalent of a SurveyCTO dynamic repeat_count. The official roster documentation defines numeric rosters exactly this way.

Example 2 — SurveyCTO count-selected() intuition

Suppose respondents select every crop they cultivate:

count-selected(${crops})

Roster: crop_details
Source type: Multi-select
Source question: crops

Example 3 — yes/no multi-select roster

A multi-select question in yes/no mode can also trigger a roster. Only items marked Yes create roster rows. If you need the number marked Yes in an expression, use:

assets.Yes.Length

For example, if the asset list contains Radio, TV, Refrigerator and Motorcycle, and Radio + Motorcycle are marked Yes, the asset-detail roster has two rows.

Example 4 — list question as the roster source

Instead of asking “How many members?” and then collecting names inside the roster, you can first collect a list:

This pattern is often more intuitive for household listings because the person's name can serve as the visible roster title.

Scaling a roster down: what happens if the source gets smaller?

This is important if you are used to changing repeat_count in SurveyCTO. The roster follows its trigger question. If a numeric trigger drops from 4 to 2, the roster drops from four rows to two. If a selected crop is unselected, that crop's roster row disappears. If an item is deleted from a list source, its corresponding roster row disappears.

index() equivalent: use @rowindex, but learn @rowcode too

SurveyCTO/ODK's repeat-position idea maps most closely to Survey Solutions @rowindex. The official migration guide maps position(xpath) to @rowindex.

first row  → @rowindex = 0
second row → @rowindex = 1
third row  → @rowindex = 2

Pulling a name out of a roster: SurveyCTO indexed-repeat()

Your SurveyCTO pattern creates household-level calculations from individual repeat instances. For example, r_comp_name is the name field inside repeat new_hhmem:

new_calc_hh_mem_name1 = indexed-repeat(${r_comp_name}, ${new_hhmem}, 1)
new_calc_hh_mem_name2 = indexed-repeat(${r_comp_name}, ${new_hhmem}, 2)
new_calc_hh_mem_name7 = indexed-repeat(${r_comp_name}, ${new_hhmem}, 7)

The three arguments mean field to retrieve, containing repeat, one-based instance number. These expressions request the first, second, and seventh names. SurveyCTO also supports additional repeat/index pairs for nested repeats. Its documentation notes fallback to instance 1 for an invalid index, so do not assume an invalid request always returns blank. Test the source behavior before reproducing it. SurveyCTO indexed-repeat reference ↗

A positional retrieval pattern in Survey Solutions

For this exercise, create a roster named new_hhmem containing Text question r_comp_name. Inside that roster add a Long integer calculated variable named member_position, with expression @rowindex + 1. It exposes the current row's position as a one-based number for this comparison. Outside the roster, add these String calculated variables:

// new_calc_hh_mem_name1
new_hhmem.Where(p => p.member_position == 1)
  .Select(p => p.r_comp_name).FirstOrDefault() ?? ""

// new_calc_hh_mem_name2
new_hhmem.Where(p => p.member_position == 2)
  .Select(p => p.r_comp_name).FirstOrDefault() ?? ""

// new_calc_hh_mem_name7
new_hhmem.Where(p => p.member_position == 7)
  .Select(p => p.r_comp_name).FirstOrDefault() ?? ""

Enter each expression without its explanatory comment. Where finds the requested position; Select extracts its name; FirstOrDefault retrieves one value or null; ?? "" displays an empty string for null. The alias p means one roster row. Place static text outside the roster containing Second member: %new_calc_hh_mem_name2% to see the result.

Do not mechanically translate the seventh instance into new_hhmem[7]. Roster addressing must respect row codes and the roster source; a position and a person's identity are different. The explicit position variable makes the intended rule visible. Compile these expressions in your Designer version and test the row changes below before using them in a project.

Choose the retrieval rule that matches the survey question

In your screenshot, count(${new_hhmem}) counts repeat instances. The corresponding roster count is new_hhmem.Count(); counting answered names instead requires a predicate. Do not use a count of distinct name strings as a count of unique people: two members may share a name, and spelling differences can make one name appear distinct.

Why the distinction matters after deleting list items

Using row identity in conditions

Suppose a fixed roster has codes 10 = Matches and 11 = Cigarettes. Inside that roster you can apply different rules by row:

@rowcode == 10 ? self <= 20 :
@rowcode == 11 ? self <= 100 :
true

The system-generated @rowcode exists specifically for referring to particular roster rows.

Dynamic roster titles

To make roster questions intuitive for interviewers, use the roster's title/name in question text. For a member roster named members, you can write wording such as:

How old is %rostertitle%?

If the current roster title is Amina, the interviewer sees How old is Amina? The roster identifier form, such as %members%, is also supported, but %rostertitle% makes the intent explicit while working inside the current roster. Neither form is valid outside its applicable roster scope.

Nested rosters

You can put one roster inside another—for example:

Household
└─ members
   ├─ name
   ├─ age
   └─ jobs
      ├─ employer
      └─ earnings

Survey Solutions supports nested rosters, but current limits cap nesting depth and total roster instances. Complex nested designs should be tested with realistic maximum sizes rather than only with tiny test households.

Table presentation for web interviews

For CAWI/web interviewing, some simple rosters can be displayed as a table, with roster items as rows and questions as columns. This can be useful for compact modules such as prices or simple household grids. It is subject to design restrictions and falls back to the normal subsection-style roster on tablets.

Practical design rules

From roster source to household indicator

This final sequence connects the three modules without mixing their responsibilities:

survey!W613 · repeat_res_member_info (begin repeat)
${hhmem_new_num_push}
survey!V614 · index_res_member_info (calculate)
index()
survey!V615 · index_res_kids_id (calculate)
${index_res_member_info} + 18
survey!V616 · temp_res_member_info_name (calculate)
indexed-repeat(${r_fname}, ${new_hhmem}, ${index_res_member_info})
survey!V619 · temp_res_member_info_rela (calculate)
indexed-repeat(${r_relation}, ${new_hhmem}, ${index_res_member_info})

Proposed design:
One members roster holds name, stable source_member_id, relationship,
residency status, age and education subsections.
Use a separate source_member_id field to preserve old identifiers.
Do not assign @rowcode = index + 18 or equate @rowindex with a persistent ID.

survey!V746 · join_hh_mem_older_six2 (calculate)
join-if(',', ${info_current_all_index}, ${age_hhmem} >= 6)
survey!V748 · count_hh_mem_older_six (calculate)
count-if(${info_current_all}, ${age_hhmem} >= 6)
survey!V749 · join_hh_mem_older_thirteen2 (calculate)
join-if(',', ${info_current_all_index}, ${age_hhmem} >= 13)
survey!V750 · join_hh_mem_13_older (calculate)
join-if(',', ${age_hhmem}, ${age_hhmem} >= 13)
survey!V751 · join_hh_mem_older_13 (calculate)
join-if(',', ${info_current_all_name}, ${age_hhmem} >= 13)
survey!V752 · count_hh_mem_older_13 (calculate)
count-if(${info_current_all}, ${age_hhmem} >= 13)
survey!W1038 · repeat_earned_inc (begin repeat)
${count_hh_mem_older_13}
survey!V1040 · any_work_screen_name (calculate)
item-at(',', ${join_hh_mem_older_13}, (${index_any_work_screen} - 1))
survey!V1041 · any_work_screen_memid (calculate)
item-at(',', ${join_hh_mem_older_thirteen2}, (${index_any_work_screen} - 1))
survey!V1042 · any_work_screen_age (calculate)
item-at(',', ${join_hh_mem_13_older}, (${index_any_work_screen} - 1))

Assuming age_hhmem is numeric inside info_current_all:

Household-level Long integer:
info_current_all.Count(p => p.age_hhmem >= 13)

Household-level String display summary:
String.Join(", ", info_current_all.Where(p => p.age_hhmem >= 13)
.Select(p => p.info_current_all_name))

Within that roster, income subsection enabling:
age_hhmem >= 13

survey!W884 · repeat_fd_cat (begin repeat)
9.0
survey!V891 · fd_cons_cnt (calculate)
count-selected(${fd_cons_1})
survey!W892 · repeat_fd_cons (begin repeat)
${fd_cons_cnt}
survey!V894 · fd_cons_val (calculate)
selected-at(${fd_cons_1},index()-1)
survey!V895 · fd_cons (calculate)
pulldata('preload_fd_cat', 'fd_cons_name', 'cons',${fd_cons_val})

Proposed design:
Fixed food-category roster → multi-select fd_cons_1 → item roster.
Inside the item roster, @rowcode identifies the selected category code;
use the chosen item labels for roster titles.
Preserve multilingual labels through translations, not numeric lookup columns.

survey!W702 · r_kids (select_multiple old_new_hh_members)

survey!W703 · repeat_kids (begin repeat)
count-selected(${r_kids})
survey!V704 · kid_age (calculate)
selected-at(${join_age_kids_15}, index() - 1)
survey!V705 · kid_age3 (calculate)
if(${kid_age} <0 and ${kid_age} <=2, 1, 0)
survey!V706 · kid_age3to8 (calculate)
if(${kid_age} >2 and ${kid_age} <=8, 1, 0)
survey!V707 · kid_age9to15 (calculate)
if(${kid_age} >8 and ${kid_age} <=15, 1, 0)
survey!V709 · r_kids_baby (calculate)
sum(${kid_age3})

Proposed rule after confirming ages and child identities:
children.Count(c => c.age >= 0 && c.age <= 2)
children.Count(c => c.age > 2 && c.age <= 8)
children.Count(c => c.age > 8 && c.age <= 15)

Here children is a proposed child roster and age is numeric;
it is not a literal rename of the ICM repeat.

survey!V312 · count_join_nonagwork_name (calculate)
count-items(" ", de-duplicate(" ", ${join_nonagwork_num}))
survey!V1052 · join_ag_index (calculate)
de-duplicate(' ',  join(' ', ${ag_index}))

survey!V1053 · join_nonag_index (calculate)
de-duplicate(' ',  join(' ', ${nonag_index}))

survey!W1595 · repeat_nonagown3 (begin repeat)
${count_nonagown_list}+${nonagown_n_calc}

Proposed Long integer, assuming a redesigned members roster and String member_id:
members.Where(p => !String.IsNullOrEmpty(p.member_id))
.Select(p => p.member_id).Distinct().Count()

Linked questions: turning earlier answers into live answer options

This is one of Survey Solutions' most powerful features for complex household, labor, agriculture, education, health, and establishment surveys. A linked categorical question can take values collected earlier—often people or roster rows—and turn them into the answer options of a later question.

Simple example: choose the household head

You first collect household members:

Survey Solutions' official categorical-question documentation describes linked questions exactly this way: their categories are generated during the interview from answers to a previous text, numeric, date question, or roster source. Categorical questions ↗

How you configure one in Designer

Linked describes the source of the answers. In the Designer interface shown by the trainee, use Source of categories; older documentation instead shows an Is linked checkbox.

If the binding dropdown is empty

1. Confirm that the intended source is located before the linked question and has been saved.
2. For a direct source, use an actual List question, or a supported Text, Numeric, or Date question located inside a roster.
3. If the aim is to show a subset of the same fixed categories selected in an earlier categorical multi-select, leave the linked-source selector. Give both questions the same category codes and use an @optioncode filter, as shown below.
4. Create a roster from the multi-select only when the questionnaire needs one row—or several follow-up questions—for every selected category.

Favorite fruit: filter the choices; do not create a roster

Suppose list_fruits is a categorical multi-select with codes 1 Mango, 2 Oranges, 3 Pineapples, and 4 Kiwi. The next question asks, “Of the fruits you selected, which is your favorite?” This is one answer chosen from a filtered fixed list, so it does not require a roster.

1. Create favorite_fruit as a Categorical: Single-select question.
2. Use the same four category codes and titles. Prefer one Reusable categories set bound to both questions; separately entered categories also work only if their codes remain identical.
3. Keep Source of categories as User defined categories or Reusable categories. Do not choose List question or question from roster group.
4. Add this option filter: list_fruits != null && list_fruits.Contains(@optioncode). If the symbol is unfamiliar, review Module 5: What @optioncode means.
5. Add this enabling condition so the question appears only after at least one fruit is selected: list_fruits != null && list_fruits.Length > 0.

Designer evaluates the filter once for every candidate category. Here @optioncode is the code of the candidate currently being tested. If the respondent selected Mango (1) and Kiwi (4), only Mango and Kiwi appear in favorite_fruit.

Follow the behavior from Designer to the interview

The screenshots below show the two expressions doing different jobs. The enabling condition controls whether the whole favorite-fruit question is active. The option filter controls which fruit choices appear after the question becomes active.

1. Before a fruit is selected

list_fruits has no selected codes, so list_fruits != null && list_fruits.Length > 0 is false. The diagonal shading shows that the entire favorite-fruit question is disabled. The blue sentence is an interviewer instruction; it helps the interviewer but does not affect the logic.

2. After Mango and Pineapples are selected

The source multi-select now contains codes 1 and 3. The enabling condition is true, so the favorite-fruit question becomes active. The option filter tests every candidate and retains only Mango and Pineapples.

3. The matching Designer configuration

The screenshot uses variable name fav_fruits; the course example uses favorite_fruit. Either name is valid when used consistently. Notice that the Filter and Enabling condition are separate fields: filtering does not activate the question, and enabling does not reduce its options.

Complete the reusable-category binding. In the Designer screenshot, Source of categories is set to Reusable categories, but Bind to reusable categories appears empty. Select the reusable fruit set—for example fruit_codes—before saving and compiling. Ideally bind both list_fruits and fav_fruits to that same set. Otherwise the filter can compile against codes whose labels or meanings do not match the source question.

Interview state	Enabling condition	Option filter result	What the interviewer sees
No fruits selected	false	Not operationally relevant while the question is disabled	The favorite question is shaded and unavailable.
Mango and Pineapples selected	true	True for codes 1 and 3; false for 2 and 4	Only Mango and Pineapples appear as radio-button choices.
Selection later changes	Reevaluated	Reevaluated for every candidate code	The available favorite choices change; verify any previously selected favorite during testing.

Behavior test: Select Mango and Pineapples, choose Mango as the favorite, then return to list_fruits and deselect Mango. Confirm how Web Tester handles the now-ineligible favorite. Repeat in the Interviewer application. Record whether the answer is cleared, flagged, or otherwise requires correction; this dependency-changing case matters more than testing only the happy path.

Single-select vs multi-select linked questions

Filtering linked options: where this becomes powerful

The Filter field is evaluated once for every potential option. If the expression is true, that option is shown; if false—or if evaluation throws an exception—the option is hidden. Conceptually, it is an enabling condition applied separately to each possible answer option. Filtered options ↗

Example 1 — only adults can be household head

Filter:

age >= 18

Example 2 — women of reproductive age

If sex == 2 means female:

sex == 2 && age >= 15 && age <= 49

Survey Solutions' current syntax overview uses this exact kind of linked-roster filtering example. Filter syntax ↗

The important keyword: @current

This is where linked questions become especially useful inside a roster. When you are asking a question about the current roster row but filtering potential choices from the whole roster, you need a way to distinguish:

Example 3 — choose the mother of each household member

Suppose the linked question mother sits inside the members roster. You want to show only candidates who are:

• female;
• not the current person;
• at least 10 years older than the current person.

sex == 2
&& @rowcode != @current.@rowcode
&& age >= (@current.age + 10)

This is essentially the pattern used in Survey Solutions' official filtered-answer-options documentation. Filtered options ↗

Example 4 — spouse selection

Assume sex is coded 1 = male, 2 = female. A simplified opposite-sex spouse filter could be:

@rowcode != @current.@rowcode
&& sex != @current.sex
&& age >= 15

For a real survey you would normally add your survey's own age, marital-status, relationship, and plausibility rules rather than relying on sex alone.

Example 5 — double screening without creating another roster

Imagine you first ask a linked multi-select:

employed_members
"Which household members are employed?"

Then you ask:

multiple_jobs
"Which employed household members have more than one job?"

The second linked question can use the earlier dynamic list and filter it again. Survey Solutions explicitly added filtering of questions linked to a list to support this type of double screening. Linked-list filtering ↗

Example 6 — link to non-person rosters

Linked questions are not just for household members. Suppose you collect plots:

You can link to the plot-name question or to meaningful roster titles, then filter by crop, size, ownership, irrigation status, or any other relevant variables.

Linking to text, numeric, date, and roster titles

The categorical multi-select documentation explicitly lists text, numeric, date, and roster-linked sources. Categorical questions ↗

Linked question vs ordinary filtered categorical question

Who is the head?
[Amina]
[Bilal]
[Sana]

Payment method
[Bank]
[Cash]
[Wallet]

What gets stored? The label is not the data key

For example, if the roster contains:

row code 0 → Amina
row code 1 → Bilal
row code 2 → Sana

and a linked question selects Sana, the stored/exported answer is associated with code 2, while the interviewer sees the human-readable label Sana.

Multi-select linked questions can make wide exports

A linked multi-select may create many export columns because Survey Solutions has to allow for the potential maximum number of source records. This can surprise you if you come from SurveyCTO and expect a compact space-separated answer string. Survey Solutions' categorical multi-select documentation describes how linked multi-select exports depend on the source roster's potential size. Multi-select export ↗

Common mistakes

When I would reach for linked questions immediately

survey!V689 · info_current_all_index (calculate)
selected-at(${joined_old_new_hhmems}, index()- 1)
survey!V690 · info_current_all_name (calculate)
choice-label(${hh_resp}, ${info_current_all_index})
survey!V2229 · mem_old_rel_index (calculate)
if(selected(${icm_grp_mem_name_old}, 0), selected-at(${icm_grp_mem_name_old}, index()), selected-at(${icm_grp_mem_name_old}, index()-1))
survey!V2230 · mem_old_rel_lbl (calculate)
pulldata('icm_part_preloads', 'icm_part_og_name1', 'id', ${mem_old_rel_index})

Design route:
Keep respondent/member selection linked to the member roster.
Use question text substitution or supported label-display behavior for wording.
Retrieve a member attribute through the linked identity only after checking
that the selection still exists; see the linked-question examples in this module.

survey!V2243 · cnt_icm_grp_mem_name_0 (calculate)
if(selected(${icm_grp_mem_name}, '0'), 0, count-selected(${icm_grp_mem_name}))
survey!V2244 · cnt_icm_grp_mem_name (calculate)
if(selected(${icm_grp_mem_name}, 0), (${cnt_icm_grp_mem_name_0}) - 1, count-selected(${icm_grp_mem_name}))
survey!W2258 · repeat_mem_oth_rel_ex (begin repeat)
${cnt_icm_grp_mem_name}
survey!V2259 · mem_rel_index_ex (calculate)
if(selected(${icm_grp_mem_name}, 0), selected-at(${icm_grp_mem_name}, index()), selected-at(${icm_grp_mem_name}, index()-1))

Illustrative Long integer for an ordinary categorical multi-select:
icm_grp_mem_name == null ? 0 : icm_grp_mem_name.Count(code => code != 0)

Use this only after confirming 0 means a non-member option and preserving
all other exclusions. This expression does not apply to a linked roster answer.

Assignments, sample lists, and preloading household information

This is the Survey Solutions equivalent of one of the most common SurveyCTO case-management workflows: you already have a household sample with IDs, geography, household head, address, and sometimes earlier-wave information, and you want interviewers to receive the right case without asking all of that information again.

SurveyCTO case management vs Survey Solutions

Concrete example: a household sample from the Philippines

Suppose your sampling team gives you this household list:

For a fixed sample where each row is one household, this is usually the closest Survey Solutions equivalent of a SurveyCTO cases dataset. Each row becomes one assignment. The official documentation supports batch creation of assignments from a tab-delimited file, with optional _responsible and _quantity columns.

Step 1 — put identifying questions on the Cover page

In Designer, open the built-in Cover section and add the sample variables that should identify the household. Modern Designer has no Identifying checkbox: supported questions become identifying automatically when placed in Cover.

Identifying questions live on the Cover page. If Headquarters preloads their values, those values appear on the interviewer's assignment/dashboard and are locked: the interviewer can see them but cannot change them.

Step 2 — upload the sample as assignments

What the interviewer sees

This is why, for a household sample, the interviewer normally does not need to type or select a case ID and then run a lookup. The assignment already carries the household's identifying information.

Pattern A — sample information is authoritative: show it, do not edit it

Use this when the household ID and geography are fixed by the sampling frame and should never be changed by field staff.

Cover / Identifying:
hhid          = PH-001-0001      🔒
province      = Cavite           🔒
municipality  = Dasmariñas       🔒
barangay      = Paliparan III    🔒
sample_head   = Maria Santos     🔒
sample_addr   = Blk 4 Lot 12     🔒

The interviewer uses these values to find the correct household. No repeated questions are needed.

Pattern B — show sample information and ask the interviewer to confirm it

This is often the best pattern for your example. Keep the original sample values locked, then ask separate interviewer questions to verify that they have reached the intended household.

For example:

Identifying / locked:
sample_head

Interviewer questions:
correct_household
head_still_correct
current_head

Enable current_head when:
head_still_correct == 2

This preserves what the sample said and separately records what field staff found. That is usually analytically cleaner than overwriting the sample value.

Pattern C — let the interviewer correct the value directly

If a value truly should be editable, do not preload it as an identifying question. Instead, preload it into an interviewer-scope question using advanced preloading, or keep the original in a hidden field and collect an editable current value separately.

hidden:
sample_phone

interviewer:
phone_confirmed
current_phone

interviewer question:
phone_number

preloaded:
0917...

Identifying vs hidden vs interviewer scope

What file format does Survey Solutions actually accept?

So what should your workflow look like?

Excel example

Your working file might be:

master_sample.xlsx
Sheet: SurveySample

hhid | province | municipality | barangay | hh_head | address | interviewer

Before upload, create/export:

household_assignments.tab

hhid	province	municipality	barangay	hh_head	address	_responsible	_quantity
PH001	Cavite	Dasmarinas	Paliparan III	Maria Santos	Blk 4 Lot 12	int_ana	1

In Excel, the practical equivalent is saving a worksheet as Text (Tab delimited). If Excel gives the file a .txt extension, the content is still tab-delimited; for Survey Solutions workflows, teams commonly rename/use the expected .tab extension after confirming the content is tab-separated.

Stata example

If your sample is maintained as sample.dta, you can create the upload file from Stata rather than manually passing through Excel:

use "sample.dta", clear

keep hhid province municipality barangay hh_head address interviewer

rename interviewer _responsible
gen _quantity = 1

export delimited using "household_assignments.tab", ///
    delimiter(tab) replace

The important point is the output format: tab-delimited text. Survey Solutions' own guidance notes that statistical packages can generate these files directly. Assignment files ↗

CSV example

If the sampling team gives you sample.csv, you can open it in Excel/Stata/R/Python and export a tab-delimited version. Headquarters does not need to know that the source was CSV—the only thing it sees is the final .tab upload.

Why Survey Solutions uses .tab

The platform moved preloading, batch operations, and long lists to tab-delimited text specifically because it handles scripts and punctuation more reliably across languages. Preload files ↗

Basic sample preload: identifying data only

For a normal cross-sectional survey with a known sample, this may be all you need:

hhid	province	municipality	barangay	hh_head	address	_responsible	_quantity
PH-001-0001	Cavite	Dasmarinas	Paliparan III	Maria Santos	Blk 4 Lot 12	int_ana	1
PH-001-0002	Cavite	Dasmarinas	Paliparan III	Jose Reyes	Blk 5 Lot 8	int_ana	1

What if the sample is defined at EA/barangay level rather than household level?

Assignments can also represent a quota or area workload. For example:

province	Cavite
municipality	Dasmarinas
barangay	Paliparan III
_responsible	sup_rosa
_quantity	12

This means: collect up to 12 interviews under this assignment. Household-specific fields such as exact address and household head can be left blank and completed by interviewers. Survey Solutions explicitly supports this less-specific assignment model as well as one-assignment-per-household samples.

Advanced preloading: more than just the Cover page

Suppose this is a panel survey and you know much more from the previous wave:

• household demographics;
• member names, ages, and sex;
• plots operated last wave;
• previous phone numbers;
• baseline treatment group;
• previous-wave IDs.

Survey Solutions can preload data into questionnaire questions and rosters—not only identifying questions. Headquarters provides an advanced preload template as a ZIP containing one tab-delimited file for each hierarchical level.

preload.zip
├─ Household.tab
│    Id | hhid | province | sample_head | treatment | ...
│
├─ members.tab
│    Id | ParentId | member_name | age | sex | ...
│
└─ plots.tab
     Id | ParentId | plot_name | area | ...

Id and ParentId link lower-level records back to the household. Nested rosters can require additional parent identifiers. This is the mechanism you would use to preload last-wave household members or other repeated records.

Panel-survey example: preload last-wave members

The current interview can start with these roster rows already populated. You can then ask whether each member is still in the household, update allowed information, and add new members.

Protecting preloaded roster triggers

For panel surveys, you may want to prevent an interviewer from deleting last-wave roster members while still allowing new members to be added. Survey Solutions provides protection for preloaded trigger questions of certain types:

• numeric trigger: interviewer may increase but not reduce the value;
• text-list trigger: interviewer may append items but not remove preloaded items;
• multi-select trigger: interviewer may add selections but not remove protected preselected ones;
• yes/no multi-select: preloaded Yes/No selections can be protected.

Example protected__variables.tab

variable__name
hhmembers
n_plots
crops

Household location and GPS

If you already have target coordinates, they can be preloaded for navigation. Survey Solutions supports showing the assigned location to the interviewer from the assignment card so they can open it in an external navigation app. If coordinates are collected during the interview instead, those can be used later for verification.

Recommended pattern for your exact use case

If you receive a fixed household sample with province, municipality, barangay, household head, address and household ID, I would structure it like this:

A full example questionnaire pattern

Cover (Identifying / locked if preloaded)
├─ hhid
├─ province
├─ municipality
├─ barangay
├─ sample_head
└─ sample_address

Verification (Interviewer)
├─ correct_household
├─ head_still_correct
├─ current_head
│    enable when: head_still_correct == 2
├─ address_still_correct
└─ corrected_address
     enable when: address_still_correct == 2

Household roster
└─ members
   ├─ name
   ├─ age
   ├─ sex
   └─ ...

Why this is better than asking everything again

Common mistakes

survey!V29 · icm_part_name (calculate)
pulldata('icm_part_preloads', 'icm_part_og_name1', 'id',${caseid})
survey!V41 · pull_hh_head (calculate)
pulldata('cases_icm', 'hh_head', 'id',${caseid})
survey!V47 · calc_hh_mem_name1 (calculate)
pulldata('psps_baseline', 'calc_hh_mem_name1', 'caseid', ${caseid})
survey!V886 · fd_cat (calculate)
pulldata('preload_fd_cat', 'fd_cat_name', 'id_key', index())
survey!V895 · fd_cons (calculate)
pulldata('preload_fd_cat', 'fd_cons_name', 'cons',${fd_cons_val})

Household attributes and baseline members → assignment/roster preloading.
Static food codes and translated labels → categories and translations.
Static numeric parameters → numeric lookup table if representable.
Mutable cases/status publishing → separate operational integration.

Field workflow: HQ → Supervisor → Interviewer

Survey Solutions treats supervision as a first-class workflow instead of an optional layer around submissions.

HQ creates/imports questionnaire
        ↓
HQ creates assignments
        ↓
Supervisor distributes work
        ↓
Interviewer synchronizes
        ↓
Interviewer conducts interview
        ↓
Complete
        ↓
Supervisor review
   ↙ reject      approve ↘
Interviewer          HQ review / final workflow

Think in states, not files

A field problem may be caused by responsibility, status, assignment availability, device synchronization, or questionnaire version—not just “the form is missing.”

The interview status lifecycle

The status tells you who must act next. Dashboards may display the labels with spaces while APIs and exports may use compact names.

Official survey workflow ↗

How review should work in practice

Reassignment and absence

Responsibility and interview status answer different questions. Responsibility says who currently owns the work; status says what stage it has reached. If an interviewer becomes unavailable, reassign only after checking whether the interview exists on a device, has synchronized changes, or is already awaiting review. Coordinate a final synchronization whenever possible before moving responsibility.

Interviewer App vs Web Interviewer

This is the closest Survey Solutions analogue to the distinction between SurveyCTO Collect on Android and conducting interviews through a browser. The tablet workflow is built around synchronization; the web workflow works directly against the server.

First: interviewer accounts are not email logins

The server can create users manually or in batch. Current Survey Solutions supports creating up to 10,000 users from one tab-delimited file containing login, password, role, and—when relevant—supervisor. Official batch-user documentation ↗

Profile data are optional. Full name, email and phone help managers identify or contact the account holder, but they do not replace the login and are not automatically available as questionnaire substitutions.

Batch creation uses its own TAB template. Select the workspace, download the current user-upload template, populate it, and upload the tab-delimited file. This is different from the assignment-upload template.

How the tablet is configured

The Interviewer App needs three things the first time it connects:

1. Server address — the Survey Solutions server URL / synchronization point.
2. Interviewer login — e.g. enum001.
3. Password — the password assigned to that interviewer account.

Find the Interviewer App login QR code

The Users → enum_01 → Manage account page is the wrong screen for this QR code: it edits contact details, password and account settings. The login QR is on the workspace interviewer profile. In the PDS interface shown below:

1. Enter Default Workspace and open Reports → Devices/Interviewers.
2. Find the sup_train team and click the interviewer login, such as enum_01.
3. On the enum_01 interviewer profile, scan the QR code at the upper right from the Interviewer App’s first-login screen.
4. The scan fills the server address and interviewer login. Enter the interviewer’s password separately, sign in, then synchronize.

1. Open the workspace report. The route begins under Reports, not the administrator’s Users page.

2. Select the interviewer. Click enum_01 under the sup_train team to open the interviewer profile.

3. Scan this account QR. It belongs to enum_01 and pre-fills the server and login. It does not contain a password.

The labels differ, but both require the device to contact the server. SurveyCTO exposes separate retrieve/send controls and can automate them; Survey Solutions presents one named synchronization cycle. SurveyCTO Collect workflow ↗ SurveyCTO case refresh ↗

What synchronization actually does

Official documentation describes synchronization as a two-way exchange: the interviewer receives assignments/instruments and sends completed work back. Internet is needed for synchronization, but not for conducting ordinary interviews once the data are on the tablet. Synchronization documentation ↗

Read the tablet dashboard as four work queues

The dashboard is the interviewer's operational inbox. Each tab answers a different question, and a case can only be acted on correctly when the interviewer understands which queue it is in.

Interviewer dashboard and workload ↗

A defensible interview close-out routine

Train interviewers to use the same sequence before every submission. This reduces avoidable rejections and makes genuine exceptions easier for supervisors to interpret.

Actions that need extra care

Question-level comments ↗ · Question types and list behavior ↗ · Validation and critical checks ↗

Typical field workflow

Password behavior worth knowing

If an interviewer’s password was assigned by someone else, current Survey Solutions can require the interviewer to change it on first login. Interviewers can change their own password, but the system does not reveal existing passwords in clear text later; forgotten passwords are reset. Password documentation ↗

Tablet Interviewer vs Web Interviewer

Web Interviewer workflow

Which should you choose?

Exports, roster files, paradata and QA

This is another major mental shift from SurveyCTO: Survey Solutions exports data by level of observation. The household-level file is separate from each roster-level file, which means roster data are naturally long rather than flattened across the household record.

Which export formats are available?

Official Survey Solutions guidance explicitly recommends downloading all main-data formats when archiving a project. Data export documentation ↗

Wide vs long: Survey Solutions is hierarchical by default

household.dta

interview__id
hhid
province
hhsize
income
...

members.dta

interview__id
members__id
member_name
age
sex
...

Concrete example

Suppose your questionnaire contains:

Household
├─ hhid
├─ province
├─ hhsize
└─ members
   ├─ member_name
   ├─ age
   └─ sex

With household PH001 containing three members, the export looks conceptually like:

The household identifier appears in every level needed for merging. Survey Solutions uses stable system identifiers such as interview__id and roster-specific identifiers based on the roster variable name, such as members__id. The roster variable-name limit historically reflects Stata's variable-name length constraints. Variable names ↗

What happens to the roster source question?

The source question that created the roster is exported at the parent level:

This is why the export is not simply “all long” or “all wide.” The source question can have a wide representation at the parent level, while questions inside the roster are stored in a separate long roster file. Official roster-export anatomy ↗

SurveyCTO comparison

Nested rosters

Nested rosters create additional levels/files. For example:

Survey Solutions includes the identifiers required to link each level back to its parent. The general rule is: one export file per level of observation.

Questionnaire variable name controls the main filename

Designer distinguishes the human-readable questionnaire name from the questionnaire variable. That variable is used to name the main data file during export. For example:

Questionnaire name:
Philippines Household Remittance Survey 2026

Questionnaire variable:
ph_remit

Export:
ph_remit.dta
members.dta
transfers.dta
...

Survey Solutions introduced this so exported filenames remain stable and language-independent. Questionnaire variable ↗

System-generated QA files come with the export

Each export archive also contains system-generated data files in the same format as your main export. For a Stata export, for example, these QA files are also Stata files:

These files document operational events such as assignment creation/reassignment, interview status changes, comments, diagnostics, and validation errors. System-generated export files ↗

Paradata: a separate event-level dataset

Survey Solutions automatically produces paradata. Each row is an event rather than a respondent or roster record.

The paradata archive contains paradata.tab, a Stata import script paradata.do, a human-readable readme, and machine-readable JSON metadata. Survey Solutions also supports a reduced paradata export that omits some high-volume enable/disable/validation events. Paradata format ↗

What paradata can tell you

Useful QA patterns

If you really need a wide household file

Survey Solutions does not natively flatten roster questions into age_1 age_2 age_3 .... If a downstream deliverable requires that structure, reshape it yourself after export.

hhid  members__id  age
PH1   0            42
PH1   1            18
PH1   2            11

hhid  age_0  age_1  age_2
PH1   42     18     11

Export workflow

* Illustrative Stata workflow — adapt names to the exported metadata
use interview__actions.dta, clear
sort interview__id date
by interview__id: egen first_complete = min(cond(action=="Completed", date, .))
by interview__id: egen first_review = min(cond(inlist(action,"ApprovedBySupervisor","RejectedBySupervisor"), date, .))
gen review_hours = (first_review-first_complete)/(60*60*1000)

* Flag for review; do not automatically accuse an interviewer
gen rapid_review = review_hours < 0.25 if !missing(review_hours)

REST API: connecting Survey Solutions to other surveys and external data systems

Survey Solutions' REST API is the main bridge when you need automation that goes beyond the standard Designer → Headquarters → Interviewer workflow. This is where you can build cross-questionnaire pipelines, create assignments programmatically, automate exports, monitor interviews, and connect Survey Solutions to an external database or statistical system.

What the API is

An API, or application programming interface, is a controlled way for one computer program to ask another computer program for information or to perform an allowed action. When you use Headquarters yourself, you click buttons such as Create assignment or Export. With an API, a script sends the equivalent structured request to the server and receives a structured response that it can record and process automatically.

REST is one common style for that conversation. It combines a server address with an action word. A GET request normally asks for information, a POST request normally creates or starts something, and a PATCH request changes part of an existing resource. Data commonly travels as JSON, a structured text format made of named fields and values. The server returns a status code and usually a response body: for example, success with the new assignment ID, or an error explaining which required field was missing.

You do not need to become a software engineer to follow this module. Read each example as a workflow: who is asking → which operation is requested → what data is sent → what the server returns → what should happen next. For a gentle introduction, see MDN's overview of HTTP ↗ and MDN's REST glossary ↗. Then use the Survey Solutions API overview ↗ and your own server's Swagger page for the exact operations and fields.

Every Survey Solutions server exposes API endpoints. Current Survey Solutions provides both REST and GraphQL interfaces. The REST API can perform many of the same operational actions available in the user interface, including creating assignments, listing interviews, approving/rejecting interviews, creating users, and generating exports.

Always use the API documentation from your own Survey Solutions server. Survey Solutions explicitly warns that API syntax can change between versions. On a server, the interactive REST reference is available under its API documentation page—for example the World Bank demo server exposes Swagger at /apidocs/index.html.

API account and authentication

For system-to-system integration, the server administrator creates an API User. That account is intended for scripts/services, rather than normal interactive fieldwork.

API username
+
API password

Authorization:
Bearer YOUR_TOKEN

Usage 1 — dynamic data shared between questionnaires

Suppose you have two surveys:

• Questionnaire A: Household listing collects household ID, household head, phone number, household size, and eligibility.
• Questionnaire B: Main household interview should only be sent to eligible households and should already know the information collected in A.

In SurveyCTO you might solve this with publishing to a server dataset and then letting Form B read that dataset. Survey Solutions does not have that direct built-in cross-questionnaire lookup. The API gives you a different architecture:

Example: listing → eligible main-survey assignment

Illustrative Python workflow

The exact request/response schema should be copied from the Swagger documentation on your project server. The example below shows the overall structure of the workflow:

import requests

SERVER = "https://survey.example.org"
USER = "api_user"
PASSWORD = "********"

# Example: create one eligible household assignment
payload = {
    "Responsible": "enum001",
    "Quantity": 1,
    "QuestionnaireId": "QUESTIONNAIRE_GUID$VERSION",
    "IdentifyingData": [
        {"Variable": "hhid", "Answer": "PH001"},
        {"Variable": "hh_head", "Answer": "Maria Santos"},
        {"Variable": "phone", "Answer": "09171234567"},
        {"Variable": "hhsize", "Answer": "5"}
    ]
}

r = requests.post(
    f"{SERVER}/api/v1/assignments",
    auth=(USER, PASSWORD),
    json=payload,
    timeout=60
)

r.raise_for_status()
assignment = r.json()
print(assignment)

Can Questionnaire B receive more than just identifying data?

Yes, Survey Solutions supports preloading beyond Cover/identifying questions, including hidden/interviewer questions and roster data. For complex panel/cross-questionnaire preloading, however, the structure is more involved because roster questions need question identities and roster vectors. In many projects the easiest reliable pattern is:

The API can retrieve the questionnaire document through GET /api/v1/questionnaires/{id}/{version}/document, which is useful when an integration needs question identities and hierarchy rather than only variable names.

External dataset → Survey Solutions

The same architecture works when the source is not another Survey Solutions questionnaire:

The World Bank's own API documentation specifically describes this type of use: an external system can consume administrative databases, remote sensing, earlier surveys, or other sources and supply the selected data to Survey Solutions as assignments.

Usage 2 — sample/case data known before fieldwork: create assignments by API

Suppose your master sample is in a SQL database or a Stata/CSV pipeline rather than a .tab file. Instead of exporting a batch assignment file and uploading it manually, your system can create assignments directly.

Example sample record

{
  "hhid": "PH-001-0001",
  "province": "Cavite",
  "municipality": "Dasmarinas",
  "barangay": "Paliparan III",
  "hh_head": "Maria Santos",
  "address": "Blk 4 Lot 12",
  "interviewer": "enum001"
}

Map the external fields to Survey Solutions variables

Illustrative batch loop

for case in sample_records:

    payload = {
        "Responsible": case["interviewer"],
        "Quantity": 1,
        "QuestionnaireId": QUESTIONNAIRE_ID,
        "IdentifyingData": [
            {"Variable": "hhid", "Answer": case["hhid"]},
            {"Variable": "province", "Answer": case["province"]},
            {"Variable": "municipality", "Answer": case["municipality"]},
            {"Variable": "barangay", "Answer": case["barangay"]},
            {"Variable": "sample_head", "Answer": case["hh_head"]},
            {"Variable": "sample_address", "Answer": case["address"]}
        ]
    }

    response = requests.post(
        SERVER + "/api/v1/assignments",
        auth=(API_USER, API_PASSWORD),
        json=payload
    )

    # Save Survey Solutions assignment ID back to your master sample
    save_assignment_id(case["hhid"], response.json()["Id"])

A robust assignment automation table

In your external database, I would maintain fields like:

Why store the assignment ID?

Once an assignment exists, the API exposes endpoints such as:

Prevent duplicate assignment creation

Do not blindly rerun a script that creates assignments. Make the workflow idempotent:

1. Before creating, check your external crosswalk for an existing Survey Solutions assignment ID.
2. If needed, query GET /api/v1/assignments or an individual assignment endpoint to reconcile server state.
3. Only create when no valid assignment already exists.
4. Save the returned assignment ID immediately after successful creation.
5. Log HTTP status, timestamp, and error message for failures.

Closed-loop example: Survey A → external check → Survey B

What this does — and does not — mean for “dynamic data”

Automated export as part of the pipeline

The export API uses a job workflow:

This is useful when Survey A has many completed cases and your integration wants a batch snapshot rather than making one interview request at a time.

REST vs GraphQL

Use an existing client when it fits your workflow

The Survey Solutions API overview lists community-maintained clients for Stata as well as packages or examples for R, Python, PowerShell and .NET. The R package wraps many REST calls for survey management, exports, paradata and Shiny workflows. Stata users should review the listed Stata clients before writing raw HTTP calls. A wrapper saves syntax, but it does not remove the need to understand assignment identities, server versions, retries and reconciliation.

Guided practical — release a deployment batch with susocase

Assume your master register contains 3,200 households, but the field plan releases only batch 3 today. Each selected row has a string household ID, an interviewer username and one or more comma-separated form aliases. The project map connects each alias to the questionnaire identity and the identifying questions that receive preload values.

* Preserve leading zeros when the source is CSV
import delimited using "households.csv", clear stringcols(_all)
destring release_batch, replace

* Your familiar allocation logic remains in Stata
replace users = "enum_001" if barangay_code == "B000012"
replace users = "enum_002" if barangay_code == "B000097"

* Local preview only: no Headquarters change
susocase plan if release_batch == 3, id(id) responsible(users) ///
    forms(formids) batch("deployment_003")

* Choose one route after reviewing proposed_actions.csv and errors.csv
susocase apply, batch("deployment_003")
* OR: susocase export, batch("deployment_003")

susocase reconcile, batch("deployment_003")
susocase status, batch("deployment_003")

What to inspect before delivery

1. Confirm the selected batch count. Unselected households must produce no planned assignment.
2. Inspect creates, unchanged cases, proposed reassignments, exclusions and blockers separately.
3. Check that leading-zero IDs and raw category codes survived. A value already converted to a number cannot be reconstructed safely.
4. Confirm every form alias maps to the exact questionnaire GUID and version imported into this Headquarters.
5. For manual delivery, remember that the files are prepared, not uploaded. Supply the returned assignment IDs during reconciliation.
6. For API delivery, treat a timed-out write as unresolved. Query and reconcile before another creation attempt.

Practical architecture I recommend

                    ┌─────────────────────────┐
                    │  Master / external DB   │
                    │ hhid, sample, metadata  │
                    └────────────┬────────────┘
                                 │
                    ┌────────────▼────────────┐
                    │ Integration layer       │
                    │ Stata / Python / R      │
                    │ validation + logs       │
                    └───────┬────────┬────────┘
                            │        │
                 REST API   │        │ REST/export API
                            │        │
              ┌─────────────▼─┐    ┌─▼────────────────┐
              │ Survey A / HQ │    │ Survey B / HQ    │
              │ listing       │    │ main interview   │
              └───────────────┘    └──────────────────┘

Common API mistakes

for case in eligible_cases:
    existing = crosswalk.find(case.hhid, questionnaire_version)
    if existing:
        reconcile(existing, server_state)
        continue

    response = create_assignment(case)
    if response.success:
        crosswalk.save(case.hhid, response.assignment_id,
                       questionnaire_version, "created")
    elif response.is_transient:
        retry_with_backoff()
    else:
        log_for_review(response.status, response.body)

Build, deploy and test a household roster and education survey

Build your first working Survey Solutions form in small, testable passes. Start with a household ID and consent, add one roster, then layer in age, phones and education before uploading assignments.

Part A — Translate the specification into Survey Solutions

1. Create the questionnaire shell and cover

Create a new Designer questionnaire named Household Roster and Education Practice with questionnaire variable hh_education_practice. Open the built-in Cover section and begin with the household identifier.

Checkpoint 1 — finish and save caseid

1. Confirm that the left side of Designer says Cover. If caseid is shown in this section, it is already an identifying question.
2. Set Question type to Text, Variable name to caseid, Variable label to Household ID, and Question text to Household ID. Cover questions require a variable label because that label is used on assignment and interview cards.
3. Click the green SAVE button at the bottom of the question editor. Do not look for an Identifying control; none is needed.

Your starting screen. The three landmarks are Cover on the left, the green SAVE button at the bottom of the editor, and COMPILE beside the questionnaire title in the top toolbar. The screenshot correctly shows no Identifying checkbox.

Checkpoint 2 — compile the saved starting state

1. Click COMPILE in the top toolbar.
2. Read the result rather than closing it immediately. Confirm that Designer does not report a missing identifying question or a missing Cover variable label for caseid.
3. If an error names caseid, return to the question, confirm that it is inside Cover and that its variable label is filled, save again, and recompile.

Complete the rest of the Cover

Add the remaining sample-frame questions directly inside Cover, one at a time, so their variable names match the assignment file exactly. Each becomes identifying automatically. Save each question before adding the next.

Add interview_date as an interviewer Date question with timestamp recording at the start. Do not duplicate enumerator and supervisor names merely to recover operational metadata: Survey Solutions already tracks responsible accounts and exports workflow history. Add a questionnaire name field only when the interview text or protocol needs an explicit preloaded or independently confirmed value, and document whether that value remains valid after reassignment.

2. Consent and interview outcome

Configure consent as a single-select question so the answer can control the rest of the interview. This Designer screen shows the question type and the preloaded interviewer-name substitution in place.

Configured consent question. The question is now Categorical: Single-select, and %assigned_interviewer_name% supplies the preloaded full name. Check the Yes/No category codes below the visible part of the editor, and replace the remaining [organization] prompt with the real organization name before deployment.

Checkpoint 3 — make consent a coded Yes/No question

• Confirm the question type is Single-select categorical and that its categories are Yes = 1, No = 2. The screenshot shows the type, but the category list is below the visible area.
• Rename consent_q_01 to consent if you want to follow the expressions in this capstone exactly. If you keep consent_q_01, replace consent with that name in every later expression.
• Place all substantive sections after consent under enabling condition consent == 1.
• If consent is refused, enable an outcome question such as final_outcome and allow the interview to end correctly. Refusal is a valid outcome, not a validation failure.
• Make the consent question critical if the project requires an explicit recorded answer before submission.

Do not rely on an interviewer-name system substitution

If an older fo_name calculation fails with WB0027

This expression should be removed, not repaired with another account shortcut. The screenshot uses @user in a nested conditional expression. Survey Solutions does not expose @user or @interviewer as the logged-in username, so the variable cannot determine the current staff member this way.

1. Create the replacement field first. In Cover, add a Text question named assigned_interviewer_name, give it a clear variable label, and save it.
2. Change consent. Replace %fo_name% with %assigned_interviewer_name%, then save the consent question.
3. Remove the broken variable. Delete fo_name after nothing refers to it. Do not replace @user with @interviewer; both approaches are unsupported.
4. Compile again. For Designer testing, enter a sample name in the Cover question. For fieldwork, preload the full name through the assignment workflow explained below.

Temporary diagnostic only: if you want to prove that the String variable editor itself works before removing fo_name, replace its entire expression with "John Smith", save, and compile. That fixed string should compile, but it is not dynamic and must not be used in production.

When you are ready to upload: how interviewer names and usernames work in the assignment TAB

_responsible versus assigned_interviewer_name

These two columns have different jobs and normally contain different forms of the same person's identity:

Assignment-file column	What it must contain	What Survey Solutions does with it
_responsible	The existing Survey Solutions login username, for example jolex. Do not enter “Jolex Banda” unless that is literally the account login.	Routes the assignment to that HQ, supervisor or interviewer account. For direct interviewer assignment, use the interviewer's login.
assigned_interviewer_name	The human-readable full name to show in consent, for example Jolex Banda.	Preloads the ordinary questionnaire question with that exact text. It does not assign or route the case.
_quantity	An integer such as 1, or -1 for an unlimited assignment where appropriate.	Controls how many interviews may be created from the assignment.

Because assigned_interviewer_name is placed in Cover in this exercise, it is an identifying question and should appear in the assignment template downloaded from Headquarters. Populate it in the same assignment .tab file alongside _responsible:

caseid	assigned_interviewer_name	_responsible	_quantity
HH-001	Jolex Banda	jolex	1
HH-002	Alice Smith	asmith	1

Read the first row as: create assignment HH-001, route it to the account whose login is jolex, allow one interview, and preload the display text “Jolex Banda” into the questionnaire. The two name columns are deliberately not interchangeable. Assignment upload columns ↗

The column structure is correct, with one exception in the captured rows. Rows assigned directly to enum_01 and enum_02 correctly pair the login with Mike Johnson and Abel Kayembe. Rows 9–10 use sup_train, so “Seliano Masautso” would describe the supervisor—not a guaranteed interviewer. The revised downloadable TAB assigns those final two cases directly to the interviewers instead. Also save the file as UTF-8 so Santo Niño does not become Santo Niño.

Column order is flexible; column names are not. assigned_interviewer_name may appear before or after _responsible and _quantity. Keep the headers spelled exactly as the questionnaire and Headquarters expect.

If the column is missing from the downloaded template: save and compile the Cover question, import the updated questionnaire version into Headquarters, and download a fresh assignment .tab template for that version. Do not add the column to an older questionnaire version whose schema does not contain it.

Direct assignment versus supervisor assignment. If _responsible contains a supervisor's username, the assignment initially belongs to that supervisor—not to the interviewer named in assigned_interviewer_name. The supervisor may later give it to a different interviewer. Survey Solutions will update operational responsibility, but it will not rewrite your questionnaire field.

Preloaded does not mean live. assigned_interviewer_name records what the assignment file said. It does not automatically change when Headquarters reassigns the case, and a preloaded Cover answer is locked. Use this design only when assignments are sent directly to known interviewers and reassignment is tightly controlled. If reassignment is common, prefer a spoken self-introduction or another field protocol that cannot display a stale name.

Why a Designer lookup table cannot map hundreds of login names to full names

Do not upload usernames and names as a Designer lookup table. Survey Solutions lookup tables require a unique integer rowcode, and every other data column must also be numeric. Renaming interviewer_login to rowcode, adding a numeric ID, using LINQ, or switching from GetRow() to another lookup syntax cannot make a text column valid. Lookup-table rules ↗

Failure 1: missing key. A lookup table must have a column literally named rowcode.

Failure 2: text key. Values such as tester1 cannot be used as rowcode; the key must be an integer.

Failure 3: text data. Adding rowcode still fails because interviewer_login and full names are strings, while lookup-table content must be numeric.

Recommended scalable workflow — preload the display name with the assignment

1. Keep the questionnaire field simple. Use the Cover Text question assigned_interviewer_name described above. Do not create fo_name as a calculated variable for this workflow.
2. Build assignments outside Designer. Join each sampled case to your staff directory in Excel, R, Stata, Python, or your case-management system. Put the full name in assigned_interviewer_name and the HQ login in the special _responsible column.
3. Upload the tab-delimited assignment file in Headquarters. The column names for questionnaire data must match Designer exactly. One file can cover many interviewers when each row supplies _responsible.
4. Pipe the preloaded value into consent. Use %assigned_interviewer_name%, save, compile, and test at least one assignment for each responsible account.

caseid	assigned_interviewer_name	_responsible	_quantity
DEMO-001	John Smith	tester1	1
DEMO-002	Mike Johnson	tester2	1

Download the practice assignments TAB This embedded file contains one row per case, the matching Cover fields, _responsible, and _quantity. It is an assignment upload, not a Designer lookup table; adapt the sample only after your questionnaire fields match. Assignment upload guide ↗

Alternative — use a coded single-select question

If the project already manages a stable numeric staff code, create reusable categories such as 1 = John Smith and 2 = Mike Johnson. Bind them to a Cover single-select question named assigned_interviewer_code, preload the numeric code, and use %assigned_interviewer_code% in consent. Text substitution displays the selected option's label, not its numeric code. This avoids hundreds of C# branches, but the code-to-name category list still needs governance and the preloaded value can become stale after reassignment.

Why the proposed expression cannot work

Expression piece	Plain-language intent	Why it fails here
enumerators	Use the uploaded table named enumerators.	The file contains string data, so Designer rejects it before an expression can query it.
GetRow(@interviewer)	Find the row whose key matches the logged-in account.	A lookup key must be an integer, and @interviewer is not a supported questionnaire system variable.
?.interviewer_fn	If a row was found, read its full-name field.	A full name is text, but lookup-table data fields are numeric.
?? @interviewer	If no name was found, fall back to the login.	The fallback operator is valid C# in the right context, but it cannot repair an invalid table or supply a nonexistent system value.

enumerators.GetRow(@interviewer)?.interviewer_fn ?? @interviewer
// Conceptually understandable, but not valid for this Survey Solutions use case.

What lookup tables are for. Use them for numeric reference data, for example a numeric staff code mapped to a numeric team or region code. The documented pattern is LookupTableName[code].ColumnName, optionally guarded with LookupTableName.ContainsKey(code). In plain language: choose the table, find the integer key in rowcode, then return a numeric value from that row.

Reassignment check: _responsible controls who receives the assignment; assigned_interviewer_name is ordinary preloaded questionnaire data. Reallocating an assignment does not prove that the displayed name was refreshed. Add a reconciliation step before fieldwork or use the spoken-introduction pattern when reassignment is common.

3. Build the household member roster

Inside members, add middle_name, last_name, has_suffix, suffix, has_nickname, nickname and relation_to_head. Use the PDF for exact labels and categories. The examples below use these same names throughout; variable names are case-sensitive.

suffix enabled when:       has_suffix == 1
nickname enabled when:     has_nickname == 1

Filter and validate relationship to the household head

Because the list question instructs the interviewer to enter the household head first, code 1 (Head) should be the only relationship available in row 0, and it should be unavailable in every later row. Put this expression in the Filter field of relation_to_head:

(@rowindex == 0 && @optioncode == 1) ||
(@rowindex > 0 && @optioncode != 1)

Designer evaluates the filter once for each candidate category. @optioncode is that candidate's code, while @rowindex identifies the current roster position. The result is: row 0 sees only Head; rows 1 onward see every permitted relationship except Head.

If you retain a validation condition on relation_to_head, it must accept both the valid first-row case and the valid later-row case:

(@rowindex == 0 && self == 1) ||
(@rowindex > 0 && self != 1)

Use an error message such as: The first listed member must be the household head, and later members cannot be coded as head. The earlier expression @rowindex == 0 && self == 1 by itself is incorrect because it evaluates to false for every row after the first. The matching validation above is a defensive check; the filter already prevents the interviewer from selecting the disallowed categories.

Filter and validation serve different purposes. The filter shown is correct: it controls which relationship categories are offered by row. Replace the validation visible in the screenshot with the two-branch expression above so later rows are valid too.

Why there is no roster-level validation box

You are not overlooking a hidden control. Survey Solutions rosters support an enabling condition but do not have validation conditions. Validation rules can be attached to questions and static text, while a critical rule can be defined for the questionnaire as a whole. Roster properties ↗

The roster panel is complete. The absence of an Add validation condition control is expected. The source list already determines whether rows exist, so member_fnames.Length >= 1 is an optional display guard rather than a data-quality validation.

Put household-wide roster checks on members_confirm

Place the aggregate checks on a simple Yes/No confirmation question members_confirm after the roster, where the whole members collection is in scope. For a first pass, its text can simply ask the interviewer to confirm the listed members; add the generated full-name sentence in the optional second pass below. Add these as two separate validation conditions so each failure has a precise message:

These rules are evaluated when members_confirm has an answer. Keep that question outside the roster and after all relationship questions. If these conditions must prevent interview completion—not merely flag invalid confirmation—also create an equivalent questionnaire-level critical rule:

members.Count(p => p.relation_to_head == 1) == 1 &&
members.Count(p => p.relation_to_head == 2) <= 1

Once the list, roster and relationship checks work with two members, continue to age and education. The name calculations below are a useful second pass when you want to display polished full names in the interview.

Second pass: calculate the head's full name and join every roster member's name

Create one household-level head_name

Placement matters. In the supplied screen, head_name is indented inside the roster, so Survey Solutions would calculate one value for every roster row. Drag it out only if Designer shows an unambiguous parent-level drop target; otherwise select it and use MOVE TO to place it in the parent household section, immediately after the roster.

The list question stores objects with a numeric Value and text Text. The roster is an ordered collection. Therefore the first name entered in the list is member_fnames.First().Text, while the first roster record is members[0]. In your build, the first listed person is defined as the household head.

If the suffix is a Text question

Set head_name to type String and use this expression outside the roster:

members.Any()
? String.Join(" ", new[] {
    member_fnames.First().Text,
    members[0].middle_name,
    members[0].last_name,
    members[0].suffix_text
  }.Where(x => !String.IsNullOrWhiteSpace(x)))
: null

This means: if the roster has at least one person, take the first listed first name and the first roster row's middle name, last name, and suffix; discard blank pieces; then join the remaining pieces with one space. If the roster is empty, return no value.

If suffix is categorical, as in the supplied screen

A single-select answer is a nullable integer in expressions, not its displayed label. Create a String variable named suffix_text inside the roster and map your questionnaire's actual category codes to their text. The following is a template—replace the example codes and labels with the values shown in your suffix question:

suffix == 1 ? "Jr." :
suffix == 2 ? "Sr." :
suffix == 3 ? "II" :
suffix == 4 ? "III" :
suffix == -666 ? suffix_oth :
null

Then use the household-level head_name expression above. The practice questionnaire uses -666 for “Other”; if your own category code differs, change it. Do not concatenate members[0].suffix directly or the result will contain the numeric category code rather than “Jr.” or “III.”

Keep your names consistent. The expressions here use member_fnames for the source list and members for the roster, matching the supplied Designer screenshots. If your own questionnaire uses different variable names, substitute them everywhere before compiling. Survey Solutions data types ↗

Head-name test: compile, then test four cases: first + last only; first + middle + last; first + last + suffix; and all four parts. Confirm there are no doubled spaces and that changing the first list item or the first row's name fields immediately recalculates head_name. Also confirm that a second member does not replace the head.

Worked example: build and display a list of every member's full name

This task has two calculations at different levels. First, build one clean full_name inside every members roster row. Second, place full_names_joined outside the roster and join all those row-level values into one household-level sentence. Keeping those two jobs separate makes the logic easier to compile, test and reuse.

Step 1 — build one full_name inside the roster

1. Right-click the members roster and choose Add variable, or use the section controls and then confirm that the new variable is indented inside the roster.
2. Set Variable type to String and Variable name to full_name.
3. Enter the expression below, save, and compile.

String.Join(" ", new[] {
    member_fnames
        .Where(x => x.Value == @rowcode)
        .Select(x => x.Text)
        .FirstOrDefault(),
    middle_name,
    last_name,
    suffix_text
}.Where(x => !String.IsNullOrWhiteSpace(x)))

Expression piece	Meaning in plain language
x.Value == @rowcode	Find the item in the source list whose identity matches the current roster row.
.Select(x => x.Text).FirstOrDefault()	Take that list item's displayed first name. If no matching item exists, return no first name instead of crashing the calculation.
new[] { ... }	Place the first, middle, last and suffix text into a temporary ordered set of name parts.
Where(...IsNullOrWhiteSpace...)	Discard missing or blank parts, so an absent middle name or suffix does not create doubled spaces.
String.Join(" ", ...)	Combine the remaining parts with one space between them.

Do not use @rowname. Modern Designer reports WB0276 because that variable is no longer supported. For a list-driven roster, match the supported current-row identifier @rowcode to the source list's numeric Value, then read its Text. Also use suffix_text, not the categorical suffix code, when the output should show “Jr.” or “III.” Compilation message WB0276 ↗

One result per roster row. The indentation on the left shows that full_name is inside members. The expression on the right removes blank name parts before joining them with spaces.

Step 2 — join all roster-row names outside the roster

1. Add a String variable named full_names_joined in the parent household section, after the roster. It must not be indented as a child of members.
2. Use the expression below. It reads the full_name calculated for each roster row, removes any empty result, and joins the names with a comma and a space.

String.Join(", ",
    members
        .Where(p => !String.IsNullOrWhiteSpace(p.full_name))
        .Select(p => p.full_name))

One result for the household. Here p means one roster row at a time. Where keeps rows with a usable name, Select takes each row's full_name, and String.Join produces one display string such as John Banda, Mary Phiri Jr., Peter Mwale.

Step 3 — substitute the joined result into the confirmation question

Create or edit the categorical confirmation question members_confirm outside the roster. Insert %full_names_joined% wherever the generated list should appear:

Thanks for providing me the names. Please confirm that the following
members live together, eat together, and are current residents—that is,
members who are here now or traveling for less than three months:
<b>%full_names_joined%</b>.

Display the completed list. Percent signs perform text substitution; the HTML <b>...</b> makes the generated names bold. The captured build compiles with 0 errors. Its six warnings still need to be opened and reviewed separately; zero errors does not mean warnings can be ignored.

The same pattern works for other roster items. Replace p.full_name with the row value you want to display—for example p.school_name or p.crop_name—while keeping the sequence Where → Select → String.Join. Change the first argument from ", " to another tested separator such as "; " when semicolons are easier to read.

Roster-list test: test one member; several members; a blank middle name; a blank suffix; an “Other” suffix; and a corrected or deleted list item. Confirm that every name contains only the expected spaces, that names appear once and in roster order, that the confirmation text refreshes, and that compilation has no WB0276 or other errors.

4. Demographics and age

Add gender, dob_known, dob, age_value, age_unit, calculated variable age_years, marital_status, and first_union_age inside the roster. A single Date question cannot store partial dates and special numeric missing codes cleanly, so explicitly ask whether the full date is known and use the age fallback when it is not.

Offer “Don't Know” and “Refuse” as numeric special values

For age_value, choose Numeric, check Integer, and use ADD SPECIAL VALUE to add -999 = Don't Know and -888 = Refuse to answer. These appear as selectable answers alongside ordinary numeric entry; the interviewer does not have to type the codes. Leave Non-negative unchecked when using these negative codes—otherwise Designer reports WB0324.

Age question in Designer. The two special values are entered under Value and Title. Their negative codes are deliberate and distinct from valid ages.

Validate the numeric question age_value first. This accepts the two special codes or an ordinary age from 0 to 110:

self == -999 || self == -888 || self.InRange(0,110)

For ordinary ages, enable the categorical age_unit question. If it uses 1 = days, 2 = months and 3 = years, put this second validation on age_unit to apply the narrower day and month limits:

(self == 1 && age_value.InRange(0,29)) ||
(self == 2 && age_value.InRange(0,11)) ||
(self == 3 && age_value.InRange(0,110))

Make age_unit critical when enabled. Use an error message such as The age does not fit the selected unit. Change the unit codes and limits if your protocol differs. Keeping the first rule on age_value independent of age_unit avoids a circular dependency.

dob enabled when:              dob_known == 1
age_value enabled when:        dob_known != 1
age_unit enabled when:         dob_known != 1 && age_value >= 0
marital_status enabled when:   age_years > 13
first_union_age enabled when:  marital_status >= 1 && marital_status <= 5

Use a nullable Long Integer calculated variable for age_years. With interview_date captured earlier, calculate completed years rather than dividing days by 365.25. The fallback below returns no age in years for a special value or unanswered age, zero for a valid age given in days or months, and the entered value for years:

dob.HasValue && interview_date.HasValue
? (long?)(interview_date.Value.Year - dob.Value.Year
  - (interview_date.Value.Date < dob.Value.Date.AddYears(
       interview_date.Value.Year - dob.Value.Year) ? 1 : 0))
: (!age_value.HasValue || age_value == -999 || age_value == -888
   ? (long?)null
   : (age_unit == 3 ? age_value
      : (age_unit == 1 || age_unit == 2 ? (long?)0 : null)))

Compile this expression in the selected Designer version and test it on the day before, the day of and the day after a birthday, as well as on leap day and for infants. Also select each special value in the Tester and confirm that age_years stays blank and age-gated questions do not appear.

5. Phone selection and member-level phone details

Create phone_status first so None, Don't know and Refuse remain explicit outcomes. When a household has phone owners, add a linked multi-select phone_owners sourced from members and limit it to three selections.

Inside members, add phone number, network, phone type, another-SIM indicator and second number. A linked multi-select stores roster identities rather than ordinary category codes. In the member roster, test whether the current row code occurs in that identity vector:

phone_owners enabled when:       phone_status == 1
Phone details subsection when:  phone_owners.Any(p => p[0] == @rowcode)
second_phone enabled when:       has_second_phone == 1

phone text validation:
Regex.IsMatch(self, @"^(0[0-9]{10}|-999|-888)$")

The vector shape depends on roster depth. The expression above is for this one-level roster; compile it in Designer and confirm it for selected and unselected members before deployment.

6. Education inside the member roster

Create an Education subsection inside members and enable the whole subsection with age_years >= 5. Keeping education in the existing roster avoids asking the interviewer to recreate or manually select the same eligible members.

Finish with open text end_comments, closing static text, variable labels, and at least one critical check for required operational fields. Compile until Designer reports zero errors, then test each branch before import.

Part B — Upload the sample and run the PDS test

Return to the expandable assignment-name note in Step 2 if you need to check the difference between _responsible (the account login) and assigned_interviewer_name (the full name displayed in consent).

1. Import the compiled questionnaire to the PDS as Version 1 using the Designer credentials that own or can view it.
2. Download the embedded Survey Solutions assignments TAB. Its headers match the cover variables and it contains _responsible and _quantity.
3. In Headquarters, open Survey Setup → Questionnaires. Move the mouse pointer over the imported questionnaire row so it highlights, then click the questionnaire title or row. This opens its action menu; choose Upload assignments.
4. Do not proceed if verification reports a mismatch. Check variable spelling, question types, UTF-8 text and whether every uploaded field is an identifying question.
5. After “Verification Complete,” create the assignments. The TAB sends five cases directly to enum_01 and five directly to enum_02; the matching display names are preloaded in the same rows.
6. As sup_train, verify that both interviewers received the expected cases. Do not reassign these consent-name practice cases unless you also have an approved way to keep the preloaded display name consistent.
7. On Android, configure the Interviewer App with the PDS URL and enum_01, then synchronize. In a browser, sign in as enum_02 and open Web Interviewer.

Not here. The general Assignments page lists and filters existing assignments and exposes NEW ASSIGNMENT, but it does not show the questionnaire-specific batch-upload command.

Use this hidden action menu. Return to Questionnaires, hover over the imported questionnaire row and click it. The menu opens above the row; choose Upload assignments.

Confirm the target questionnaire and version. The default responsible is used only for rows whose batch file does not provide _responsible.

Choose the correct upload mode. For this capstone's Cover and interview-level assignment file, use UPLOAD .TAB FILE under Identifying data only. The ZIP option is for multi-level preloading, including subordinate rosters.

When an assignment column cannot be matched: PL0003

The upload below stopped before creating any assignments. HQ reported PL0003: Column cannot be mapped to any question in the questionnaire and identified barangay as the unmatched header. This means the questionnaire version shown on the upload screen has no matching question at the level expected by this file. In this case, a Cover question's variable name was misspelled; the same error can occur when a spreadsheet contains a column that was never added to the questionnaire.

Read both the code and the named column. PL0003 points to the header barangay, not to a value in a particular household row. The message No assignments were created means the file can be corrected and submitted again without duplicating this failed batch.

1. Compare the exact headers. Download the assignment .tab template for the same imported questionnaire version. Compare its first row with the first row of your upload, especially barangay. Check spelling, underscores, capitalization, and accidental spaces. Check the question's variable name in Designer, not its question text or variable label.
2. If the Cover variable name is wrong: correct it in Designer, save and compile the questionnaire, then import the revised questionnaire into Headquarters. Download a fresh assignment template for that new version and upload to that version. Editing Designer alone does not change an already imported Version 1.
3. If the TAB contains an unwanted extra column: remove that column from the upload file and save it as tab-delimited UTF-8 text. Keep the intended Cover fields and any valid special columns such as _responsible and _quantity.
4. Retry verification. Confirm that Headquarters reports verification complete before creating the assignments. If another header is named, resolve that mismatch in the same way.

Batch assignment upload ↗

Required test scenarios

Required review cycle and evidence

Reference basis: official Survey Solutions documentation current through 2026 for Designer components, variable names, assignments, user roles, web interviewing, synchronization and exports.