Forms and XLSForm · Joripo documentation

A form is an Excel workbook (.xlsx, or .xlsm) in the XLSForm layout that SurveyCTO and ODK both use. Joripo reads SurveyCTO's spelling of every column directly, so a workbook written for SurveyCTO is uploaded as it is, with nothing to translate first.

The three sheets

survey: one row per question, note, group or calculation, in the order the form runs.
choices: the answer lists that choice questions refer to, one row per choice (list_name, name, label). Any other column you add is kept, so a choice_filter can refer to it.
settings: one row describing the form: at least form_id and version, usually form_title, and optionally default_language and instance_name.

Survey columns

Column	What it does
`type`	The question type: `text`, `integer`, `select_one yn`, `begin group`, and so on. See Question types. `select_one yn` and `select one yn` are both accepted.
`name`	The variable name: the column it becomes in the data. A name may be used once per form.
`label`, `hint`	What the enumerator reads. `label:English`, `label:Bangla` and so on give one translation per language.
`required`, `required message`	`yes` stops the enumerator going on without an answer; the message replaces the default one.
`relevance`	When the question is asked (ODK's `relevant` is read the same). A question not asked is left out of the submission and exported blank.
`constraint`, `constraint message`	A condition the answer must meet.
`calculation`	On a `calculate`, the value. On a question the enumerator may edit, SurveyCTO's calculated default: given the first time the question is shown, then theirs to keep or change.
`default`	A fixed starting value.
`appearance`	How the question is drawn. See Appearances.
`read only`	`yes` shows the value without letting it be changed.
`choice_filter`	Which choices to offer, from an expression over the choices sheet's columns.
`repeat_count`	A fixed or computed number of times a repeat group runs.
`media:image`, `media:audio`, `media:video`	A file shown or played with the question; attach the file to the form.
`parameters`	Extra settings for a type; for GPS, `capture-accuracy=` and `warning-accuracy=` in metres.
`disabled`	`yes` removes the row from the form entirely, as SurveyCTO does.

SurveyCTO's publishable, response_note, minimum_seconds and comments columns are kept in the workbook and have no effect on the form, because they govern SurveyCTO's own pipeline rather than the questionnaire.

Languages

Write each translation in its own column (label:English, hint:Bangla). The form opens in the default_language from the settings sheet, and the enumerator or respondent can switch language while filling it. Exports can carry the labels of any one language, or of every language at once.

Formatting in labels

Labels, hints and choices may hold the HTML SurveyCTO authors use: , , ,   and . It is drawn as formatting on the phone, in web forms and in the tester. Write it exactly as you would for SurveyCTO.

Uploading a form

On Design, use Upload form definition (or a + bar in the list) and drop the workbook. Add the form's attachments in the same upload if it has any: images, audio, video, preload .csv files, or a .zip of them. An .xlsx data file is converted to the .csv the form reads.

Joripo then checks, compiles and deploys the workbook in one step:

It reads every sheet and checks every row: types, names, expressions, choice lists, settings.
It compiles the workbook into an XForm.
Where the server can, it opens the compiled form in Joripo's own form engine, headlessly, and refuses a form that engine could not open: such a form would not open on phones or in web forms either.
It makes the new version live in one step, with its attachments. If anything fails, nothing that was already live changes.

If something is wrong, the message lists every problem with its sheet, row and column, the upload panel stays open with your files still chosen, and nothing is deployed. Warnings (things to check before collecting, such as a preload file nothing has attached) do not stop the deployment. A program that uploads with Accept: application/json gets the full list of problems as structured data.

There are no drafts. Every successful upload is deployed at once: there is no separate "save as draft" step. Test a new version in the tester before sending phones out with it, and upload a test copy under another form ID if you want to try changes without touching the live form.

A form's address on the server

Each form is identified by its form_id, which never changes once the form exists. Its title can change from version to version; nothing is stored by title, so renaming moves nothing. Uploading a workbook whose form_id is already a form in the workspace from the top-level Upload is refused, so that nothing is replaced by accident: use that form's own Upload button to publish a new version. See Versions and form files.