Library locking with XLSForm¶

Last updated: 25 Nov 2025

The KoboToolbox Library allows you to store and manage templates, questions, and blocks for reuse across multiple projects. Form templates in the Library can be shared with team members to ensure consistent form design and reduce duplication of effort.

Library locking expands on this by allowing you to control how templates can be edited once they are used to create new projects. With locking, you can specify which questions, groups, or form-level settings can be changed. This is especially useful for large teams working from a shared template, where certain elements need to remain fixed while others can be adapted to local needs.

This article explains how library locking works, the types of restrictions you can apply, how to configure them in XLSForm, and how to upload locked XLSForms to KoboToolbox.

Note: Library locking is not currently supported in the KoboToolbox Formbuilder. To use this feature, you must implement it via XLSForm and then upload your XLSForm to KoboToolbox.

To learn more about downloading and editing your form as XLSForm, see Using XLSForm with KoboToolbox.

Introduction to Library locking¶

Library locking controls how much of a form can be edited when a project is created from a Library template. Restrictions are defined in your XLSForm before uploading the form.

When you create a locked template and share it through your Library:

Users can make local adjustments where restrictions allow.
Locked elements appear grayed out in the Formbuilder.
A message above the form indicates which restrictions are active.

Library locking is separate from project permissions, which control what different users can do inside a deployed project.

Note: Library locking restrictions apply only in the Formbuilder when a project is created from a locked template. If the XLSForm is downloaded and edited in a spreadsheet, the restrictions will not prevent changes. However, incorrect or invalid locking configurations may cause errors when the form is re-uploaded.

Library locking is configured in three XLSForm worksheets:

survey worksheet: To apply restrictions to specific questions and groups.
settings worksheet: To apply form-level restrictions and set the kobo--lock_all option.
kobo–locking-profiles worksheet: To define profiles that group related restrictions.

Together, these worksheets let you define which parts of a form remain fixed and which parts can be edited when the template is used to create new projects.

Types of restrictions¶

Library locking supports restrictions at three levels: question, group, and form. Restrictions define what can and cannot be edited when a project is created from a locked template.

In addition, a global setting (kobo--lock_all) can be used to lock the entire form.

Question-level restrictions¶

Question-level restrictions apply to individual questions. You can apply the following restrictions to questions in your XLSForm:

Restriction	Description
`choice_add`	Prevents adding new choices to a select question.
`choice_delete`	Prevents deleting existing choices in a select question.
`choice_value_edit`	Prevents editing a choice name (or XML value).
`choice_label_edit`	Prevents editing a choice label.
`choice_order_edit`	Prevents reordering choices in a select question.
`question_delete`	Prevents deleting a question.
`question_label_edit`	Prevents editing a question label or hint.
`question_settings_edit`	Prevents editing question settings, including the question name. This does not include skip logic or validation criteria.
`question_skip_logic_edit`	Prevents editing skip logic conditions.
`question_validation_edit`	Prevents editing validation criteria.

Group-level restrictions¶

Group-level restrictions apply to question groups. You can apply the following restrictions to groups in your XLSForm:

Name	Description
`group_delete`	Prevents deleting a group.
`group_split`	Prevents ungrouping questions.
`group_label_edit`	Prevents editing the group label.
`group_question_add`	Prevents adding or cloning questions inside a group.
`group_question_delete`	Prevents deleting questions from within a group.
`group_question_order_edit`	Prevents reordering questions inside a group.
`group_settings_edit`	Prevents editing group settings, including the group name. This does not include skip logic.
`group_skip_logic_edit`	Prevents editing skip logic for a group.

Form-level restrictions¶

Form-level restrictions apply to the whole form. You can apply the following restrictions to your XLSForm:

Name	Description
`form_appearance`	Prevents changes to the form theme.
`form_replace`	Prevents replacing the form in KoboToolbox using the Replace Form option.
`group_add`	Prevents creating new groups.
`question_add`	Prevents adding or cloning questions in a group.
`question_order_edit`	Prevents reordering questions.
`language_edit`	Prevents editing translations.
`form_meta_edit`	Prevents editing metadata questions.

Locking an entire form¶

The kobo--lock_all setting can be added to the settings worksheet of your XLSForm.

If set to TRUE, the entire form is locked and all granular restrictions become redundant.
If set to FALSE (or omitted), only the restrictions defined in your locking profiles are applied.

settings worksheet

kobo–lock_all
TRUE
settings

Configuring library locking in XLSForm¶

Defining locking profiles¶

Locking profiles are sets of restrictions that can be applied to questions, groups, or the whole form. They are defined in the kobo–locking-profiles worksheet of the XLSForm, and then applied in the survey and settings worksheets. You can create as many profiles as you need.

To define locking profiles in your XLSForm:

Create a new worksheet named kobo–locking-profiles.
Add a restriction column, which can include any restrictions from the tables above.
Create one column per profile (e.g., profile_1, profile_2).
In the cell corresponding to a restriction and a profile, include the keyword locked to assign a restriction to a profile.

kobo–locking-profiles worksheet

restriction	profile_1	profile_2	profile_3
choice_add	locked	locked
choice_delete		locked
choice_value_edit	locked	locked
choice_label_edit		locked
choice_order_edit		locked
question_delete	locked	locked
form_appearance			locked

Applying profiles in the survey worksheet¶

Once you have defined locking profiles in the kobo–locking-profiles worksheet, you can apply these profiles to specific questions and groups. To apply profiles in the survey worksheet:

Create a column named kobo–locking-profile in the survey worksheet
For each question or group you want to restrict, define the locking profile in the kobo--locking-profile column.

survey worksheet

type	name	label	kobo–locking-profile
select_one country	country	Select your country	profile_1
select_one city	city	Select your city	profile_2
survey

Applying profiles in the settings worksheet¶

In addition to applying profiles to questions and groups in the survey worksheet, you can also apply a profile with form-level restrictions in the settings worksheet.

To apply a profile to the settings worksheet:

Create a kobo–locking-profile column in the settings worksheet.
Specify the profile that you would like to apply.

settings worksheet

kobo–locking-profile
profile_3
settings

Note: Restrictions cannot be applied in the choices worksheet. All choice-related restrictions are defined at the question or group level in the survey worksheet.

Using locked templates in KoboToolbox¶

Once you have created and uploaded a locked XLSForm as a template, you can use it to build new projects in KoboToolbox.

Importing a locked XLSForm into your Library¶

To import a locked XLSForm into your Library:

Go to your Library from the left menu bar in KoboToolbox.
Click NEW, then select Upload.
Upload your XLSForm file, and select Upload as template.

Upload template

The template will appear in your Library with a lock symbol, showing that it contains restrictions.

Creating a project from a locked template¶

Go to the Projects home page.
Click NEW, then select Use a template.
Choose the locked template you want to use.
Continue creating your project as usual.

Use template

When you open the project in the Formbuilder:

A message will appear above the first question summarizing restrictions.
Locked questions, groups, or form-level settings will appear grayed out.
Each locked question shows which profile has been applied in its Settings > Locked Features.

Locked library

Troubleshooting¶

Troubleshooting recommendations

If library locking does not work as expected, try the following:

Make sure the form was uploaded as a Template in the Library.
Check the settings worksheet in your XLSForm. If kobo--lock_all is set to true, the whole form will be locked.
Verify that all restriction names in the kobo--locking-profiles worksheet are valid. Only predefined restriction names are supported.
Ensure that the column kobo--locking-profile exists in the survey or settings worksheet and that the profile names match those defined in the kobo--locking-profiles worksheet.

Caveats and limitations

Restrictions are enforced only in the Formbuilder. If the XLSForm is downloaded and edited directly in a spreadsheet, restrictions do not prevent changes.
Restrictions apply only to projects created from locked templates. Templates and surveys in the Library remain editable.
Only surveys and templates support locking. If you upload a locked XLSForm as a question or block, the locking is ignored.
Some spreadsheet editors automatically convert two single dashes -- into a long dash (—). Always use two single dashes in names such as kobo--locking-profiles.

What do you need help with?