XLSForm reference

This page is for the person building an XLSForm workbook to import into CommonLynk. It lists what the platform reads from each sheet, what every column and key does, what is not supported and what happens to it, and where CommonLynk differs from ODK, KoboToolbox and SurveyCTO.

The lists of question types, functions, columns, keys and scoring values on this page are generated from the platform itself, so they describe what it does today. For a walk through building a form, see Building a form and Skip logic and scoring.

What CommonLynk reads from a workbook

A plain ODK, KoboToolbox or SurveyCTO workbook imports as it is. Everything CommonLynk adds is optional, and it is named the way those tools name their own additions, so a CommonLynk workbook still opens in them.

On the survey sheet, the value of each of these columns is applied to the question. The label, hint and constraint message columns take one column per language, as Building a form describes.

• appearance
• calculation
• choice_filter
• constraint
• constraint_message
• default
• hint
• label
• name
• read_only
• relevant
• repeat_count
• required
• type

Every other column with a value on a question row is kept on that question: it is shown on the form’s Design tab, listed on the import page as kept but not applied, and written back when you export the form. Nothing you write is lost on the way through.

A question’s name is its identity: skip logic refers to it, an update matches on it, and every export column is named after it. Write it in lowercase letters, digits and underscores, starting with a letter; capitals are lowered and any other character becomes an underscore. Every row needs a name except a note.

Three routes, three meanings

A workbook identical to the one a form was last built from is not applied again unless you tick “Apply this workbook again” on the update: without it, the import says that nothing was changed. Tick it when the platform’s importer has improved and the form should be rebuilt from the same file. Importing the same workbook twice into one activity or project creates nothing the second time.

Question types

Each question type in CommonLynk, the XLSForm types that import as it, and what an export writes for it.

A type built in CommonLynk only is exported as the nearest XLSForm spelling. Imported again as a new form, that spelling becomes the type it imports as, not the original: a Likert question becomes a choice question, a phone number a short text. An update of a form that holds responses never changes the type of a question it already has.

Groups and repeats open and close with these types, written with an underscore or a space:

• begin_group · begin group
• end_group · end group
• begin_repeat · begin repeat
• end_repeat · end repeat

Any other type is skipped and named on the import page, and the row is not kept. That includes these metadata types:

• start
• end
• today
• deviceid
• username

CommonLynk records when each response was started and submitted, and who submitted it, without them.

The commonlynk sheet

An optional sheet of two columns, with the headings below, one key per row. A value the platform does not recognise is reported on the import page and left unset for you to choose in the form’s settings; it is never guessed at.

• setting
• value

These keys are recognised as your own notes. They are listed on the import page and never applied, and any other key you add is treated the same way:

• domains
• id
• indices
• instance_name
• items_per_domain
• note
• notes
• purpose
• purpose_ar
• purpose_en
• respondent
• version

The form types, for the key form_type:

The respondent groups, for the key subject:

The cl:: question columns

Optional columns on the survey sheet, one value per question. They apply only on a row marked as scored: points or an answer key on a row that is not scored is kept and reported, not applied.

Any other column beginning cl:: is kept, listed as kept but not applied, and written back on export, like any column the platform does not interpret.

Scoring

A form is scored by one of four methods. Set it with the scoring key, or in the form’s settings.

The scoring key also takes these words, and each becomes a method:

How a question adds to a Rating Sum

A choice question adds the value of the chosen option divided by the highest value among its options, times its points. An option named 0, 1, 2 and so on has that value; an option named yes has the value 1 and one named no the value 0, matched on the name and never on the label. With options 0 to 2 and 6 points, the question adds 0, 3 or 6. When the points equal the highest option, the question adds the plain value: nine questions with options 0 to 3 and 3 points each add up to between 0 and 27.

A typed question, which is a number, or a Likert or Rating question built in CommonLynk, adds its value as typed, times its points. So the same points mean two things: the most a choice question can add, and a multiplier on a typed one.

A scored choice question whose options are neither numbers nor yes and no cannot be scored, and neither can a multiple choice question: the import names it, and it adds nothing.

In Rating Sum and Rating Average, a question with no answer, whether skipped or left empty, is left out of both the score and the maximum.

scale_max on the commonlynk sheet is the most the whole form can score. It is a check, not a setting: the import adds up what the scored questions can score and reports a difference. It is not the rating scale maximum in the form’s settings, which is the top of one question’s scale and is used for a typed question with no maximum of its own.

An update that changes how a form scores rescores its complete responses in the same import, and any indicator figure computed from them is marked to be computed again.

Domains and reverse questions

A domain is a label on questions, not a group: two questions in one group may count towards different domains. Name a scored question’s domain in cl::domain. Every complete response then stores a score for each domain beside the form score; it is shown on the response, exported beside the score and written back on export, and an indicator can read one domain instead of the total.

A commonlynk_domains sheet gives each domain its label: one row per domain, with key, a label column per language and, optionally, max, the most the domain can score, which is checked like scale_max and never stored. Without the sheet, a domain is labelled from its group when that group holds only that domain; otherwise the import asks for a label. With the sheet, a cl::domain naming a key it does not list is reported and not applied.

A question marked reverse runs the other way: a higher answer is better. It counts only in its own domain, reported beside the form score, and is never added to it or taken from it, so a declared total is never exceeded. If every scored question is reverse, they make up the form score themselves.

In the example above, the risk questions make up the form score out of 28, and the protective questions, marked reverse, are reported beside it out of 8.

Expressions

The relevant, constraint and calculation columns are read by one grammar, and evaluated the same way on the page, on a phone offline and on the server. A function accepted in one column is accepted in the other two.

An expression may use other answers, numbers, quoted text, arithmetic, comparisons, and, or and brackets. In a constraint, a dot stands for the answer being checked. An unanswered question makes a calculation blank, not 0; to count a blank as 0, say so with if().

• ${name}
• 'text'
• + - * div mod
• = != > >= < <=
• and or
• ( )
• .

These are the functions it evaluates:

In a calculation only, this shape gives the label of the option chosen in a question, as ODK writes it:

• jr:choice-name(${q}, '${q}')

Reading a repeat as a whole

count(), sum(), min(), max() and avg() read every entry of a repeat from anywhere in the form. Name the repeat itself to count its entries, or a question inside it for its values. Only entries that hold at least one answer count. With no entries, count() and sum() give 0 and the others a blank; one blank or non numeric value makes sum(), min(), max() and avg() blank. The value follows entries as they are added or removed, and is computed again on submission. An aggregate must name a repeat or a question inside one; any other name is reported and stored blank.

To count the entries that match a condition, write a calculation inside the repeat that is 1 for a match and 0 otherwise, and sum() it after the repeat:

Dates

today() is the day the answer is given, in the workspace’s time zone. Two dates written as year, month and day, including a date written in quotes, compare correctly as earlier and later.

Offline, today() is the day the response was collected, not the day it reached the server. A response already submitted is never checked again against a later day. If a phone did not report the day, a constraint that uses today() is not judged: the answer is kept and the question is flagged for review. In the default column, today() is the day the form is opened.

What is not supported, and what happens to it

A fragment the platform does not evaluate is named on the import page, the rest of the row still applies, and your original text is kept on the question and written back when you export the form. Until you change it, what happens depends on the column:

• in relevant, the question always shows;
• in constraint, that part is not enforced, though a simple bound in the same constraint still is;
• in calculation, the value is stored blank.

Unsupported structure is reported too: a repeat inside a repeat is merged into the one around it, a relevant on a begin_repeat row is not applied, and appearance minimal on a select_multiple is drawn as a checkbox list. The differences below say why.

Differences from ODK, KoboToolbox and SurveyCTO

Where a workbook that works in those tools behaves differently here, and why. Each is deliberate unless its row says otherwise.

Offline behaviour that changes how you build

• A constraint is checked on the phone as the answer changes, before the next screen and on submission, offline too, and the server checks it again.
• today() follows the rules under Dates: offline it is the day the answer was given, never the day the response reached the server.
• Only the columns a form’s pulldata() reads travel to collecting phones with the form. Attach the dataset before publishing: a form whose dataset is missing cannot be published or set active. Replacing the dataset publishes a new form version, and responses keep the data they were filled with.
• A question named after a profile field of the form’s respondent group is prefilled from the respondent’s record, and that field then travels to collecting phones for everyone on the list. Rename the question if it does not need prefilling.