First, know what you are operating

SurveyCTO is not just a form editor. It has a server that holds form versions, users, incoming interviews, and exports; SurveyCTO Collect, the phone or tablet app used by many field teams; and SurveyCTO Desktop, a computer application for synchronizing and exporting data. A respondent can also complete an enabled web form in a browser. You do not need all of these components for every study, but you must know which one holds the form, which one holds an unfinished interview, and when data actually reach the server.

Read the whole workflow before opening a menu

1. DesignWrite the questions and answer rules in the online designer or a SurveyCTO XLSForm. Preview a draft with fake answers. Evidence: the intended question and options appear in Test.
2. DeploySave and deploy a tested form to the practice server. This is the version collectors can use. Evidence: the deployed form appears under Design with the intended form ID and version.
3. DownloadOn a phone or tablet, sign in to the right server and use Get Blank Form. An enabled web form instead opens from Collect. Evidence: the form is available to fill on that device or browser.
4. CollectFill the form, check answers, and finalize it. Work may happen without mobile Internet. Evidence: the interview is saved or finalized locally; this alone does not confirm server receipt.
5. SendWhen connected, use Send Finalized Form in Collect (or submit the web form). Evidence: a successful send and the corresponding submission visible on the server.
6. Review and exportUse Monitor to inspect incoming interviews and Export to download a CSV or another supported analysis format. Evidence: the expected test ID and answers appear in the exported file.

The image loops back to Design because field testing often reveals a wording or logic change. A revised form has to be tested, deployed, and received by devices again. Do not mistake “I edited the draft” for “everyone now has the update.”

Set up a safe practice space

1. Choose a server you may use. Use an approved training server or your own trial account. Record its server name/address in your private notes; never put credentials in a workbook or share them in the course. Do not experiment on a live project server.
2. Confirm your role. A designer or administrator can create and deploy forms. A data-collection account can fill permitted forms. Review and export access may be restricted. If a control below is missing, ask the server owner which role you have; do not try to bypass permissions.
3. Use synthetic data. The practice files use invented IDs such as HH001. Do not upload a real sample list, respondent name, production API key, or confidential questionnaire to a trial server.
4. Pick one collection route. For the quickest first run, use web data collection if it is enabled for your practice server. For the field route, install SurveyCTO Collect on a test device and configure it with the practice server name and a permitted collector account.
5. Keep one test log. Note form ID, version, test ID, route (web or device), expected answer, actual answer, and whether the server received it. This becomes your evidence when something fails.

Find your way around the console

Sign in to the practice server and locate these five areas. Menu labels can vary slightly by permissions and interface version, so match the purpose rather than guessing from position alone.

The server connects these areas; the tabs are not separate databases. SurveyCTO's more advanced server datasets can provide preloaded values, current records, and case lists. They are not required for this first test. A CSV is a file you can upload or export; a server dataset is a managed object that can be downloaded as a CSV. Module 12 starts the connected-data pathway.

Make one complete trip with a tiny form

These steps deliberately use the online designer so a first-time learner can see the complete cycle before studying the spreadsheet source in Module 2. Use a unique practice ID such as first_trip_yourinitials; do not reuse an ID already on the server.

1. Design: In Design → Your forms and datasets, choose + → Start new form. Give it the visible title “My first practice form” and a stable, space-free form ID. Choose Edit online. Add a Text field with the question “What is your practice code?” and field name practice_code. Save the field.
2. Test: Switch the designer to Test. Enter HH001. Confirm the label and input work. If the question is missing, return to Design and check the saved field; a successful editor load alone is not a test.
3. Deploy: Use Save and deploy, then return to the server's Design area. Note the form ID and deployed version. Testing a draft and deploying it are separate actions.
4. Collect by web, if enabled: In Collect, open Fill out for this form. Enter HH001, mark the form finalized, and submit it. If web collection is off or unavailable to your role, use the device route instead.
5. Collect by device, alternative route: In SurveyCTO Collect, configure the practice server and collector credentials. Choose Get Blank Form, select this form, then Fill Blank Form. Enter HH001 and finalize. When connected, choose Send Finalized Form. Saving locally without sending is not the final step.
6. Verify receipt: In Monitor, refresh the form's submission count and inspect the new submission. Match the practice code and submission time. If there is no record, first check whether you used the correct server, deployed form, account, and send/submit step.
7. Export: In Export, choose the same form and download its data as CSV. Open the file and locate the practice_code column with HH001. Keep the export with your test log. The export is a snapshot, not an automatically updating link to later interviews.

Five words that must not blur together

Later, the course adds server datasets, which maintain rows that can be preloaded into forms or updated from submissions, and cases datasets, which drive a collector's case list. A form ID names the questionnaire; a household ID such as HH003 names the household; a submission KEY names one particular interview. Those IDs may appear together but are not interchangeable. Module 14 returns to dataset keys, and Module 19 to case IDs.

Start from the maintained template

A SurveyCTO XLSForm is an Excel workbook with multiple worksheets, not a CSV. The official template includes survey, choices, and settings plus help and audit material. Copy it for a new form. Do not rebuild the three sheets from an empty workbook; that discards useful guidance and may change defaults. When editing an existing form, start from its maintained source and preserve its form ID, variable names, and version history unless a documented change requires otherwise.

Follow a question through the workbook

survey:  type=select_one yesno   name=consent   label=May we continue?
choices: list_name=yesno value=yes label=Yes
choices: list_name=yesno value=no  label=No
settings: form_id=hh_listing_training

The word after select_one must match choices.list_name. The submitted value is yes or no, not the English label. Logic such as ${consent} = 'yes' compares the stored code. The name becomes a data column, so choose it carefully and keep it stable across a live form's versions.

SurveyCTO differs from other XLSForm platforms in small but important ways. Use relevance for skip logic and value for a choice code. Use the exact headers constraint message and required message with spaces. These are not interchangeable with another platform's column names.

Version the source as well as the server

Keep one maintained workbook for each form. Before a change, copy it to a dated or versioned working file, record the purpose of the change, and preserve the prior deployed version. A different filename does not itself create a new form: the form ID in settings is the stable identity. An accidental form-ID change can break case rows, attachments, publishing links, and device update expectations.

Choose a type from the answer

A variable that looks numeric may still be an identifier. HH003 is text. A phone number is text because leading zeros, a plus sign, and formatting matter; no arithmetic should be performed on it. A count of people is an integer. An area in hectares may be a decimal. A single status is select_one; several facilities are select_multiple. A note gives guidance without collecting an answer. A calculate stores a derived value without asking the user.

Keep labels and codes separate

Write the wording that the collector or respondent sees in label. Write short, stable machine values in choices.value. A translated form can show another language while preserving the same stored code. A changed label is a documentation and translation task; a changed code can break comparisons, publishing filters, and analysis across versions.

Make the question actionable. “Household size?” leaves uncertainty about visitors and absent members. “How many people usually live in this household?” followed by a project-approved definition gives a consistent count. Use hint for a brief field instruction, and a constraint message that says how to correct an invalid answer. Avoid forcing an answer when the respondent may not know it; choose a missingness policy and code it deliberately.

Design for analysis before programming

For every field in the practice instrument, make a one-line specification with question name, type, label, allowed values, missingness rule, and intended use. This prevents a later calculation from assuming an input is always available when the questionnaire allows it to be skipped. A field for phone number might be optional, while hhid should be required and checked against the sample or case list.

Run a test that can fail

Preview is a draft-form test. It is useful only when you enter cases that challenge the logic. For the listing form, test consent No; consent Yes with one member; age 17 and 18; a blank required ID; invalid age 121; and a change from Yes to No after answering follow-ups. Record both expected and observed behavior. A form that opens successfully has passed only a load test.

Deploy, then test the full path

1. Save the maintained XLSForm and upload it as a draft. Read any validation message and correct the named row or expression.
2. Preview the test matrix. Keep a record of the workbook version and date.
3. Deploy the practice form only after the critical paths pass.
4. Open the deployed form through the method collectors will use. Submit one synthetic record.
5. Find that record in the server's submission list and inspect its exported values. If a publishing link exists, verify the dataset row separately.

The first live record tests access, device or browser delivery, finalization, sending, server receipt, and export. It does not prove every questionnaire branch works; that is why the earlier matrix remains necessary.

Protect existing records during updates

Once collection starts, a change to a field name or stored choice value changes the meaning of old and new data. A new required field can make editing an older submission difficult. A changed relevance rule can alter what an edited record retains. Test an update on a copy with synthetic submissions before updating a live project. Tell field devices how to receive the new form. Keep old source versions and a release note.

Three rules answer three different questions

These rules do not replace each other. An optional age with a range constraint can still be blank. A required field hidden by relevance should not block a refusal path. A field may be visible and valid but still not have the meaning your question intended; wording and training matter too.

Write and test a consent branch

Write the rule in words first: “Ask the roster only if consent is Yes.” Then write it as ${consent} = 'yes' in the relevance column on the begin group row. The group rule applies to the member questions within it. Use a stored choice value, not the visible label. If you have a refusal follow-up, put it outside the group and give it the opposite relevance.

type               name           label                   relevance
select_one yesno   consent        May we continue?
begin group        interview      Household interview     ${consent} = 'yes'
integer            hh_size        Usual residents
end group          interview
text               refusal_note   Reason, if offered      ${consent} = 'no'

Preview three paths: consent unanswered; Yes; No. Then choose Yes, enter a value, return to consent and change to No. Inspect what the final record stores, not only what disappears from view.

Test a hard range and a multiple-choice condition

For a member age use . >= 0 and . <= 120 with a message such as “Enter an age from 0 to 120, or follow the missing-age procedure.” Test −1, 0, 120, and 121. A constraint is a hard stop; if unusual but possible ages need supervisor review, design that as a separate soft-check process rather than widening or disabling the hard rule without thought.

For select_multiple facilities, the answer may hold several codes such as water toilet. To show an Other text box use selected(${facilities}, 'other'). A direct equality test against 'other' will fail for a combined answer. Test Other alone and Other with another selection, then remove Other and see whether a stale explanation remains in the saved result.

A calculate field stores an answer nobody types

A calculate row has a name and an expression in calculation. It is hidden from the collector but appears in submitted data. Use it to create a derived value that has a defined meaning, such as is_adult, adult_count, or eligible_for_followup. Do not add a calculated field only because a formula can be written. Specify its inputs, output type, possible blank value, when it should change, and who will use it.

type        name         calculation
calculate   is_adult     if(${member_age} >= 18, 1, 0)
calculate   visit_flag   if(${visit_outcome} = 'complete', 1, 0)

These values can drive relevance, checks, publishing filters, or analysis. The displayed label on visit_outcome can change; the stored code complete must remain consistent with the expression.

Track dependencies and recalculation

Suppose a collector enters age 17, then corrects it to 18. A regular calculate field depending on age recalculates, changing is_adult from 0 to 1. Any later total that depends on is_adult must also update. Build a dependency chain on paper before programming:

A test that enters only the final value misses stale-calculation bugs. Test the correction. Also test whether a field becomes irrelevant: a calculation placed inside an irrelevant group may be blank rather than 0. Those states must have distinct interpretations.

Choose calculate_here rarely and deliberately

SurveyCTO's regular calculate fields recalculate as needed when forms load, save, or dependencies change. calculate_here runs when the user reaches that location in the form. It fits a checkpoint such as “time first reached the consent screen,” but is usually the wrong tool for a count that should react to edits. A one-time timestamp can use once(format-date-time(now(), '%Y-%b-%e %H:%M:%S')) in a calculate_here row. Test leaving and returning to the screen and editing a saved record.

Specify the output before writing the expression

For each calculated field, write five lines in the source review: what it represents, its unit or type, which fields it reads, when it may be blank, and what changes it. For adult_count, the unit is people, the value is a nonnegative integer, and it reads all member ages in one household submission. Its value should change when an age or roster row changes. For rand_draw, the value is a number in [0,1), drawn once for a submission and intentionally stable after edits. Those two fields need different recalculation behavior even though both use calculate.

A calculation's placement also matters. A row inside a repeat runs in that repeat's context. A row outside a conditional group may still compute when the group is hidden unless its own relevance or expression handles that case. Test the stored value after a branch change.

Write a calculation contract before the expression

Consider a field called adult_count. “Count adults” is not enough to program it safely. State whether an adult is a member aged at least 18 at the listing interview, whether a missing age counts as younger than 18 or remains unknown, and whether a deleted roster row should disappear from the total. Then specify the result type as a whole number and the consumers as the follow-up rule and export. This short contract prevents a formula from quietly making a study decision.

Write the expected result before previewing. Otherwise the observed result tends to become the assumed rule.

Separate a display calculation from a stored decision

A note can show a collector a calculated total, but the workflow also needs a stable field name in exports and publishing. Store the total in adult_count, then display it with a reference in a note. The field name belongs in the data dictionary. The note's wording can change without changing the data contract. If the total controls follow-up eligibility, add a second named field, such as followup_eligible, whose expression applies the full rule. That makes the count and the decision separately inspectable.

Trace the chain after each edit: age → adult flag → count → eligibility → relevance or publishing filter. When the final visible screen looks correct, inspect stored values too. A hidden field can be wrong while the collector sees no warning.

Define what blank means before calculating

A count of zero means the respondent reported none. A blank may mean not asked, refused, unknown, or not yet entered. These values should not be combined without a rule. If a calculation turns blank into zero, the downstream dataset may make an incomplete interview look like a true zero. If a calculate field drives a publishing filter, that difference can change whether a row is published at all.

Guard calculations at their inputs

Use empty(${field}) to test whether a field has no value. For a rate, check that the denominator is present and greater than zero before division. SurveyCTO uses div for numeric division. A teaching expression is if(${hh_size} > 0 and not(empty(${adult_count})), ${adult_count} div ${hh_size}, ''). Compile and test it on your server version, including an unanswered numerator, a zero denominator, and an edited denominator. For a production study, decide whether a blank result is allowed or whether the form should stop earlier with a required answer or a constraint.

Do not rely on type conversion by accident. If a source field is text because it preserves an ID, keep it text. If arithmetic is intended, use a numeric input or a documented conversion and test nonnumeric text. If a calculated value will publish into a dataset, confirm the dataset column's expected type and what blank does to an existing row.

Make a test table part of the form specification

A calculation is not complete when the formula compiles. The form specification should show test inputs, expected output, and why. For adult_count, use a three-person household with ages 17, 18, and 65; the expected count is 2. Correct age 18 to 16; expected count becomes 1. Remove the third member; expected count stays 1. Then change consent to No and inspect whether the derived count is blank or zero. That last result depends on where the calculate field sits and how relevance is applied.

Try the missing-value decision

The small model below represents the rule “calculate adults divided by household size only when both values are present and the size is greater than zero.” Clear an input to represent missing data; enter zero to represent an observed zero. The model runs in this course file and does not submit data.

After testing, explain whether the form should allow adult_count > hh_size. A calculation guard avoids division errors; a separate constraint or supervisor check addresses contradictory answers.

Three different meanings of zero

For a ratio such as adults divided by listed members, zero can mean “no adults,” “no members,” or “the denominator was never collected.” Only the first is a valid numeric share. The expression must therefore check denominator presence and value before division. Decide whether the output for the other cases is blank, a separate status code, or a validation error; do not silently return zero for all three.

The denominator check is part of the measure's definition, not merely a way to avoid an error message. Use a separate text or select-one status if analysts need to distinguish zero denominator from missing source answers.

Check type conversion at the boundary

Survey form values can be blank, text, integer, decimal, or a choice code. A label such as “Yes” is not the stored choice value. Before applying arithmetic, inspect the field type and the code that will actually appear in a submission. If a preload CSV stores adult_count as text, verify that the intended conversion yields a number and decide what happens when the cell is blank or contains an unexpected word. A formula that works for the clean training row may fail for the first malformed update.

In a test export, compare input columns with every calculated output. Do this for one normal case, one boundary case, one blank input, and one corrected input. Record the workbook version with the results so the test can be rerun after a change.

Choose the definition of age first

“Age” may mean reported completed years, years since a recorded birth date on the interview day, or years at a fixed eligibility date. These are different measures. A rough expression such as int((today() - ${dob}) div 365.25) can be useful for an approximate age, but near a birthday it may not match an exact completed-years rule. For a study boundary at 18, specify whether to ask age directly, verify a date of birth, or calculate against a fixed reference date. Test the day before, on, and after the birthday.

If eligibility must remain tied to a baseline assessment, publish or preload that baseline result. Do not let today() silently change an earlier decision when a form is reopened months later.

Distinguish live time from captured time

today() and now() are dynamic. duration() measures total time spent filling or editing a submission. A regular calculation using a dynamic value may change as the form is edited. If the task is “record the first time the collector reached this section,” use calculate_here with an outer once() around a formatted time expression. Keep that field's meaning in its name, such as first_reached_followup_at.

type             name                         calculation
calculate_here   first_reached_followup_at    once(format-date-time(now(), '%Y-%b-%e %H:%M:%S'))

Test the device clock and time zone assumptions. Record whether the value is intended as an audit signal or an eligibility input. Audit fields should not be presented as a substitute for server receipt time.

Use time fields in a testable sequence

For a callback, the form may store a scheduled date. A calculate field could flag whether it is in the past, but that flag should update if the scheduled date changes. A one-time timestamp should stay fixed. Put both cases in a test table and edit the source date after initial entry. If the rule's intended behavior differs from what you observe, change the field type or expression rather than accepting the mismatch.

Do not let device time stand in for study time

For a household eligibility rule, the relevant date might be interview day, baseline date, or a fixed study cutoff. A device's today() answers only what that device currently considers today. If a collector's clock is wrong or an interview is reopened after the cutoff, the result may change. Write the reference date into the form or preload it from an approved source when the rule must be fixed. Store both the source date and the derived eligibility flag so an analyst can reproduce the decision.

Use a test with a person born exactly 18 years before the cutoff, one day before that date, and one day after. Repeat after changing the device date in a controlled training setting or by substituting a fixed reference-date input. If the result is used for case routing, check that the published flag and case list match the form's displayed decision.

Separate the draw from the assignment

A random assignment needs a stored draw and a rule that maps it to a group. Put once(random()) alone in a calculate field called rand_draw. Then use another calculate field for if(${rand_draw} < 0.5, 'A', 'B'). A draw below 0.5 maps to A; a draw from 0.5 up to but not including 1 maps to B. The threshold is a design decision, not proof that a small pilot will contain exactly half in each group.

type        name          calculation
calculate   rand_draw     once(random())
calculate   assignment    if(${rand_draw} < 0.5, 'A', 'B')

SurveyCTO warns against putting random() directly in relevance or nesting once(random()) inside another expression. A new draw could occur when a form is edited. Use the stored draw in later expressions, constraints, and publishing fields.

Test stability, not just balance

1. Complete a synthetic interview and record the stored draw and group.
2. Move backward and change an unrelated answer. Check the draw and group again.
3. Save, reopen, edit, and check again.
4. Create a different new interview. It should have its own draw; do not expect a particular group.

If the study has stratification, quotas, or central assignment, this simple threshold may not be the design. A server dataset can hold authoritative assignments, or a different randomization workflow can be used. The form must implement the approved assignment method and record enough information to audit it.

Audit an assignment as a stored decision

In a training export, keep rand_draw, assignment, form version, and submission KEY together. Recalculate the expected group from the draw in a separate worksheet or script and compare it with the stored assignment. A mismatch might indicate an expression change, a threshold error, or an edit that recomputed one field but not the other. Do not judge a small sample by whether its A/B counts are exactly equal; check the rule for each record.

If a design needs a centrally controlled assignment, a form-local random draw may be inappropriate. A server dataset can hold an approved assignment by household ID; the form preloads it and stores the ID and assignment used. That changes the workflow: missing IDs and stale attachments must be tested before fieldwork. Choose the approach from the study protocol, then document it in the form specification.

A repeat creates many records within one submission

Use a begin repeat and end repeat pair for a roster. Each instance describes one member. A fixed repeat_count can come from household size; alternatively, the collector can add members manually. Decide which is safer for the study. If the count is later reduced, test how the device handles already-entered member rows. Keep a stable person identifier if the same person must be found across later forms; the current row position alone may change.

type            name          label                       repeat_count
integer         hh_size       Usual residents
begin repeat    members       Household member            ${hh_size}
text            member_name   Member name
integer         member_age    Age in completed years
calculate       member_order                              index()
end repeat      members

index() gives the current repeat position. It is useful for a roster slot, but not a durable person ID if rows can be reordered or removed.

Aggregate across all instances

Outside the repeat, count(${members}) returns the number of repeat instances. count-if(${members}, ${member_age} >= 18) counts adults. sum(${member_income}) totals a numeric field in the repeat. SurveyCTO also has conditional aggregate functions such as sum-if(). Use the function that matches the intended unit. A single ${member_age} reference outside a repeat is not a household summary.

For a later form, joining by HH003 plus a person ID is safer than joining only by household ID and roster position. A deletion can make the second row refer to a different person.

Test the edit path and the export shape

Create three roster rows, correct an age, and remove one row. Check that the aggregate follows each change. Then submit a synthetic record and inspect the exported repeated data. Keep the household identifier in the repeated-data context needed for analysis. If a later publishing link sends member data to a dataset, decide whether one wide household row or one long row per person is needed; Module 18 develops that choice.

Change a roster and watch the total

This model mirrors the adult-count test. Clear an age to represent an unanswered member. The count includes entered ages of at least 18; the form's real required rule should prevent an unanswered age from being finalized when that is the study policy. Try 17, 18, 65, then change 18 to 16.

A displayed count here is a learning model. The workbook's count-if() expression and the server preview remain the authoritative test of the actual form.

Know the state of a field record

A form can be completed in a web browser or in SurveyCTO Collect. In Collect, an interview can be open, saved but unfinished, finalized, ready to send, sent, and eventually visible on the server. The words “completed” and “uploaded” are not interchangeable. For a missing household, check the device state before deciding the server lost it. For a web form, distinguish a preview run from a deployed form submission.

Test an offline cycle on the actual device

1. While connected, configure the practice server and download the deployed form.
2. Disconnect. Complete a synthetic household interview, then finalize it.
3. Confirm it remains stored on the device and note its local status.
4. Reconnect, send, and verify the server received it exactly once.
5. If the form is attached to a dataset, refresh the relevant attachment or case list and verify the new row appears where expected.

Do not clear device storage or remove a form to “fix” a send problem while local records remain. Record the device, user, form version, affected IDs, and error. A supervisor can then troubleshoot without losing unsent work.

Distribute changes as a field procedure

A deployed new version is not automatically the version on every offline device at that moment. A release instruction should say when to connect, where to obtain updates, whether saved interviews can be safely reopened, and what test confirms the device has the intended version. If the form uses a dataset attachment, updating the form and refreshing the data source may be separate tasks. A collector should never infer that a new case is absent from the project merely because the local case list has not refreshed.

Choose a source that matches the update need

A direct CSV attachment is useful for a fixed sample or a small training file. A server dataset is useful when the lookup needs to be updated from multiple forms or maintained centrally. Both become local preloaded data when attached to a form. The form needs the correct columns, a stable lookup key, and a refresh procedure for field devices. An attachment is an input to a form; publishing is a separate rule that writes data into a dataset.

Read every argument of pulldata()

pulldata('hh_registry_training', 'head_name', 'hhid_key', ${hhid})

The first argument is the attached dataset ID (or CSV basename); the second is the column to return; the third is the column used to find a row; and the fourth is the form's lookup value. If HH003 is in the form but the dataset row uses hhid_key=HH3, no match is found. If two source rows share the same supposed unique key, the lookup is ambiguous; fix the source rather than guessing which row the form will use.

Preloaded values come into expressions as text strings even when a source column looks numeric. Convert deliberately before arithmetic. Keep the raw pulled value and a converted calculated value separate when troubleshooting a mismatch.

Test missing and stale lookups

1. Attach the training CSV or dataset to the follow-up form.
2. Use HH001 and confirm the expected head name appears.
3. Use HH999 and confirm the form follows an explicit missing-ID path.
4. Change the source name for HH001, then check the old device before refreshing and after refreshing.

A server dataset can be current while a device still has an older attached copy. Ordinary server publishing requires server receipt, and refreshed dataset files may not be immediately available after every update. Record the actual delay observed in your training test and use a field procedure that accommodates it.

Use a dynamic list when fixed choices would be unwieldy

A long school, village, or household list can be loaded from an attached CSV or dataset. In SurveyCTO, a search() expression in the appearance column selects source rows. The matching choice row on choices specifies which source column supplies the stored value and which supplies the displayed label. The stored value should be a stable ID, never merely a name that can be duplicated.

survey:  type=select_one households
         name=selected_hhid
         appearance=search('hh_registry_training', 'matches', 'village_code', ${village_code})
choices: list_name=households  value=hhid_key  label=head_name

This example lists households in the selected village. The value and label cells on that special choices row name source columns; they are not literal household values. Verify the exact source headers and the attached dataset ID before uploading.

Choose an appropriate match and filter

search(source) can list all distinct rows. matches tests an exact value in a named column; contains, startswith, and endswith support other searches. You can also filter by another column. A broad text match may show several people with the same name, so display enough context, such as household ID and village, for a collector to choose correctly. A search that returns zero rows is an expected test case, not an excuse to fall back to the first row.

Keep list updates controlled

A list can change when the dataset refreshes. If a code used in an existing submission disappears or changes meaning, analysis and edits become harder. Define who owns the source, when it refreshes, which column is the stable key, and how a change is communicated to collectors. On an offline device, confirm the new list actually arrived before asking a collector to find a newly added household.

Model the dataset before configuring links

A server dataset is a managed collection of records on the SurveyCTO server; its contents can be uploaded or downloaded as a CSV. For the running example, hh_registry_training stores one row per household. Its key is hhid_key; other columns might be head_name, village_code, adult_count, last_outcome, and last_visit_date. Write the meaning and owner of each column. Decide whether the dataset represents a historical event log or the latest state of each household. This example is a latest-state lookup, so repeated submissions should update the same household row using a stable key.

Use a unique ID field when rows must update

SurveyCTO can enforce that a nominated Unique ID field contains unique, nonblank values. When you configure a form to publish to that dataset, map the form's identifying field into the dataset's unique column and choose it as the field to identify unique records. If you omit the join, each submission can append a new row instead of updating the existing household. If a form publishes an empty or misspelled ID, stop and investigate before trying to merge records by name.

The raw listing and follow-up submissions remain separate evidence. The dataset is a maintained view for preloading or workflow state. If an incorrect publish overwrites a current-state column, use submission history and a correction plan to reconstruct the intended value.

Plan refresh and ownership

Dataset contents can be edited or uploaded manually, published from forms, or updated programmatically. For manual uploads, distinguish append, merge, and replace. A replace operation on the wrong file can discard current rows; use the synthetic training dataset and keep a copy before trying it. Dataset downloads and attached copies may lag recent server updates, so include refresh time in a handoff test rather than assuming instant availability.

Separate a source of truth from a working view

Raw listing submissions are events. The registry row is the current value the follow-up form reads. That distinction matters when a correction arrives. If two records for HH001 disagree on head name, the registry needs a documented rule for which value wins. “Latest arrival wins” can be wrong when an older offline interview is sent late. For a high-stakes workflow, include a reviewed update process or explicit event time and conflict procedure.

Keep the registry narrow. Publish only the fields the next form needs, such as household ID, display name, village code, and a non-sensitive routing flag. An analyst can still use the full submissions for research. A field device should not receive a broad dataset merely because it was convenient to map every form field.

Configure the link from the destination dataset

On the server console's Design tab, find or create the destination dataset. Choose Publish into on that dataset and select the source form. Map each form field to the intended dataset column. Do this field by field for the training example instead of choosing Add all; the explicit mapping makes the data contract visible. Only a field that was relevant in the submission can publish its value.

Choose the link's other settings deliberately

Choose wide format for one dataset row per household submission. Select hhid as the form field that identifies unique records so a later listing for HH001 updates the HH001 row. Add a calculated filter field when only eligible or completed records should publish; the filter must equal 1. Decide whether to select Publish existing data. If selected, earlier submissions can be backfilled into the new link. If not, the link starts with future submissions. Write down which choice you made.

For encrypted forms, only fields configured as publishable can flow into a dataset. A training server with invented data simplifies the first exercise, but a real project must decide which fields may be shared before configuring the link.

Test the link end to end

1. Submit HH001 with consent Yes, two adults, and a head name.
2. Wait for server receipt and locate the submission KEY.
3. Inspect the publishing link status and dataset row for HH001.
4. Submit a second HH001 record with a corrected adult count.
5. Confirm whether the same dataset row updates and whether its value matches the chosen update action.

When a dataset row is absent, check in order: the source submission was received; the publishing link is enabled; the filter equals 1; the mapped source fields were relevant; the join field is nonblank; and the dataset view has refreshed. Do not change several settings at once while diagnosing.

Use a publishing-link test record

Give each new link a known synthetic case. For HH004, write the expected dataset row before sending the form: hhid_key=HH004, head name “Test Person”, village V02, adult count 1. After the server receives the submission, compare every mapped column with this expectation. If the form uses review and correction, note whether the record was held and approved; an awaiting-review record may be received but not yet published.

Keep a screenshot or written export of the link's map and settings. The workbook alone cannot show which destination dataset, update action, filter, or Publish existing data choice was configured in the console. That configuration is part of the maintained source for a connected workflow.

Walk one record through the publishing link

Suppose HH001's submitted listing has head_name=Ana, adult_count=2, and publish_ok=1. The publishing link reads the received submission, applies its filter, maps hhid to hhid_key, and writes the mapped values to the destination dataset. A second HH001 listing with corrected adult_count=3 leaves both submissions available as source records but should update the one current HH001 row when the join and Replace action are configured as specified. The dataset is therefore an operational view with a documented rule, not a substitute for submission history.

Keep this trace beside the field map. It is more useful than a screenshot of a successful Publish button because it identifies which record and settings produced the row.

Decide how existing data enters a new link

When a publishing link is created after submissions already exist, record whether Publish existing data was selected. If you backfill, inspect the resulting row count and a few named keys before allowing downstream forms to use the dataset. If you start with future submissions only, an earlier HH001 submission will not appear solely because the link now exists. A lookup test using that old record could therefore fail even though the new link works.

For the capstone, make one submission before creating the link and one after. Predict the registry under each setting, then verify. This deliberately tests the backfill decision and avoids confusing it with an attachment or pulldata() problem.

Predict a dataset before clicking Publish

A publishing link can append a new row for every included submission or use a form field as a join key to update an existing row. For a household registry, hhid is the join. Map it into hhid_key. If HH001 is published twice, the intended current-state dataset has one HH001 row. Without a join, it may have two. A head name is an unsafe join because two households can share a name and a spelling correction can change it.

Choose a field-level update action

The default Replace action uses the new mapped value as the dataset value. Add increases an existing numeric value by the submitted value. Concatenate appends or prepends text with a separator; the published text has a length limit, so it is not a safe unlimited event log. For adult_count, Replace is usually appropriate because a corrected count is the new total, not an increment. For a cumulative tally, Add may be appropriate if repeated submissions are guaranteed not to be replayed. Do not use Add for a value that can be resent or edited unless duplicate protection is designed.

A publishing filter is a calculated decision

A publishing link can include a form submission only when a chosen field equals 1. A calculate field such as publish_ok = if(${consent} = 'yes', 1, 0) makes the rule explicit. Decide whether refusal records should create a lookup row, update a case state, or remain only in raw submissions. Those are project decisions; no single filter fits all studies. Test 1, 0, and blank. Also decide whether a changed answer and corrected submission should remove or revise a row published earlier; a filter on later submissions does not automatically describe the handling of old dataset state.

Simulate an update before configuring a link

Start with a dataset row for HH001 whose adult count is 2. Enter a new submitted count, select an update action, and decide whether the publishing filter passes. A no-join link appends a second row; Replace and Add use the matching household key. This model intentionally shows why adding a corrected total is wrong.

After using the model, write the actual field map you would put in the console. The simulator cannot see your server's links, encrypted fields, or pending submissions.

The connected two-form path

The listing form does not directly send a value to the follow-up form. It sends a submission to the server. A publishing link maps that submission into a dataset row. The follow-up form has the dataset attached and pulls the intended row by the stable ID. A separate cases dataset can expose the follow-up form to an assigned collector. Make each handoff explicit; otherwise a missing name in follow-up can be misdiagnosed as a calculation error when the dataset simply did not refresh.

Configure in an order that produces evidence

1. Upload and deploy the listing form. Verify its form ID and synthetic test submission.
2. Create hh_registry_training with hhid_key as the unique ID field and the columns the follow-up will need.
3. Use Publish into to map listing fields. Send HH003 and inspect the dataset row.
4. Upload the follow-up form and attach hh_registry_training as its preloaded source before deploying and testing it.
5. In the follow-up, use the case ID or a selected household ID to pull head_name. Test HH003 and a missing ID.
6. After publishing a correction from the listing form, refresh the attached dataset on the intended device and check the new value.

This order helps distinguish a form error, publishing error, attachment error, stale local copy, and lookup-key mismatch.

Write a connection contract

Store this contract next to the maintained XLSForms. The console settings are part of the field system even though they are not in either workbook.

Trace a failed connection without guessing

Stop at the first mismatch. If the registry row is absent, changing the follow-up form will not create it. If the row is correct but the device shows an old value, repeating the listing interview can create duplicate raw records without fixing the attachment. The table turns “the forms are not connected” into a specific, reproducible fault.

Keep three copies of a household record straight

The two-form workflow can show three different states at one moment: the latest listing submission on the server, the current registry dataset row, and the dataset copy attached to a collector's form. They are related by publishing and refresh steps but are not one object. If the head name was corrected to “Ana Maria” in a new listing, first check that the submission reached the server. Then check the registry row. If it is current there but the follow-up still shows “Ana,” update the attached data on the collection device and retry the lookup.

Do not edit the follow-up expression to compensate for a stale attachment. Fix the state that is stale.

Specify the missing-key path

A collector may mistype HH001 as HH01, select a case whose registry row has not published, or work with an outdated case list. A blank pulldata() result cannot tell those causes apart. The form should expose the entered or selected key, show a clear “household not found” instruction, and prevent an ordinary completed follow-up until the ID is resolved. The field procedure should say whether the collector refreshes attached data, calls a supervisor, or records a separate unresolved-contact event. Never fill a household's name by guessing from a near match.

Test both HH001 and HH999. For HH999, verify the displayed message, the fields that remain accessible, and what a submitted unresolved record would contain. That negative path is part of the linked system, not an optional edge case.

Choose wide or long from the destination unit

In wide publishing, one form submission produces one dataset row. Repeat fields become numbered columns such as member_age_1, member_age_2, and so on. This can work for a household summary with a limited roster. In long publishing, each repeat instance produces its own dataset row. This is often better when another form needs to search individual members. Long publishing requires a field inside the repeat that uniquely identifies each destination row; a household ID alone is not enough for several members in one household.

For long format, mapped repeated fields must come from the same repeat group or a suitable parent repeat. A repeated unique field must be mapped and selected for identifying records. Test adding, editing, and removing a repeat instance to see how the dataset changes.

Server publishing and offline publishing are separate plans

Ordinary server publishing follows server receipt. A device offline in the field cannot assume a new listing submission is already available as preload in its next form. SurveyCTO also supports offline dataset publishing in Collect, but that feature needs its own configuration, permissions, compatible forms, and device tests. The course's basic capstone uses server receipt and a deliberate attachment refresh; it does not silently imply instant offline updates.

If an advanced study needs two forms on one device with no network between them, write an offline test covering a new case, a corrected value, a second device, and later synchronization. When devices disagree, define which dataset state wins and how supervisors discover conflicts. A same-device demonstration alone does not prove a multi-device workflow.

Reconcile the source and destination

When a repeat publishes long, count the expected repeated rows from the form and compare them with dataset rows for that submission. Check the repeated key, household key, and selected filter. A difference may be intended if only eligible members publish, but the rule must be documented. Avoid changing a roster's row order without testing whether member identities remain stable.

A case is the subject of work, not a submitted visit

Case management reorganizes collection around households, schools, clinics, or another tracked unit. A cases dataset supplies the list shown through Manage Cases. One case can offer one or more forms, and one case can have several submissions over time. The case ID identifies the subject; a submission KEY identifies one completed visit. Do not use a changing display label as the case ID.

The attached workshop photo shows the original case-routing discussion. The typed diagram and tables here are the operational version to use for the exercises.

Prepare the cases CSV

The required columns are id, label, and formids. The ID must be unique and nonblank. The label is shown to the collector. formids lists the form IDs offered for that case, separated by commas when there is more than one. Optional columns include users, roles, enumerators, and sortby. Include the standard columns in a maintained training CSV so assignments can be added without restructuring it later.

id,label,formids,users,roles,sortby,enumerators
HH001,Household HH001,hh_followup_training,,,1,
HH002,Household HH002,hh_followup_training,,,2,

Blank user and role values make the initial training cases broadly visible under the platform's case-list rules. Before actual field assignment, replace them with approved test usernames or role IDs and verify the effective view with those accounts. Use only invented IDs and labels in the trial.

Connect caseid to the form

Include the caseid metadata field in the follow-up form. When the user opens a form from Manage Cases, SurveyCTO populates it with the selected case's ID. If the same form is opened from Fill Blank Form, caseid can be blank. The form should either require a valid case path for case-managed work or define a separate manual-ID procedure. For the training follow-up, the lookup uses the selected case ID as the household key.

On a mobile device, Manage Cases may need to be enabled in Admin Settings. Users refresh the case list when connected to obtain current cases. A missing case can mean a stale list, a visibility rule, a wrong role's cases dataset, or a form ID in formids that is not on the device.

Choose the case list display for the work

SurveyCTO supports a tree view and a table view for cases. A tree can expose each case and its available forms; a table can show selected case columns for sorting and filtering. Use a short label that helps a collector find the right subject without exposing unnecessary private data. For a household training list, “HH003 · V02” is enough. A real study may require a more discreet label than a respondent's full name.

A case row can list several form IDs. That does not force every form to be completed or define their sequence; the operational procedure must say which form is due and when. A calculated or published status column can help, but a case list is only as current as its dataset and the device's refresh. Test an added case and a closed case on both the server and field device.

Design case IDs for the whole project

A case ID should survive a change of head name, village, assigned collector, and visit status. Use a text identifier even if the first set of IDs looks numeric; text preserves leading zeros and allows a prefix. Before loading the cases CSV, check for blank IDs, duplicates, leading or trailing spaces, and different spellings of the same ID. The same normalized value must be used in the registry lookup key and in caseid when the case opens a form.

Keep the ID cleaning rule with the cases file. A case list that looks right to a person may still fail an exact lookup.

Write the access plan before creating accounts

SurveyCTO users have roles that control console and collection permissions. A cases dataset can also filter rows by the users, roles, or enumerators columns. These mechanisms answer related but different questions: may this person use the system, may they fill this form, and which cases should appear in their queue? Do not assume that seeing a form implies seeing every case or that an administrator's case list matches a collector's.

Use test accounts or the server's training environment. If you create named users for a class, tell them what records they can access. Do not place passwords in the cases CSV or XLSForm.

Filter a queue with the cases dataset

For a simple two-collector test, put the actual SurveyCTO username for Collector A in HH001's users cell and Collector B's username in HH002's. Keep formids the same if both should fill the follow-up form. Reload the case list as each collector. A comma-separated users cell can list more than one approved account. The roles column can list role IDs instead of named users for role-based queues. If enumerator IDs drive visibility, the cases dataset must be linked to the proper enumerator dataset and tested with the enumerator selection flow.

Do not infer the combining behavior of several nonblank visibility columns from a single admin screenshot. Keep the first lab to one filter mechanism, then test every intended combination with separate accounts before a pilot.

Diagnose a missing case in order

1. Confirm the case row exists in the correct cases dataset and has a nonblank unique id.
2. Confirm the current user's role points to that cases dataset; multi-team or custom roles can use a non-default dataset ID.
3. Check users, roles, and enumerators values against the actual account and configuration.
4. Refresh Manage Cases on the device, then confirm the current form ID appears in formids and the form is downloaded.
5. Check whether the case appears under another test account. Record which filter changes the result.

This sequence protects against a common mistake: adding duplicate case rows because the first row is invisible under the current account.

Practice the simplest case filter

This model shows one mechanism at a time: the users column. HH001 is assigned to collector_a; HH002 is assigned to collector_b; HH003 has a blank user value and is visible to both in this training model. Real role and enumerator filtering should be tested separately on the server.

The model predicts which rows to expect after refresh. It does not grant permission or create users. A server role can still prevent collection even when a case is listed.

Define a case lifecycle as data changes

A case list can be static, but a connected workflow can update it from submitted forms. Write the states first: not_started, assigned, callback, complete, and perhaps closed. Define who may move a case between them and what evidence supports each transition. A follow-up submission with outcome callback might update a case status and next-visit date; a completion might close the case or remove the follow-up form from its formids. These are publishing decisions, not automatic effects of filling a form.

Use publishing to update a case row

A cases dataset is a server dataset with special columns. A form can publish into it. Map the stable case or household ID to its id column and use that ID as the record join. Map only the state and routing fields the form is authorized to change. If an assignment changes, update the users or roles value deliberately and test that the old and new account views reflect the handoff after refresh. A status word should not accidentally be mapped into users; the values in that column must be actual usernames if it is used for visibility.

A new case can also be generated by a publishing link, but its id, label, and formids must be supplied. Test case creation separately from case update. Keep a known-good CSV export of the synthetic cases dataset before experimenting with publishing actions.

Test order and duplicates

Submission order can differ from visit order when devices work offline. If a callback was recorded on Tuesday but sent after a Wednesday completion, a simple Replace mapping could put the case back in callback state. Decide whether the workflow should block the stale update, flag it for supervisor review, or use an authoritative timestamp and approval process. Also test duplicate sends and corrections. Dataset state is a current view; the source submissions and their KEYs remain the audit trail.

Map a handoff as a transaction

Suppose Collector A completes an initial visit and the case must move to Collector B. The transition has four observable steps: the new visit submission is received; its publish rule updates the case row's assigned user; the old account refreshes and no longer sees the case; the new account refreshes and does see it. Record all four. A success message in the form is only the first step.

Use a unique case ID for the update and publish the actual SurveyCTO username in users. Do not put a status label such as callback into the username column. If a case must remain visible to both people for a review period, list both approved usernames according to the case-management format and test both views. A supervisor should own the policy for what happens when the new collector has not yet refreshed.

Model events separately from current state

A follow-up visit is an event: HH001 was visited on a date, with an outcome and a submission KEY. A case row is current state: HH001 is assigned, callback due, completed, or closed now. Several visit events may contribute to one current row. If every follow-up submission replaces case status, a late offline callback may reopen a case after a newer completion. Write a transition rule that considers the existing state and the order of events, then test the late arrival. A simple Replace action has no inherent knowledge that “complete” should dominate “callback.”

For a small project, a supervisor review before closing cases may be enough. For automated state changes, document the exact ordering and conflict rule and verify it on delayed offline data before using it in fieldwork.

Keep submissions and dataset rows in separate counts

Two HH001 listing submissions can produce one current HH001 dataset row if the link upserts on household ID. A filter may exclude a refusal. A long repeat can produce several destination rows from one submission. Therefore, a simple equality between submission count and dataset row count is not a universal QA rule. Write the expected relationship for each link, then compare the actual output with it.

Review data with actionable queries

Monitor incoming submissions for missing IDs, duplicate IDs, unexpected values, unusual duration, invalid combinations, and field-version differences. A query should identify the record, field, observed value, expected relationship, and question for the field team. “Bad data” is not a query.

When reviewing a published dataset, add the publishing-link version and refresh time to the query. A stale attached copy can show an older head name even when the current server dataset is correct.

Export with provenance

For each test export, record server, form or dataset ID, export time, form versions included, filters, and format. Keep an unmodified raw copy and do analysis in a separate file. If the form has repeats, inspect the repeat-level output and join keys. If datasets contain current state, keep a dated snapshot alongside source submission history so later investigators can reconstruct how a row changed.

Review status can delay publishing

SurveyCTO can hold incoming submissions for review instead of releasing them immediately. When that workflow is enabled, a submission may be received on the server yet absent from the dataset because it is awaiting approval. Approved submissions are released downstream; corrections made in review are applied to the published result. Record the form's review settings in your publishing contract. Test one record that is held and one approved record rather than assuming server receipt alone triggers the link.

For a pilot, decide who may review, correct, approve, or reject. A data-quality correction can change a calculation or routing field, so rerun the downstream dataset and case checks after approval. Keep the raw record, correction history, and export settings together.

A connected form change has several dependents

Before changing a deployed question, search for its use in calculations, relevance, choice filters, dataset mappings, case routing, exports, and analysis scripts. A renamed hhid field can break a publishing join and a follow-up lookup. A changed stored outcome code can alter a 1/0 filter. A changed form_id can make a case's formids point to the wrong form. Keep a dependency map beside each maintained XLSForm.

Limit what can be published

SurveyCTO supports end-to-end encryption. Form data that remains end-to-end encrypted cannot simply be published into an ordinary server dataset. Fields deliberately marked publishable are an exception for values suitable to share in a connected workflow. Decide which fields are necessary for case routing or lookup, and avoid publishing a respondent's full answer set just because Add all is convenient. On a real project, document this choice with the data owner and test the effective export and dataset access.

Write a recoverable incident note

When a linked workflow fails, freeze the facts before changing settings: server URL, affected form and dataset IDs, form versions, device or browser, user role, case ID, submission KEY, expected state, observed state, and time. Keep a copy of the relevant dataset row and publishing-link configuration. Change one cause, rerun the same synthetic test, and record whether it resolved the issue. If local records are unsent, preserve them; do not clear app data as a first step.

Keep a change log that reaches beyond the workbook

For a live connected form, the release record should include the source workbook hash or filename, old and new form version, calculation tests, publishing-link changes, dataset schema changes, affected case queues, device update instruction, and rollback source. If the change is only to a question label, confirm that the variable name and stored choice values remain stable. If a mapped field must be retired, plan how old records will be exported and how the dataset column will be maintained.

Rollback is not merely uploading the old XLSForm. A publishing link, dataset row, or case assignment may already have changed. The recovery plan should say how to identify affected submission KEYs, whether a dataset snapshot exists, and who can approve a corrective republish or manual update. Test that plan on synthetic records before a production incident.

Deliverable specification

Your final practice system has two forms, one household lookup dataset, and one cases dataset. The listing form records hhid, head name, village, consent, a repeat of members and ages, and adult_count. The follow-up form uses the case ID or entered household ID to pull the head name and records visit outcome, next visit date when needed, and a calculated publish flag. The registry has one current row per household. The cases dataset offers the follow-up form to a collector. Use only synthetic IDs HH001–HH004.

Listing starterListing exampleFollow-up exampleLookup CSVCases CSVCalculation test matrixPublishing map templateRelease test log

Part A: build and calculate

1. Copy the listing starter. Complete its member repeat and adult-count calculation without reading the completed example first.
2. Run the calculation test: ages 17, 18, and 65 give adult count 2; correct 18 to 16 and expect 1; remove the 65-year-old and expect 0.
3. Run consent No and confirm roster values do not enter a completed refusal record unexpectedly.
4. Compare your workbook with the completed example. Explain any difference in missing-value handling.

Keep a test matrix. An expression that compiles but produces the wrong value after an edit has not passed.

Part B: publish and preload

1. Deploy the two forms on a designated practice server. Create the registry dataset with hhid_key as unique ID.
2. Publish listing fields into the registry in wide format. Join hhid to hhid_key and record whether you backfilled existing submissions.
3. Submit HH001 and verify server receipt and the dataset row.
4. Attach the registry while uploading the follow-up form, then deploy it. Open HH001 and confirm that its head name is pulled from the right row.
5. Correct HH001's head name in a second listing submission. Check the registry and then refresh the follow-up attachment. Record when the corrected name appears.
6. Test HH999. The form should follow your defined missing-ID procedure.

Part C: cases and field access

1. Prepare the cases CSV with HH001, HH002, and HH003. Set formids=hh_followup_training.
2. In a training cases dataset, load the CSV and enable Manage Cases on the intended device if needed.
3. Open HH001 through Manage Cases. Confirm the caseid stored in the follow-up is HH001.
4. If test accounts are available, assign HH001 and HH002 to different users and verify both views. Do not use a real enumerator account merely to make the lab pass.
5. Submit a callback for HH001. If you configure a case-state publishing link, verify the row's new state and its visibility after refresh.

Part D: negative and recovery tests

For each failure, change one setting or source value, rerun the same synthetic case, and write the result. Preserve original submissions and the prior workbook.

Bring your build-along together

You have a household roster and education questionnaire and a ten-row household sample. Continue the form you began during the earlier build-along milestones: make it case-managed, test it with invented answers, and prepare its main and repeat exports for review. The HH001–HH004 connected-data example is a separate teaching case. Keep the questionnaire beside the workbook; its question numbers are the specification.

Questionnaire PDFOriginal household listTraining preload with barangay IDsTen-case queue

Inspect the source before programming

Open the two CSVs and check all ten IDs, duplicate IDs, blank location fields, and unexpected leading or trailing spaces. The derived B-codes are a teaching device, not authoritative geographic codes.

Create the case and preload contracts

The included practice_cases.csv uses id,label,formids,users,roles,sortby,enumerators. Its id equals the source caseid; its formids is hh_roster_education_training. Blank user, role, and enumerator values make the training rows visible to users of that case list. Before assigning live work, replace them with approved test identities and verify each user's effective view.

Create a server dataset from practice_household_preload.csv, set caseid as its unique ID, and attach it when uploading the form. The reference form uses pulldata('practice_household_preload', 'province', 'caseid', ${hhid}) and the same pattern for other fields. Keep the dataset ID, attachment name, and key identical. Upload practice_cases.csv to the training cases dataset. The form should also allow a manual ID when opened outside Manage Cases; that path is for testing, not for replacing case assignment.

Consent is a real branch

Q0.1 asks whether the respondent consents. Code Yes and No as stored values, calculate a refusal flag, and put the interview inside a group relevant only when consent is Yes. Test both paths. A No response should create a refusal submission with case and staff identification, while the roster and education fields remain empty. Do not force a respondent into the interview to make the form complete.

Use the PDF as a field specification

Programming starterReference buildOriginal questionnaire

Program from the PDF first, then compare with the reference. The reference is an executable teaching adaptation, not an approved production instrument. It asks household size before the name repeat to control its count; the paper questionnaire instead ends name collection through Q1.7. Record this change in your specification and test how a collector corrects the count.

Part A: names and confirmation

Do not assume a name is unique. Member order is the link between the name, demographic, and education repeats. Changing repeat count after data have been entered needs a documented correction procedure.

Part B: demographics and age

The demographics repeat has repeat_count=count(${members}). Each iteration uses indexed-repeat(${full_name}, ${members}, index()) so the name beside Q1.8–Q1.12 comes from the matching roster position. Test a household with a child first, an adult second, and another child third; a skipped member must not shift the later name.

The source allows -999 (unknown) and -888 (refusal) for birth day, month, and year. The reference calculates completed years from the three components when all are positive. If any component is unavailable, it asks Q1.10 for age and unit; days and months become zero completed years, while years use the reported number. The reference bounds days at 29, months at 11, and years at 110. Q1.12 appears only above age 13; Q1.12a appears for codes 1–5. Test ages 13 and 14 and a birthday immediately before or after the interview date.

The PDF has no Q1.11, and its partial-date specification does not state how to reject impossible calendar dates such as 31 February. The reference checks component ranges but leaves cross-component date validation unresolved. Decide the interview rule with the study owner before field release. Record whether a partial birth date should produce an estimated age, an unknown age, or an explicit follow-up.

Part C: phones and education

The paper form asks Q1.13 to select phone holders, then repeats Q1.14–Q1.18 for up to three holders. The reference asks has_phone inside each demographic repeat and calculates phone_holder_count. It displays a warning above three but does not silently drop a fourth phone owner. The three-person cap requires a study decision: hard stop, first three by a documented rule, or a revised questionnaire. Mobile numbers are stored as text so an initial zero survives; the constraint accepts 11 digits starting with 0 and the explicit -999/-888 codes.

The education repeat also uses the full roster count. It pulls the name and calculated age at the same index, then puts Q2.1–Q2.6 in a group relevant for age 5 or older. Using only the count of eligible members would mismatch names and ages when an under-five appears early. Q2.2 and Q2.3 appear for current attendees. Q2.4 appears only for non-attendees aged 5–24. Q2.5 appears for every eligible member; Q2.6 excludes codes 00 and 99. The reference uses separate current-grade and highest-grade lists because the source adds 00 and 60 only for Q2.5.

Run a release test, not just a preview

Practical test matrixCases CSVPreload CSV

The supplied matrix contains twelve tests. Add the observed result, form version, device or browser, and a pass or fail for each. A form that compiles has only passed a syntax check. Test through Manage Cases on a device or an enabled web-collection account, then compare with the designer's Test view.

Test sequences that can expose a wrong calculation

Inspect the exports

Submit only synthetic cases. Export the main submission data and the member, demographic, and education repeats. Join repeat rows by their parent submission key and repeat index; do not assume that a member name is a join key. Check that a refusal has no member rows; that each consented household has the expected number of member and demographic rows; and that education rows for under-fives have no Q2 answers. Preserve the original submissions and an export copy when correcting a mistake.

If you publish a household-level summary into a server dataset, map hhid to a unique caseid column, and publish only non-sensitive indicators needed for follow-up, such as roster count or an interview status. Do not publish names, phone numbers, or treatment assignment into a broad case list. Define whether a correction replaces a prior summary row and test a second submission for the same case.

Release decision

Before calling this field-ready, obtain decisions on the missing barangay ID source, staff roster and auto-fill, the Q1.7 roster-length adaptation, impossible dates, partial age, and the three-phone rule. Confirm consent wording with the study owner. Then run the matrix again on the approved form version and target device. The included reference workbook remains a training aid until those decisions are implemented and tested.