Managing user roles
In SurveyCTO, a user's role governs their level of access throughout the system. Every SurveyCTO subscription includes five pre-configured global roles, to which users can be assigned:
Data collection only: Permission to see and collect data for all forms.
Data manager (collection and download): Permission to see and collect data for all forms, plus permission to view and download data for all forms and datasets.
Form and data manager (can administer forms and datasets): Permission to see and collect data for all forms, permission to view and download data for all forms and server datasets, and permission to add, edit, or delete all forms and datasets.
Form, data, and user manager (can also administer users): Permission to see and collect data for all forms, permission to view and download data for all forms and server datasets, permission to add, edit, or delete all forms and datasets, and permission to add, edit, or delete users.
Administrator (full access, plus subscription management): Full administrator permission server-wide, including permission to manage the SurveyCTO subscription.
These are called "global roles" because they apply server-wide, to all forms and datasets in all groups.
If you have a single-team subscription, these global roles are almost certainly all you need. If your server is shared by multiple teams, however, you will want to use custom user roles to manage users' access to various team groups. (Learn more about teams and team groups in Managing teams.)
In addition to the global roles listed above, any user in the Administrator (full access, plus subscription management) global role can define one or more custom roles that control user access in a more fine-grained manner. Users can then be assigned to these custom roles.
Typical approach to managing roles
If you have a single-team subscription, there's really no need to manage roles at all: your users can all be placed in one of the five global roles. If you have multiple teams, however, then one or more users will have to be in the global Administrator role – but then most (if not all) other users will probably be placed in custom roles. Custom roles allow you to define exactly which permissions users should have to all shared groups, and what permissions they should have to each team group.
For each team on a multi-team server, you will typically want to have a set of roles that parallel the global roles. For example, if you had a team named "Ethiopia", you might create the following custom roles for that team:
Ethiopia - Data collection only: Same permissions as the global role, but only for the "Ethiopia" team group.
Ethiopia - Data manager: Same permissions as the global role, but only for the "Ethiopia" team group.
Ethiopia - Form and data manager: Same permissions as the global role, but only for the "Ethiopia" group – plus maybe read-only access to All shared groups.
Ethiopia - Form, data, and user manager: Same permissions as the global role, but only for the "Ethiopia" group – plus maybe read-only access to All shared groups.
Which roles get which access to All shared groups depends a bit on how you want to use those shared groups. Many SurveyCTO administrators use shared groups for global form libraries and shared datasets, and so form managers in all teams will be granted read-only access to those shared groups.
In order to simplify your task when adding new teams to SurveyCTO, you'll have the chance to bulk-copy either global roles or an existing team's roles whenever you add a new team. That way, you can get your new team going right away, without having to individually create every new role.
In addition to totally-global roles and purely-team-specific roles, you are likely to want some custom roles that are in between those two extremes. For example, you may have some global or regional managers, or some individuals with highly-specific access. You can create your own custom roles for all such cases. For example:
Global form and dataset manager: Full access to all team groups, plus full access to All shared groups. Users in this role would, for example, be able to help manage your global form library (if that's how you were using shared groups), or assist any team with their work.
East Africa - Form and data manager: Full access to all team groups within the East Africa region, read-only access to All shared groups.
Southern Africa - Form and data manager: Full access to all team groups within the Southern Africa region, read-only access to All shared groups.
Individual role - John Doe: Specific access to specific teams, based on John Doe's unique role within the organization.
When naming your custom roles, it would be helpful if you followed the convention here, where team-specific roles are named "Team name - role name" and individual-specific roles are named "Individual role - user name". If you do, SurveyCTO will more easily recognize those roles and might assist you a bit more effectively when you copy or delete them.
Additional security settings
In addition to controlling permissions related to forms and datasets, roles can help control the manner in which users are able to connect to your server more broadly. Each role on your server has the following options:
Require external authentication. Enable this setting if you want to make sure all users in a role are authenticated with your own provider. See the topic on configuring external authentication for more information.
Allow server API access. Use this setting to control whether or not users in a given role can use documented APIs to programmatically fetch forms and data from your server. If disabled, users in that role will only be able to access the server by using one of the following trusted clients: the server console, SurveyCTO Desktop, SurveyCTO Collect (all of which must be on version 2.71 or later). Please note: while this option is enabled, users in the role will be able to download datasets that are attached to forms they can see via API, even if they do not have the can see server datasets permission.
Ignore mobile security settings. If you've configured any mobile security settings on your server, you can allow certain roles to bypass them by enabling this setting.
Managing custom user roles
For each custom role, permissions can be granted regarding user management as follows (each being a checkbox for enabled or disabled, granted or not-granted):
Can add users. Permission to add new users, provided that they are in roles with access strictly less than or equal to this role. (No user can add a user with access greater than their own.)
Can edit users. Permission to edit users, provided that they are in roles with access strictly less than or equal to this role. (No user can edit – or even see! – a user with access greater than their own.)
Can delete users. Permission to delete users, provided that they are in roles with access strictly less than or equal to this role. (No user can delete – or even see! – a user with access greater than their own.)
Hub Access. Permission to see the Discover tab and utilize the SurveyCTO Hub.
Hub Import. Permission to install items from the SurveyCTO Hub into the server console.
A series of additional permissions can then be granted for all shared groups (together), and for each team group (individually). Each permission is represented by a checkbox that you check to grant permission or un-check to withhold permission:
Can see forms. The basic ability to see and download forms, form definitions, and attached files – including attached datasets. If data is attached to a form, assume that anybody with "can see forms" permission can see that data.
Can submit responses (requires "Can see forms"). The ability to actually submit data for forms, via web forms, SurveyCTO Collect, or SurveyCTO Desktop.
Can view form data in aggregate (requires "Can see forms"). The ability to view field and relationship summaries in the Data Explorer. While the user interface will not allow somebody with only this permission level to download raw data or view full submission details, a skilled hacker with this level of permission (plus any necessary private key) could access the raw data.
Can view individual responses (requires "Can view data in aggregate"). The ability to zoom in on individual submissions in the Data Explorer. While the user interface will not allow somebody with only this permission level to download raw data, a skilled hacker with this level of permission (plus any necessary private key) could access the raw data.
Can download data (requires "Can view individual responses"). The ability to download and export data.
Can modify or delete data (requires "Can view individual responses"). The ability to approve, reject, comment on, correct, or purge data, as well as the ability to accept incomplete submissions.
Can add forms (requires "Can see forms"). The ability to add new forms.
Can edit forms (requires "Can see forms"). The ability to edit forms, upload new versions, re-order forms within the group, and change the configuration of forms (including, e.g., publishing to datasets or the cloud for users who also have "Can download data" permission).
Can delete forms (requires "Can see forms"). The ability to delete forms.
Can see server datasets. The ability to see (and download) server datasets. Please note the following exceptions:
- Anybody who has access to see a form can technically see any datasets attached to that form. However, as long as they aren't allowed to use public storage in SurveyCTO Collect for Android, they will not be able to access the entire dataset directly; they will only be able to see the data that you pull into the form itself (using the pulldata() or search() functions). See the topic on managing device security for info on disabling public storage, and other ways to safeguard your datasets.
- Anybody who has access to submit data can see the "cases" dataset configured for their user role.
- Anybody whose role is configured to allow API access will be able to download server datasets directly via API.
Can add server datasets (requires "Can see server datasets"). The ability to add server datasets.
Can edit server datasets (requires "Can see server datasets"). The ability to edit server datasets (title and settings), re-order datasets within the group, and edit the configuration for server datasets (including, e.g., publishing to the cloud).
Can delete server datasets (requires "Can see server datasets"). The ability to delete server datasets.
Can modify or delete server dataset data (requires "Can see server datasets"). The ability to modify or delete server dataset data.
Can move forms in or out of group (requires "Can see forms"). The ability to move forms in or out of the group (to successfully move a form from one group to another, a user must have this permission in both groups).
Can move datasets in or out of group (requires "Can see datasets"). The ability to move datasets in or out of the group (to successfully move a dataset from one group to another, a user must have this permission in both groups).
Can move groups in or out of group (requires "Can see forms" AND "Can see datasets"). The ability to move sub-groups in or out of the group (to successfully move a sub-group from one group to another, a user must have this permission in both groups). Note that only global administrators can move top-level groups or move a sub-group such that it becomes a top-level group.
Can add groups. The ability to add new sub-groups. Note that only global administrators can add top-level groups.
Can edit groups. The ability to edit sub-groups (their titles). Note that only global administrators can edit top-level groups.
Can delete groups. The ability to delete sub-groups. Note that only global administrators can delete top-level groups.
When you create a new custom role, you will specify the permissions as well as a title, short description, unique ID, and dataset ID for case management. The title you choose will dictate how the role is shown (and chosen) in the Your users section of the Configure tab. The short description is meant to help you to keep better track, internally, of additional details about the role. The unique ID, like a form or dataset ID, must be short, without spaces or punctuation, and cannot be edited later; it, like the cases dataset ID, is only used in case-management applications (see the help topic on case management for more).
Some tips:
There are two ways to add a new custom role: starting from scratch by clicking Create role, and starting from an existing role by clicking Duplicate for an existing role. Because a role's permissions need to be set group-by-group, the easiest approach is often to duplicate an existing role, then make changes from there.
When you're adding or editing a role, note that each permissions tab includes a Copy from option that lets you easily copy another role's permissions. So, for example, you could duplicate an existing role, then flip through the permissions tabs that require different permissions, copying permissions from one of the pre-configured global roles. You can always, then, tweak the individual permission checkboxes as desired.
After you create a new user role, click the Preview option under that role to quickly see how the server console appears and operates for users assigned to that role. That way, you can double-check that the permissions are set correctly.
If you have a single-team server, then all forms and datasets that reside outside of any group are still considered, for purposes of permissions, to reside in a shared group. I.e., the All shared groups permissions apply to forms and datasets outside any groups.
See Keeping your data secure for a broader discussion of SurveyCTO data security, including a list of best practices.
