Managing Users in Central

There are two types of user accounts in ODK Central: Web Users and App Users.

  • Web Users have accounts on the Central management website. These accounts are global across all projects on the server. They can log into the web interface and perform administrative actions like user management, form upload and management, and submission data viewing and download.
  • App Users can use mobile data collection apps like ODK Collect to connect to Central. App Users are limited to a single project at a time. Once connected through the app, they will be able to see the list of forms, download the ones they need, and upload completed submissions to those forms.

You will need both types of users in order to run a successful data collection project: a Web User must upload a valid form definition, an App User must upload submissions to it from their mobile device, and the Web User will then be able to see those submissions in the web interface and download them for analysis.

Web User Roles

Central features Role-based User permissioning. In the current release of Central, we provide two roles: Administrator and Project Manager. In future releases, more default roles will be added and eventually you will be able to define your own roles as you see fit.

By default, Central roles are configured to allow the following:

Action Administrator Project Manager
Projects
Create x  
Edit Details x x
Archive x x
Project Forms
Create x x
List All x x
Edit Attachments x x
Edit Details x x
Set State x x
Delete x x
Project Form Submissions
Create (API) x x
View & Download x x
OData Access x x
Project App Users
Create x x
List All x x
Revoke Access x x
See Code x x
Web Users
Create x  
List All x  
Edit Details x  
View Email Addr. x  
Revoke Password x  
Delete x  
Server Configuration
Setup Backups x  
Stop Backups x  

Managing Web Users

You can make Users into Administrators from the site-wide Users panel, and you can assign them as Project Managers on the Settings tab within the Project.

To manage web users, navigate to ‣ Users ‣ Web Users at the top of the Central management website. You should see a listing of users that looks like this:

../_images/web-users-listing.png

Creating a Web User

To create a new Web User, click on the Create web user button on the right side of the Web Users listing page. You will see a popup that looks like this:

../_images/web-users-create.png

To create a new Web User, input the email address of the person who should receive access. Press Create once you are satisfied with the email address.

That email account will shortly receive an email with the subject line "ODK Central account created". If you do not see the email, check your spam folder. In the email, there will be a link which will allow the recipient to set a password for their new account, after which they will be able to log in.

The link is only valid for 24 hours. If 24 hours pass and it has not been used, you should use the Reset Password tool to send them a new link.

Newly created Web Users are only able to log in and edit their profile information. In order to give them access to do useful work on the server, please read the following section.

Assigning a site-wide Web User Role

As mentioned under Web User Roles above, there are two Roles you may assign to Web Users in the current release of ODK Central: Administrator and Project Manager. Administrators may perform any action on the system, while Project Managers may perform any action on their assigned Project(s).

To learn how to assign a Project Manager role, please see the Managing Project Managers section in the Projects guide.

To assign an Administrator role, navigate to the Web Users administration panel. There, you should see a table like this one:

../_images/web-users-role.png

Under the Sitewide Role column in the table, you will see dropdown inputs with the options Administrator and None. To make a Web User an Administrator, change the dropdown next to their name to Administrator. You will see the page think for a moment, and then it will inform you that the action is done. To take away Administrator rights from a Web User, change the dropdown to None.

You will not be able to change your own Role in the system. To change your own Role, you will need to get somebody else to log in and change it for you.

Resetting a Web User password

Any user may request a reset of their own password by using the link at the bottom of the login screen:

../_images/web-users-self-reset.png

After submitting the reset form, the user should receive an email with the subject line "ODK Central account password reset". If they cannot find it, they should check their spam folder. When resetting a password this way, the user's current password continues to function until they actually use the link in the email to set a new one.

We also provide a separate way for administrators to directly reset any Web User's password in the administration panel for two reasons:

  1. In case the user's password has been stolen and needs to be disabled immediately.
  2. In case the user does not know how to do this themselves.

With the administrative reset, the user's password stops working immediately and they will be completely unable to log in until a new one is set. They will receive an email with instructions and a link on how to do this exactly as shown above. To perform the administrative reset, navigate to the Web Users listing page, and use the Actions menu at the right side of the table:

../_images/web-users-admin-reset.png

Retiring a Web User

When you retire a Web User, their login access will be revoked and they will be immediately signed out everywhere. They will disappear from the Web Users management list, but any records that trace their actions (submission uploader or form creator name, or audit log action initiator, for example) will still show their information.

If a retired Web User attempts to reset their password, they will receive a special email explaining that their account has been retired.

To retire a Web User, find them on the Web User administration panel, and open the Actions menu:

../_images/web-users-retire.png

From here, select Retire User and follow the on-screen instructions.

Managing App Users

App Users never gain any access to the management website: they do not have email addresses or passwords associated with their account, only a nickname so you can tell which is which. Once a Web User creates an App User within some project, a configuration QR Code will be generated which will grant a mobile device access to that project as that App User. Access can be revoked at any time, and Web Users can see which App Users uploaded which submissions.

In the current alpha release of ODK Central, all App Users can download any Open form and upload submissions to any non-Closed form within their project. Future versions will feature more options to restrict certain App Users to certain forms.

To manage App Users, navigate to the project whose App Users you wish to manage, and then click on the App Users tab just below the project name. You should see a listing of users that looks like this:

../_images/app-users-listing.png

Creating an App User

To create a new App User, click on the Create app user button on the right side of the App Users listing page. You will see a popup that looks like this:

../_images/app-users-create.png

Once you provide a nickname for the user (usually the name of the data enumerator who will carry the mobile device works well), click Create. The user will be created, and you will see a screen that looks like this:

../_images/app-users-created.png

That App User has now been created and granted access to use their mobile device to list, download, and submit to all available forms within their project. To do so, however, their mobile device will have to get set up with this new account. That is what the QR Code you see on this screen is for. Read on to the next section to find out how to use it.

Configuring an App User mobile device

A mobile device will need to be configured to access your ODK Central server as a particular App User in order to gain access to the forms and upload submissions within their project. This is done by way of the Collect Settings QR Code.

The QR Code contains information about how to find your ODK Central server, and how to prove to the server that the mobile device belongs to a valid App User. In future versions of ODK Central, it will be possible to specify other settings to be imported to the device as well.

There are two ways to access the QR Code for an App User. The first is in the second step of the App User creation wizard. Please find the second screenshot in the previous section to see what this looks like. If you close out of this wizard, you can still access the QR Code by clicking on the See code link in the listings table:

../_images/app-users-code.png

If instead of a See code link you see text that says Access revoked, that App User no longer has access to the server. Create a new App User if you need a new QR Code.

Once you have found the QR Code, you will be able to use it to configure ODK Collect. Please see the section on importing settings into Collect to learn how to do this.

Revoking an App User

You may wish to revoke an App User's access, for instance if their QR Code has been stolen or if they have left the organization. To do so, navigate to the App Users listing page, and use the Actions menu at the right side of the table:

../_images/app-users-revoke.png

App Users whose access has been revoked will still appear in the App Users listing table, and will still be visible as the submitter of any submissions they uploaded. However, they no longer have a valid QR Code with which they can configure an ODK Collect installation, and any mobile devices already configured with their code will no longer have access to the project.