A project has a form and its data

KoboToolbox is a system for designing forms, collecting submissions and reviewing or exporting those submissions. A project contains one form, its versions, settings, media, collaborators and submitted records. A data collector uses either a web form or the KoboCollect Android app to complete that form.

The form is a definition. A submission is one completed record. Editing the definition does not change answers that collectors have already sent, although later edits to older records can be affected by a new form version.

Choose the server before creating team accounts

Current KoboToolbox account guidance describes the Global and European Union public servers. Some organizations have a private server. An account created on Global cannot be used to sign in to EU, and users who collaborate on a project need accounts on the same server.

From questionnaire to export

1. Create a project and build or upload the form.
2. Preview the draft and test each important response path.
3. Deploy the form, then test a live submission.
4. Give collectors the correct link or Android setup.
5. Review submissions and export the format needed for analysis.

“Upload” applies when your source is an XLSForm workbook. If you build directly in the Formbuilder, there is no separate workbook to upload before deployment.

Read the Projects page

The Projects page lists projects and their status. A draft is still being prepared. A deployed project can accept submissions under its access settings. The left menu also gives access to the question library. The controls for archive, sharing and deletion may appear near the project list; this course does not use them for practice.

In the current interface, opening a project leads to Summary, Form, Data and Settings. Summary gives links to edit or preview a form and, after deployment, to view the data.

Create the course project

1. Choose New, then Build from scratch.
2. Use the title School Visit Checklist — Practice.
3. Describe it as “Synthetic training records only.” Choose a country and sector if your server asks for them.
4. Open the Formbuilder. Add a Text question labelled “School ID” and an Integer question labelled “How many classrooms are currently usable?”
5. Save. An asterisk by Save indicates unsaved edits. Preview both questions before continuing.

In the Formbuilder, add a question below an existing question, enter its label and choose a type. Question settings provide required status, hints, skip logic and validation. Once you choose a type, the Formbuilder does not let you convert that question to another type in place; plan the type first.

Choose the type from the answer, not the wording

The source slides say “Number” as a broad category. XLSForm distinguishes integer and decimal. Keep the distinction explicit because it affects input and validation.

Separate three names that learners often mix up

The question label is what the user sees. The question name becomes the stored field name. For a select question, each choice name is the stored answer code, while its choice label is what the user sees.

Use clear, unique question names with underscores instead of spaces. Decide choice codes before collecting real data. You can improve a displayed label later, but changing a stored code after collection can change what exported values mean.

Write a question a collector can apply consistently

“Classrooms?” is too vague. Use “How many classrooms are currently usable for teaching?” and a hint such as “Count rooms that can host a class today; exclude rooms closed for repairs.” State a time reference where it matters. Include “Do not know” or refusal options only when the study needs them and the team has agreed how they will be coded.

Why move to a spreadsheet?

The Formbuilder is useful for learning and shorter edits. XLSForm is a spreadsheet definition of the same KoboToolbox form. It lets a team review many rows, edit longer choice lists, add translations and keep a versioned source file. Download a Formbuilder form as XLSForm when spreadsheet editing becomes more efficient, then upload the revised workbook to the project and preview it.

Read the three sheets

Use the lowercase sheet names shown here. The settings sheet is optional for a simple workbook, but useful once a team manages versions and languages.

Follow the link from a question to its choices

survey sheet
type              name          label
select_one yn     consent       Does the respondent agree to participate?

choices sheet
list_name   name   label
yn          yes    Yes
yn          no     No

The yn in select_one yn matches list_name = yn. The stored answer is yes or no. Logic must compare the stored code, not the visible English label.

Upload and troubleshoot a workbook

1. Make a copy of the XLSForm before changing it.
2. Keep the column headers exactly as KoboToolbox expects.
3. Upload through New → Upload an XLSForm for a new project, or replace the form in the practice project if that is your planned workflow.
4. Read any validation error for its row number, question name or expression. Correct one cause, upload again and preview.
5. Never deploy just because the upload succeeds. Preview and test the paths first.

A common mistake is using a column name from another platform. In KoboToolbox XLSForm the visibility column is relevant.

Diagnose an XLSForm error from the row that caused it

When an upload fails, first read the named sheet and row in the error message. Do not replace the whole workbook or rename several fields at once. Compare the row with the question immediately before it and with the matching rows in choices.

Question names are data column names. Use short, stable names such as classrooms_usable. Avoid putting punctuation, spaces or a changing year in them. Labels can change when wording is improved; changing names during fieldwork needs an explicit data plan.

Start with the rule in words

Write “Ask the respondent's role only when consent is Yes.” Then translate it into a true/false expression on the follow-up question:

relevant
${consent} = 'yes'

${consent} reads the earlier answer. 'yes' is the stored choice name. When the expression is true, the question appears. Put the rule on a begin_group row to control an entire section.

Visibility, required answers and validation do different jobs

The dot means the answer to the current question. Do not use ${classrooms_usable} as a substitute for the dot when validating that same question.

Test boundaries and missing values

For a classroom count from 0 to 120, test −1, 0, 120 and 121. Check whether a blank answer is allowed. If the question is required, blank must stop completion; if it is optional, the range rule should not silently turn blank into zero.

Select One and Select Many need different tests

A Select One answer is one code, so ${electricity} = 'grid' is appropriate. A Select Many answer can contain several codes. Use selected(${facilities}, 'other') to show a text question when Other is selected alongside any other facility.

type       name              label                         relevant
text       facility_other    Describe the other facility   selected(${facilities}, 'other')

Test a change of answer, not only the first answer

A collector may select yes for consent, start the follow-up, then correct consent to no. Preview that exact path. The follow-up must disappear; check whether answers already entered there are cleared or retained in the saved record. Treat the observed behavior as a data issue, not just a screen issue. Repeat the test when editing a submitted record, because a later form version can affect editing differently from new entry.

Record the expected and actual outcome for each case. If a rule fails, point to the question name and expression that caused it. That gives a second form designer enough information to reproduce the issue.

Calculate a value only after defining what it means

A calculate row stores a derived field and normally has no visible label. If a school reports six usable classrooms and two unusable ones, the total is eight. Write the relationship first, then the expression:

type        name                 label                              calculation
integer     classrooms_usable    How many classrooms are usable?     
integer     classrooms_closed    How many are closed?                
calculate   classrooms_total                                        ${classrooms_usable} + ${classrooms_closed}

If either source can be blank, decide whether blank means unknown or zero. Do not silently treat an unanswered count as zero unless the questionnaire specification says so. Test the calculation after changing and clearing each source answer.

Groups organize; repeats multiply rows

A group puts related questions together, such as “School facilities.” A repeat asks the same block for each item. For a classroom inventory, one repeat instance is one classroom.

type           name        label
begin_repeat   rooms       Classroom inventory
text           room_code   Classroom code
integer        seats       Number of usable seats
select_one yn  in_use      Is this classroom in use today?
end_repeat

If you want exactly the number entered in classrooms_usable, the repeat can use a repeat_count expression. Decide whether that count should be fixed or whether the collector may add and remove rows. Test what happens when the source count decreases after entries have been filled.

Read repeated data as a separate level

One school submission can have several classroom rows. In the standard XLS export, the main sheet has one school visit row and the rooms sheet has one row per classroom. The main CSV download does not contain repeat rows. The exported _index and _parent_index fields help link them.

This table shows the idea; the real export uses system identifiers rather than the school ID alone for the parent-child link. Keep the school ID as a study identifier and preserve the export's system columns during the merge.

Keep summary counts and repeat rows consistent

The school form asks for a summary count of usable classrooms and also has one repeat row per classroom. These answer different questions: the summary is the reported total; the repeat is the inventory actually entered. If the study expects every usable classroom to have an inventory row, define that rule before programming. If only selected rooms are inventoried, say so in the question label and do not compare the two totals as if they must match.

The completed example lets collectors add repeat rows and leaves this consistency review to the supervisor. It does not force a repeat count from classrooms_usable. A fixed repeat count can prevent accidental omissions, but changing the count after entering rows needs careful testing, especially when the count is reduced.

Filter a long list from an earlier answer

Suppose a school visit first selects a province, then a municipality. A long municipality list is easier to use when it only shows options for the chosen province. In XLSForm, a column in choices stores the parent code, and choice_filter on the municipality question compares it with the answer.

survey sheet
type                       name           label                    choice_filter
select_one province_list   province       Province                 
select_one muni_list       municipality   Municipality             province_code=${province}

choices sheet
list_name   name   label          province_code
muni_list   m01    Municipality A p01
muni_list   m02    Municipality B p01
muni_list   m03    Municipality C p02

The names p01, m01 and so on are illustrative. Check the exact spelling and codes in both sheets. Test at least two provinces, including one with no matching municipality, to find a blocked path.

Translate the respondent-facing text

Use language-specific columns such as label::English (en) and label::Filipino (fil). Translate choices, hints and error messages too. Stored question names and choice names remain the same across languages.

These are examples of the column structure, not approved survey translations. Have the project's qualified translator review consent text and all terms whose meaning affects measurement.

Prepare for location and media questions

A geopoint question depends on device location services and field conditions. Decide where the collector should stand, how long to wait for a fix and what to do when a point cannot be collected. An image or audio question produces a file attachment. Test device storage and upload on the actual field method.

Build a test matrix before deployment

A preview that follows one happy path misses most form errors. Make a small table of inputs and expected behavior before you publish. The school visit needs at least these paths:

Use invented answers. Mark each result Pass or Fail and keep the test note with the form version.

Preview, deploy, then test a live submission

1. Save all edits and preview the draft.
2. Fix failed paths and preview again.
3. On the Form page, choose Deploy.
4. Open the deployed collection form and send one synthetic record.
5. Confirm the record appears in Data and inspect its exported values.

Preview is a design test. A live submission checks the collection link, authentication, server receipt and export structure.

Understand redeployment

After you edit a deployed form, the Form page offers Redeploy. Saved edits are not public until redeployment. Web forms may ask the collector to refresh. KoboCollect users must download the updated form while connected.

Write a release record that a field team can use

For each deployment, keep the form ID, version, deployment time, source workbook filename, change summary, tester, and a link or location for the test results. Add the action collectors must take. “Updated form” is too vague; “connect to the server and download version 20260924 before the next visit” is testable.

When a field team reports a problem, ask which form version was on the device, whether the record was sent, and which test input reproduces the problem. Keep the older workbook so the team can compare behavior across versions.

Choose the web form mode

KoboToolbox web forms run in a browser on a computer, phone or tablet. They can support online and offline collection, but the specific mode and device must be tested before fieldwork. On the Form page, the Collect data area offers modes including Online-Offline (multiple submission), online-only variants and View only.

Older materials call these “Enketo forms.” Current KoboToolbox documentation calls them web forms and notes that Enketo powered earlier versions.

Authentication is a project decision

By default, deployed projects require sign-in to open and submit. You can share a project with named users and give Add submissions permission. For a public respondent link, the project owner can allow submissions without a username and password. That setting changes who can send data, so review it deliberately.

What an offline browser test must show

1. Open the deployed form while online in the intended browser and mode.
2. Disconnect the device and start a synthetic school visit.
3. Save or submit according to that mode. Close and reopen the form only if your field procedure requires it.
4. Reconnect and confirm the submission reaches Data exactly once.
5. Repeat on the type of device collectors will use. Browser storage and private-browsing behavior can affect offline work.

Write a field instruction from your observed result. “Works offline” is not specific enough to tell a collector what to do when a device has no signal.

When the network returns, verify the result

An offline form may still be stored in the browser after the enumerator presses a button that looks like submission. The collector needs a clear distinction between “saved on this device” and “received by the server.” After reconnecting, use the mode’s submission queue or status screen, then check the project Data table for the synthetic school ID. Do not enter the same visit again simply because the first upload is slow; that can create a duplicate.

Put the result of these checks in the field guide for the actual device and browser combination. A desktop demonstration does not prove that a shared field tablet has the same storage behavior.

Prepare the Android app

KoboCollect is the Android app for field entry. The app connects to the KoboToolbox server, downloads deployed forms and later sends records. The URL used by KoboCollect is different from the website URL: the Global server uses https://kc.kobotoolbox.org/, while the EU server uses https://kc-eu.kobotoolbox.org/. A private server supplies its own address. The Form page's Android collection instructions show the URL for that project.

1. Install the current KoboCollect app on a supported Android device.
2. Configure its project with the KoboCollect URL and an account that has permission to add submissions.
3. Download the practice form while connected.
4. Check the form title and version before going offline.

For several devices, a QR code can copy settings from one configured device. Treat that QR code carefully because KoboToolbox documents that it can contain account credentials.

Know where a record is

Finalizing on the device and receiving a record on the server are separate events. A field close-out routine should check both.

Test the offline cycle

1. Download the form while online.
2. Turn off network connectivity. Start a school visit with invented values and save it as a draft.
3. Reopen the draft, complete it and finalize it.
4. Reconnect. Send the finalized record. Check the server Data table.
5. Change the practice form, redeploy and download the updated form to check how a version change appears on the device.

Trace a missing Android submission

Start on the device. A record still in an open form is not finalized. A finalized record may be in Ready to send. After sending, it should appear in Sent; then confirm server receipt in the project Data table. Use the synthetic school ID and the time of completion to match the device record with the server record.

If the device reports a send error, preserve the record and error message while troubleshooting. Do not clear app storage or remove forms as a routine fix: locally stored work could be lost. Supervisors should record the device, form version, last successful send and affected school IDs before changing configuration.

Read the Data page before exporting

The Data area includes a table of submitted records and may offer reports, map and media gallery views. Use the table to check that test submissions arrived, which form answers are blank, and whether unusual values need investigation. A chart or map is a quick view, not a complete quality review.

Choose the export for the task

Use Data → Downloads, select export settings, click Export and then Download. Record the export date, project version and whether values and headers use names or labels. Do not assume a CSV contains every part of a hierarchical form.

Link a classroom row to its school visit

In an XLS export, the main sheet has one row per submission. The rooms sheet has one row per classroom entry. KoboToolbox documents _index and _parent_index for linking these levels. Retain these columns while checking or merging the data.

A small daily QA review

1. Compare expected and received visit counts by collector or area.
2. Check missing IDs, duplicate school IDs and consent paths.
3. Compare classrooms_usable with the number of room repeat entries.
4. Review outliers in counts and GPS points that fall far from the sample area.
5. Document each query, correction and decision. Do not edit a record just to make a chart look plausible.

Turn a suspicious export row into a query

Data review should produce specific questions for the field team. “Bad data” gives no one a way to act. A useful query identifies the record, variable, observed value, expected range or relationship, and the decision needed.

For each export, record the project, export time, selected form version range and format. Compare submission count with the field log, check duplicate school IDs, missing consent, out-of-range counts, and repeat rows without an identifiable main record. A code such as grid is the stored answer; a translated label shown in a report is for reading. Keep those two representations distinct when merging data.

Make a permission plan before inviting people

KoboToolbox has project-level settings and permissions for named users. A data collector may need Add submissions without access to all existing records. A supervisor may need View and Validate submissions. An analyst may need View submissions and downloads. A manager may need to edit the form or settings. Give each role the access it needs for its work.

Permissions can imply other rights, so verify the actual behavior with a second test account. Row-level permissions can restrict access by submitting user or by a condition such as an area code.

Public form access and public data access are different

A form can be configured for submissions without a username and password. Separately, a project can allow anyone to view the form or view submitted data. Public submission access may be suitable for some respondent surveys; public data access is a much larger disclosure. Check both settings before sending any link.

Test the effective access

1. Write down the owner and each collaborator's role.
2. In a practice project, inspect Settings → Sharing without changing your live projects.
3. Check the form's anonymous submission setting and the project's public data setting separately.
4. Use a signed-out browser window or a test account to verify what an outsider or collector can actually see.
5. Record the results in your launch checklist.

Project history can help trace changes, but it does not replace a permission test. A person with Manage project can alter access, so assign it deliberately.

Test permissions with each role

Write down what each person must do before granting access. For the school pilot, a collector needs to submit records, a supervisor needs to see and resolve assigned data issues, and an analyst needs a controlled export. The project owner should retain authority over form changes and permissions. The exact permission switches depend on the chosen workflow, so test them with separate accounts on the same server.

A sharing dialog shows intended permissions; a sign-in test shows effective permissions. Have each tester perform the task under their own role and record the outcome. If the form is available without sign-in, test separately whether its submissions can be viewed without sign-in. Recheck after any permission change.

Choose the data source from the update need

Look up a school from a CSV

Prepare schools.csv with one row per school and a unique ID. Upload it to the project's media. A calculation can retrieve the school name when the collector enters the ID:

school_id,school_name,province
S001,Example School A,p01
S002,Example School B,p02

pulldata('schools', 'school_name', 'school_id', ${school_id})

Test an ID that matches, one that does not and one that has leading zeros. KoboToolbox treats pulled CSV values as text; convert a value before numeric arithmetic. Updating the CSV or form requires a controlled refresh on field devices.

Linked projects are a different source

Dynamic data attachments use submissions from a KoboToolbox parent project rather than a standalone CSV. This can help a follow-up form use baseline data. It is not instantaneous in every setting. Current documentation describes an online sync delay and requires the child project to download parent data before offline use. Design a fallback for a newly submitted parent record that has not reached the field device yet.

Exports and REST Services solve other problems

A synchronous export provides a configured CSV or XLSX view for Excel, Power BI or another authorized client. Use XLSX if repeat data is needed. The JSON API is for scripts that handle raw records. REST Services can send a newly created submission to an external service; KoboToolbox says later edits to that submission are not sent by this feature. External systems therefore need a reconciliation plan if corrections matter.

Plan how reference data reaches offline devices

A school lookup is only useful when the device has the reference file or linked data before the visit. Decide who owns the list, when it changes, and what should happen if an ID is absent. For an XLSForm CSV attachment, check the column headers, the exact filename in the expression, and whether the new file reached the deployed form. Then download or refresh the form on the intended device while online and test an ID that exists and one that does not.

For a dashboard or scheduled extract, define the same timing question: how often does it refresh, how is a failed refresh noticed, and who can access its output? Store credentials outside a shared form workbook and give each integration only the access it needs.

The specification

A school facilities team will visit a fixed sample of schools. The form must identify the school, record whether the representative agrees to answer, collect facilities information only after consent, inventory classrooms, and produce an XLS export that an analyst can check. Use invented IDs and locations for this capstone.

The completed example workbook contains one implementation. Review it after your own attempt. Its counts and wording are for training, not an approved study instrument.

Starter XLSFormCompleted example XLSForm

Part A: build and preview

1. Copy the starter XLSForm and give the copy a new filename.
2. Complete the identification and consent rows. Confirm that select_one yn finds its choices.
3. Add a group for the respondent and facilities section. Put ${consent} = 'yes' on the begin_group row.
4. Add electricity and facilities lists with stable codes. Add facility_other with selected(${facilities}, 'other').
5. Add classroom counts with . >= 0 and . <= 120 and a clear error message.
6. Add classrooms_total as a calculation. Decide how it behaves when one count is blank and record that decision.
7. Add the rooms repeat. Keep room_code unique within one school visit.
8. Save, upload and preview the workbook. Fix any validation error before deployment.

Part B: run six test paths

Write down actual results. A test case passes only when the displayed form and stored values match the expected result.

Part C: deploy and collect

1. Deploy the practice form after the preview passes.
2. Submit at least two synthetic records through the web form, including one refusal.
3. If Android is available, download the form in KoboCollect, complete a record offline, reconnect, send it and confirm server receipt.
4. Record the deployed version and collection method for each test.

Do not use existing real projects or submissions. Do not delete anything from your KoboToolbox account to make room for this practice.

Part D: review the export

1. Download XLS and identify the main sheet and rooms sheet.
2. Check the number of main submissions and repeat rows against your test log.
3. Inspect school_id, consent codes, optional blanks and classroom totals.
4. Use _index and _parent_index to link a classroom row to its visit.
5. Write one query for any unexpected value or missing row. Keep the unedited export as evidence.

Part E: hand the project to a field team

Write a one-page handoff note with:

• Project server, owner, form version and date deployed.
• List of question names and stored codes that must remain stable.
• Collection mode, authentication method and device update procedure.
• Permission plan for enumerators, supervisor and analyst.
• Test matrix with results and open issues.
• Export procedure and daily QA checks.

A project is ready for a small pilot when the critical paths pass on the intended devices, test submissions reach the server, exports contain the expected structure, and access has been checked with the relevant user roles.

Independent extension

When the core capstone works, add a prepared school list with pulldata(), or add a province-to-municipality choice filter. Document how the reference data reaches a collector who will work offline. Test a missing school ID or a province with no matching municipality.