- 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 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.
## Configure your Account Settings: @@ -34,6 +40,34 @@ Learn more about [requiring passwords for accessing Enketo web forms](https://su  +## User-based row-level permissions + +| User-based row-level permissions | Condition-based row-level permissions | +| :------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------- | +| View submissions only from specific users | _View data_ submitted by a subset of defined data entry users. | +| Edit submissions only from specific users | _Edit data_ submitted by a subset of defined data entry users. | +| Delete submissions only from specific users | _Delete data_ submitted by a subset of defined data entry users. | +| Validate submissions only from specific users | Validate data submitted by a subset of defined data entry users. | + +### User-based row-level permissions example + +TBD + +## Condition-based row-level permissions + +| User-based row-level permissions | Condition-based row-level permissions | +| :------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------- | +| View submissions only from specific users | _View data_ submitted by a subset of defined data entry users. | +| Edit submissions only from specific users | _Edit data_ submitted by a subset of defined data entry users. | +| Delete submissions only from specific users | _Delete data_ submitted by a subset of defined data entry users. | +| Validate submissions only from specific users | Validate data submitted by a subset of defined data entry users. | + +### Condition-based row-level permissions example + +TBD + + + ## Managing Row Level Permissions: In this example, three user accounts are presented to demonstrate how the @@ -92,17 +126,16 @@ from _kalyan2_. ## Troubleshooting: -### Scenario 1: +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. -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. You will be able to submit data to the server if you have **Add submissions** permission for the project. -Enter your KoboToolbox username and password and, if the account has **Add submissions** permission, you will be able to submit data to the server. - - +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 linked to 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](https://support.kobotoolbox.org/managing_permissions.html#requiring-passwords-for-accessing-enketo-web-forms).
From 0dbd452ae527838eaeae24b154ec3d9869374146 Mon Sep 17 00:00:00 2001 From: Mae-Lin DeLange <92045096+maedelange@users.noreply.github.com> Date: Thu, 2 May 2024 09:03:17 -0400 Subject: [PATCH 2/5] Update row_level_permissions.md Add extend partial row permissions and update images --- source/row_level_permissions.md | 132 ++++++++++++++++---------------- 1 file changed, 65 insertions(+), 67 deletions(-) diff --git a/source/row_level_permissions.md b/source/row_level_permissions.md index 62c91a0d..2822b5fd 100644 --- a/source/row_level_permissions.md +++ b/source/row_level_permissions.md @@ -18,111 +18,109 @@ To use row-level permissions, go to your project **SETTINGS**, click on the **Sh ### Available row-level permissions -As of August 2021, the management of project permissions has been extended to -allow for a total of four **row-level** access permissions that include: - -| User-based row-level permissions | Condition-based row-level permissions | +| [User-based](#user-based-row-level-permissions) row-level permissions | [Condition-based](#condition-based-row-level-permissions) row-level permissions | | :------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------- | -| View submissions only from specific users | _View data_ submitted by a subset of defined data entry users. | -| Edit submissions only from specific users | _Edit data_ submitted by a subset of defined data entry users. | -| Delete submissions only from specific users | _Delete data_ submitted by a subset of defined data entry users. | -| Validate submissions only from specific users | Validate data submitted by a subset of defined data entry users. | +| View submissions only from specific users | View data based on a condition | +| Edit submissions only from specific users | Edit submissions based on a condition | +| Validate submissions only from specific users | Validate submissions based on a condition | +| Delete submissions only from specific users | Delete submissions based on a condition |- When certain permissions are granted, other permissions 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). - + ## User-based row-level permissions -| User-based row-level permissions | Condition-based row-level permissions | -| :------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------- | -| View submissions only from specific users | _View data_ submitted by a subset of defined data entry users. | -| Edit submissions only from specific users | _Edit data_ submitted by a subset of defined data entry users. | -| Delete submissions only from specific users | _Delete data_ submitted by a subset of defined data entry users. | -| Validate submissions only from specific users | Validate data submitted by a subset of defined data entry users. | - -### User-based row-level permissions example - -TBD +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. -## Condition-based row-level permissions +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. -| User-based row-level permissions | Condition-based row-level permissions | +| User-based row-level permissions | Description | | :------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------- | -| View submissions only from specific users | _View data_ submitted by a subset of defined data entry users. | -| Edit submissions only from specific users | _Edit data_ submitted by a subset of defined data entry users. | -| Delete submissions only from specific users | _Delete data_ submitted by a subset of defined data entry users. | -| Validate submissions only from specific users | Validate data submitted by a subset of defined data entry users. | - -### Condition-based row-level permissions example +| **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 | -TBD +### 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) + +- 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 -## Managing Row Level Permissions: +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 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_. - -### View submissions only from specific users: ++ To ensure data privacy, please make sure to confirm the username of the user you are granting permissions. +
-_kalyan1_ can share row-level permissions with _kalyan2_, where they can _view_ -submissions made from _kalyan2_. +### User-based row-level permissions example - +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**. -Row-level permissions can also be set for _kalyan3_ such that they can only -_view_ submissions made by _kalyan2_. + - +## Condition-based row-level permissions -### Edit submissions only from specific users: +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. -In this case, _kalyan1_ can share row-level permissions with _kalyan2_, where -they can _view_ and _edit_ submissions made from _kalyan2_. +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”. - +| 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 | -As with view permissions, the same can be done for _kalyan3_ to only _view_ and -_edit_ submissions from _kalyan2_. ++ 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. +
- +### 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 -### Delete submissions only from specific users: + -In this case, _kalyan1_ can share row-level permissions with _kalyan2_, where -they can _view_ and _delete_ 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 - +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. -The same can be done for _kalyan3_ to only _view_ and _delete_ submissions from -_kalyan2_. ++ For Date questions, the response value must be written in the format `YYYY-MM-DD` (e.g., `1974-12-31`). - + +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`). +
-### Validate submissions only from specific users: +### Condition-based row-level permissions example -In this case, _kalyan1_ can share row-level permissions with _kalyan2_ where -they can _view_ and _validate_ submissions made from _kalyan2_. +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`. - + -The same can be done for _kalyan3_ to only _view_ and _validate_ submissions -from _kalyan2_. +These permissions allow **kobosouth** to view, edit, delete, and validate only the data submissions where the `region` indicated by the respondent is `south`. - + ## Troubleshooting: @@ -136,6 +134,6 @@ Enter your KoboToolbox username and password. You will be able to submit data to 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 linked to a username. +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.By default, project settings now require users to sign in to collect submissions. Learn more about [requiring passwords for accessing Enketo web forms](https://support.kobotoolbox.org/managing_permissions.html#requiring-passwords-for-accessing-enketo-web-forms).
From 88d9b18804a7e2df129366ad6bb985a9f421aa36 Mon Sep 17 00:00:00 2001 From: Mae-Lin DeLange <92045096+maedelange@users.noreply.github.com> Date: Thu, 2 May 2024 09:04:31 -0400 Subject: [PATCH 3/5] Rename Allow_submissions_without_ username_password.gif to Allow_submissions_without_username_password.gif Update file name --- ...Allow_submissions_without_username_password.gif} | Bin 1 file changed, 0 insertions(+), 0 deletions(-) rename source/images/row_level_permissions/{Allow_submissions_without_ username_password.gif => Allow_submissions_without_username_password.gif} (100%) diff --git a/source/images/row_level_permissions/Allow_submissions_without_ username_password.gif b/source/images/row_level_permissions/Allow_submissions_without_username_password.gif similarity index 100% rename from source/images/row_level_permissions/Allow_submissions_without_ username_password.gif rename to source/images/row_level_permissions/Allow_submissions_without_username_password.gif From 8ff6a3d22473d3b350959ed180bbbb946fec4fed Mon Sep 17 00:00:00 2001 From: Mae-Lin DeLange <92045096+maedelange@users.noreply.github.com> Date: Thu, 2 May 2024 09:04:44 -0400 Subject: [PATCH 4/5] Update row_level_permissions.md From f056ca674a1f693d05bafec4a4ceb270a8cc2dca Mon Sep 17 00:00:00 2001 From: James KigerBy default, project settings now require users to sign in to collect submissions. Learn more about [requiring passwords for accessing Enketo web forms](https://support.kobotoolbox.org/managing_permissions.html#requiring-passwords-for-accessing-enketo-web-forms).
+By default, project settings now require users to sign in to collect submissions. Learn more about requiring passwords for accessing Enketo web forms.