XLSForm

See also

XLSForm is a standard for designing forms in Excel. XLSForms are simple to get started with and can represent complex forms.

XLSForms can be created and edited by any application that works with .xlsx documents. This means that they are portable and can leverage many useful features commonly available in spreadsheet applications such as formulas, comments, and document versioning.

Many users choose to use Google Sheets or Excel for the web so that they can collaborate on or publicly share their forms. The best way to get started with XLSForm is with the tutorial below.

If you are more adventurous, you can skip the tutorial, make a copy of the form template below, and learn to design your form that way.

Once your form has been designed, you can upload the XLSForm directly to your ODK Central server. If your ODK server does not have the latest XLSForm features or you need to temporarily preview a form in a browser, try XLSForm Online.

The ODK documentation shows all form design examples as XLSForms and describes how XLSForms are used by ODK tools. The All Widgets form has examples of all of the different user-visible question types.

The survey sheet

At minimum, an XLSForm has a sheet named survey to describe the types and order of fields in a form. It must have these three columns:

  • type: the type of the field represented by each row. Supported types and how they are displayed are described here.

  • name: the name of the field represented by each row. This name will be used in your data results. It may not contain spaces and must start with a letter or underscore. Use a short and descriptive name. For example: date_of_birth.

  • label: the user-visible question text for the field represented by each row. For example: When was ${first_name} born? This text can reference other fields or have translations.

The survey sheet can have many other columns to represent different question types and form logic. You can see the most commonly-used columns in this template.

The choices sheet

If you have multiple choice questions, you will also need a choices sheet to specify choices for those questions. It must have these three columns:

  • list_name: The unique ID that identifies a group of choices. It may not contain spaces and must start with a letter or underscore. Use a short and descriptive name. For example: yes_no_maybe.

  • name: the name of the field represented by each row. It may not contain spaces and must start with a letter or underscore. This name will be used in your data results so it's best to use a short and descriptive name (e.g., y for Yes and n for No).

  • label: the user-visible text for the choice represented by each row. For example: Yes, No, and Maybe. This text can reference other fields or have translations.

Choices with the same list name are considered part of a related set of choices and will appear together for a question. This also allows a set of choices to be reused for multiple questions (for example, yes/no questions).

The settings sheet

You should also include a settings sheet to uniquely identify your form definition and its current version. We recommend specifying at least the following columns:

  • form_title: The title that will be displayed by tools that list this form.

  • form_id: The unique ID that identifies this form to tools that use it. It may not contain spaces and must start with a letter or underscore. Use a descriptive name no more than 64 characters. For example: bench_inventory_2021.

  • version: The unique version code that identifies the current state of the form. A common convention is to use a format like yyyymmddrr. For example, 2017021501 is the 1st revision from Feb 15th, 2017.

  • instance_name: An expression that will be used to represent a specific filled form created from this form definition. For example, concat(${first_name}, "-", ${age}). Learn more.

Other available columns are:

  • default_language: Specifies the default language name in a form that has multiple defined languages. For more information on using multiple languages, refer to multi-language forms.

  • public_key: This attribute is necessary for enabling encryption. It represents a base64-encoded RSA public key. The corresponding private key will be required for decrypting submissions and should not be included in the form definition.

  • auto_send: When set to true, any finalized forms will be automatically sent as soon as a connection becomes available. If present, it will override the app-level Auto send setting.

  • auto_delete: When set to true, successfully submitted forms will be immediately deleted from the device. If present, it will override the app-level Delete after send setting.

Naming filled forms

In an XLSForm's settings sheet, you can add an instance_name column and specify an expression to use a specific filled form's contents in its name. This name will be shown in several places to help guide data collection and analysis. You should pick a name that uniquely identifies the filled form and the data it had captured. For example:

  • If a single filled form represents data about a real-world thing like a person or park bench, your instance_name expression should include some information to uniquely identify the thing like the person's name or the park bench's location and current status.

  • If a single filled form represents data about an observation, consider including the date and time of the observation in the instance_name expression.

  • If your form definition includes a repeat, consider including the repeat count in the instance_name expression.

Filled form names in Collect

Each filled form is identified by its instance_name value in Collect's Drafts, Ready to send and Sent lists.

In workflows where forms have to be be filled in multiple different steps, a useful instance_name expression will make it much easier to find which filled form to edit. If forms only have to be edited under certain conditions (e.g. not all household members were available), you can include this status in the instance_name.

In the Sent list, instance_name can be helpful to identify which data collection tasks have been completed. For example, if a data collector needs to interview 25 specific people and the instance_name for each filled form identifies the respondent, they can go to Sent to verify which subset of interviews they have already completed.

A sent form's instance_name is maintained after it is deleted. This makes it possible to confirm what work has been completed even if submissions are configured to delete after send. However, it does mean sensitive data should be avoided in instance_name.

The instance_name is also used to identify filled forms in Collect's filled form map.

Filled form names in Central

Each submission in Central has its own detail page which provides basic information about the submission, an activity history of action and discussion on that submission.

The title at the top is pulled from the instance_name and it makes navigation much easier to have friendly names at the top of the page and in the web browser title and tab.

The entities sheet

Entities let you share information between forms so you can collect longitudinal data, manage cases over time, and support other complex workflows.

Review the Entities page to learn more about what Entities are and how to use them.

Did this page help you?

Selecting an option will open a 1-question survey

👍 Yes 👎 No