- Please note that some permissions imply others. For example, if Alice has Edit submissions only from specific users only for Bob, then this implies that Alice also has View submissions only from specific users for Bob. + When certain permissions are granted, other permissions are also automatically granted. For example, if a user is granted Edit submissions only from specific users, then the user will also be granted the permission View submissions only from specific users.
-## Configure your Account Settings: +## Configure your Project Settings for row level permissions -By default, users must be authenticated by entering their KoboToolbox username and password before they can submit data to a deployed form. This is important for row-level permissions to work correctly. To confirm that the form authentication requirement is active, open the project and navigate to the **FORM** tab. Under the **Collect data** section, ensure that the “Allow submissions to this form without a username and password” setting is turned off. +Before you can set user-based row-level permissions for your project, the setting “Allow submissions to this form without a username and password” must be turned off. Data submissions must be associated with usernames to apply user-based row-level permissions. Learn more about [requiring passwords for accessing Enketo web forms](https://support.kobotoolbox.org/managing_permissions.html#requiring-passwords-for-accessing-enketo-web-forms). - + -## Managing Row Level Permissions: +## User-based row-level permissions -In this example, three user accounts are presented to demonstrate how the -feature works. _kalyan1_ represents the _admin_ or _owner_ of the survey project -(as seen in the previous images). _kalyan2_ and _kalyan3_ represent different -users receiving permissions. **Require authentication to see forms and submitted -data** has been checked for _kalyan1_. +User-based row-level permissions allow you to share your project data with another KoboToolbox user and permit them to only view, edit, delete, or validate data submitted by specific users. -### View submissions only from specific users: +This can be useful when you need a user to have access to only the submissions they sent. For example, you may want to allow enumerators access to only their own submissions for verification and/or editing. User-based permissions can also be helpful when you want to share data with specific stakeholders and only allow them to access data submitted by specific users. -_kalyan1_ can share row-level permissions with _kalyan2_, where they can _view_ -submissions made from _kalyan2_. +| User-based row-level permissions | Description | +| :------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------- | +| **View submissions only from specific users** | Users with this permission can **view data** submitted by specific users | +| **Edit submissions only from specific users** | Users with this permission can **edit data** submitted by specific users | +| **Validate submissions only from specific users** | Users with this permission can validate data submitted by specific users | +| **Delete submissions only from specific users** | Users with this permission can **delete data** submitted by specific users | - +### To add user-based row-level permissions: +- Open your project and navigate to the **SETTINGS** tab +- Go to the **Sharing** section +- Click **Add user** and enter the username of the user you would like to share the project with and set permissions for +- Select the user-based permissions you want to allow (view, edit, delete, and/or validate) -Row-level permissions can also be set for _kalyan3_ such that they can only -_view_ submissions made by _kalyan2_. + - +- Below each permission, enter the usernames for the users whose submissions you are granting the user access to +- Click **Grant permissions** to save your row-level permissions settings -### Edit submissions only from specific users: +Once you have saved your permissions, the user you have shared the project with will be able to view, edit, validate, or delete the project data submitted by the specified usernames, depending on which permissions you selected. -In this case, _kalyan1_ can share row-level permissions with _kalyan2_, where -they can _view_ and _edit_ submissions made from _kalyan2_. ++ To ensure data privacy, please make sure to confirm the username of the user you are granting permissions. +
- +### User-based row-level permissions example -As with view permissions, the same can be done for _kalyan3_ to only _view_ and -_edit_ submissions from _kalyan2_. +In the example below, the user **kobocourses** is sharing project data with the user **alex**. User-based permissions have been created so user **alex** can only access project data submitted by **alex** and by the user mario. These permissions allow **alex** to view, edit, and validate only the data submitted by **alex** and **mario**. - + -### Delete submissions only from specific users: +## Condition-based row-level permissions -In this case, _kalyan1_ can share row-level permissions with _kalyan2_, where -they can _view_ and _delete_ submissions made from _kalyan2_. +Condition-based permissions allow you to grant access to project data based on a response to a question on your form. When you create a condition-based permission for a user, they will only have access to specific submissions based on the response to a specific question on the form. - +This can be useful for managing access to data in shared projects. A condition-based permission allows you to grant permissions to other users based on the conditional **XML value** response submitted to a specific question. For example, if your form includes a question about marital status, you can create a condition-based permission so that the user you are granting permission to only has access to specific submission data if the response is “married”. -The same can be done for _kalyan3_ to only _view_ and _delete_ submissions from -_kalyan2_. +| Condition-based row-level permissions | Description | +| :------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------- | +| **View submissions based on a condition** | Users with this permission can **view data** if the response to a question meets the specified condition | +| **Edit submissions based on a condition** | Users with this permission can **edit data** if the response to a question meets the specified condition | +| **Validate submissions based on a condition** | Users with this permission can validate data if the response to a question meets the specified condition | +| **Delete submissions based on a condition** | Users with this permission can **delete data** if the response to a question meets the specified condition | - ++ These condition-based row-level permissions are now available for sharing project data. This new feature adds four new levels of permissions to the existing row-level permissions. Previously, row-level permissions only included user-based permissions. +
-### Validate submissions only from specific users: +### To add condition-based permissions: +- Open your project and navigate to the **SETTINGS** tab +- Go to the **Sharing** section +- Click **Add user** and enter the username of the user you would like to share the project with and set permissions for +- Select the condition-based permissions you want to allow (view, edit, delete, and/or validate) +- Below each permission you have selected, choose the question and enter the response condition that must be met -In this case, _kalyan1_ can share row-level permissions with _kalyan2_ where -they can _view_ and _validate_ submissions made from _kalyan2_. + - +- Open the **Select…** drop-down menu to display the full list of form questions and select the question that should be used to filter which submissions are shared with the user +- On the right-hand side of the **equals sign (=)**, enter the response’s conditional **XML value** for the condition that must be met +- Click **Grant permissions** to save your row-level permissions settings -The same can be done for _kalyan3_ to only _view_ and _validate_ submissions -from _kalyan2_. +Once you have saved your permissions, the user you have shared the project with will be able to view, edit, validate, or delete project data submissions that have the required response to the specified question, depending on which permissions you selected. - ++ For Date questions, the response value must be written in the format `YYYY-MM-DD` (e.g., `1974-12-31`). -## Troubleshooting: + +For Select One and Select Many questions, the response value must be written using the unique XML value, not the label (e.g., `first_grade` rather than `First grade`). +
+ +### Condition-based row-level permissions example -### Scenario 1: +In the example below, the user **kobocourses** is sharing project data with the user **kobosouth**. Condition-based permissions have been created so **kobosouth** only has access to data submissions where the `region` indicated by a respondent is `south`. -When submitting data, a dialogue requesting user credentials will appear if the authentication requirement is active and the **“Allow submissions to this form without a username and password”** setting is turned off. + -Enter your KoboToolbox username and password and, if the account has **Add submissions** permission, you will be able to submit data to the server. +These permissions allow **kobosouth** to view, edit, delete, and validate only the data submissions where the `region` indicated by the respondent is `south`. - + + +## Troubleshooting: + +1. When submitting data, a dialog box requesting user credentials will appear if the authentication requirement is active and the “Allow submissions to this form without a username and password” setting is turned off. + +Enter your KoboToolbox username and password. You will be able to submit data to the server if you have **Add submissions** permission for the project. + +To ensure data security, it is not advised to share your administrator sign in credentials with other users when managing your project. You can create multiple enumerator accounts and share those credentials with your team.
-### Scenario 2: +2. If your user-based permissions are not functioning as expected, confirm that the form authentication requirement is active. To confirm this setting is active, open the project and navigate to the **FORM** tab. Under the **Collect data** section, ensure that the “Allow submissions to this form without a username and password” setting is turned off. + +User-based permissions will not apply to any submissions collected before the “Allow submissions to this form without a username and password” setting was turned off, because these submissions would not be associated with a username. -Before you can set row-level sharing permissions for your project, the setting “Allow submissions to this form without a username and password” must be turned off _before_ data is collected. Otherwise data collected before this setting is turned off will not be -restricted as expected. +By default, project settings now require users to sign in to collect submissions. Learn more about requiring passwords for accessing Enketo web forms.