Building a form

Forms is where you design a questionnaire of your own and then collect answers to it. You build the form once, publish it, and your team can then fill it in inside the workspace while people outside your organisation answer the same form from a public link.

Starting a new form

A new form begins empty. You add its questions one at a time in the builder, on the form's Design tab, or you import a whole questionnaire from an XLSForm workbook.

1. Open Forms from the workspace menu and create a form.
2. Open the new form and choose Build.
3. Add a question, choose its type, fill in its settings and save it. Repeat until the questionnaire is complete.

Building needs the Forms edit permission. The builder sits at an address of this shape: /forms/<id>/build/

The twenty one question types

A question is one of twenty one types, and the type decides both what the person answering sees and what the platform stores. Choose the type first, because it governs which of the settings below appear.

There is also a note, which shows text such as an instruction or a consent paragraph and records no answer.

A note can be shown with the question that follows it: when editing the note, tick Show this note with the next question. The note then appears in the same card as that question, also when the form shows one screen at a time, and a screen reader reads it out with the question. A note with a display condition of its own, a note in a repeat group, and a note followed by another note keep a card of their own.

What you can set on a question

Every question carries a label and, if you want one, a line of help text. Both are text, so both are entered once for each of your workspace languages. Beyond that, the settings you see depend on the type you chose:

• Required, so the form refuses to move on until the question is answered.
• Choices, added and removed as rows. Each row carries a label the person reads and a value the platform stores.
• A minimum and a maximum value, for questions that take a number.
• Labels for the bottom and the top of a scale, so a rating reads as something more useful than a bare number.
• A variable name. It is required, and it must begin with a lowercase letter and then use only lowercase letters, digits and underscores, for example household_size
• The file types you will accept, for upload questions.
• A formula, for a calculated field whose answer the platform works out instead of asking for it.
• Validation rules, including a regular expression and the error message shown when an answer does not match it.
• The rows and the scale of a matrix, the items to be put in order for a ranking, and the parent question for a cascading select.

Who a form belongs to, and who it is about

A form's scope says what it belongs to: one activity, or a whole project. Its respondent source says who it is about: the participants of its activity, the participants of the activity chosen at each response, a list of people you choose, an uploaded roster, or no respondent list. Once the form holds a real response, neither can change, and nor can its respondent group: the rest of the Settings page still saves, and the save says which of the three it left as they were. A form someone has opened but not yet answered holds no response.

A form with no respondent list is about nobody on a register. It opens at its first question, online and on a phone, with no search, no scan and nobody to register: use it for an anonymous survey, or for anything that is not about a person, such as market prices. Registering people from a form needs a respondent group, so a form that declares none registers nobody.

One form for many events. A form that is the same at every event, such as a training satisfaction survey, belongs to the whole project and takes the source "Participants of the activity chosen at each response". When the form opens, the collector chooses the activity, from that project's activities only, and the list of people narrows to that activity's participants. Every response keeps its activity, so one dataset carries an activity column instead of one form for each event. Offline, the activity is chosen on the phone and sent with the response.

Where a project names an operating area on its Countries tab, the place picker on a form collected for that project offers those places first, under "Where this project works", and the rest of the country after them. Nothing is hidden: every place stays available, and what you may record is unchanged. For a response collected at an activity, the order follows that activity's country.

Each response also records the country it is about: its activity's, else its respondent's, else a place answer's, else the collector's default country. It is updated whenever the response changes, and the Country column and filter on the records list use it.

Grouping questions into sections

Select the questions that belong together, by ticking them or with a Ctrl or Cmd click, and choose Create section with selected. The section takes a heading of its own, in each of your workspace languages, and its settings open so you can decide how it behaves. Move to section adds questions to a section that already exists.

A section can show all of its questions on the same screen, it can repeat, and it can carry a condition of its own. Removing a section asks whether to ungroup it, which keeps every question and removes only the section, or to delete everything in it. Deleting questions that already hold answers asks you to confirm how many answers go with them.

Repeating a section

A repeating section asks its questions once for each entry, for example once for each child in a household. You choose how many entries there are: the person filling the form adds them as they go, a fixed number, as many as the answer to an earlier question, or as many as an expression gives. A section shown on one screen cannot contain a repeat.

A repeating section that already holds entries cannot be switched off or ungrouped, so entries that have been collected are never lost that way.

A calculation can also read a repeating section as a whole, with one of the functions below, for example how many people a roster lists, or a year of monthly revenue. To count only the entries that match a condition, such as how many of the workers are women, add a calculation inside the section that is 1 for a matching entry and 0 otherwise, and total it. The value follows the entries as they are added or removed, and is worked out again when the response is submitted.

• count() the number of entries
• sum() the total of one of its questions
• min() the smallest value of one of its questions
• max() the largest value of one of its questions
• avg() the average of one of its questions

Importing an XLSForm

A form can also be built from an XLSForm workbook, the format KoboToolbox, ODK and SurveyCTO use. Import it from the Design tab, and upload the workbook again later to update the form. The import reports anything it could not apply, names a group too long for one phone screen and any rule that reads a later question, and keeps the columns it does not interpret so that they are exported back unchanged.

Each upload that is applied is recorded with its file name, who uploaded it and when, and the workbook itself can be downloaded again. The template offered on the import page carries a GUIDE sheet that explains what the importer accepts.

Forms → Import XLSForm creates a new form, and is linked from the forms list and its empty state. To replace a form you already have and keep its responses, use Import XLSForm on that form’s own Design tab, which matches your questions by their name column and updates them in place.

The form’s title is stored in the language the workbook declares, so an English title never lands in the Arabic slot.

A workbook may carry a commonlynk sheet (its bilingual title, the register the form is about, how it is scored) and cl:: columns: one set for scoring each question, and cl::bound, which shows a note with the question after it. CommonLynk reads these and applies the ones it recognises; a value it does not recognise is reported and left for you to set, never applied silently. They are optional, so a plain Kobo, SurveyCTO or ODK file imports unchanged. Exported, a bound note is an ordinary note that keeps its cl::bound marker, so importing the file again restores it.

A pattern (regex) must check an answer the same way on the phone as on the server, so a pattern the phone cannot check is refused when the form is written: in the question editor, and when a workbook is imported, naming the question and the part of the pattern. The cases are possessive quantifiers (a++), atomic and conditional groups, \N{…}, octal escapes such as \0, and a negated escape inside square brackets such as [\D]; inside a relevant, a calculation or a constraint joined with or, inline flags such as (?i) are refused too. Rewrite the pattern without them.

A rule on a date can compare it with the day the answer is given, using the function below, so a date can be kept out of the future, or the date of a next visit kept after today. A response collected offline is checked against the day it was collected, not the day it reached the server, and a response already submitted is never checked again against a later day. If a device did not report when it collected a response, the answer is kept and flagged for review rather than refused.

• today() the day the answer is given, in the workspace's time zone

Putting the questions in order

Each question card has a drag handle. Take hold of it, drag the card up or down to where you want it, and the new order is saved the moment you drop it. There is no separate save step for the order, and no numbering to keep in step by hand.