Users — Portal documentation

Access

How an administrator reaches the screen, and what has to be true for it to open.

Element What it decides Permissions

Navigation Side menu → Users, under Admin. Me:users.access

Header

What the band states about accounts before anything below it is actionable.

Element What it decides Permissions

Title “Users”, with the number of active accounts as subtitle. —

Main actions

What belongs to the page rather than to one account.

Element What it decides Permissions

Add user Opens the invitation for a new account. The role is asked before anything optional, because it decides what the account can do. Me:users.invite

Form · Add user

What an invitation needs before it is sent.

Field Validations Permissions

First name Required. Trimmed, and refused if only spaces are left. —

Last name Required. Trimmed, and refused if only spaces are left, so a single-word legal name fits in either field. —

Email Required. A valid address, and unique across the organisation — checked by the server, which answers on the field itself. It becomes the sign-in, and the invitation goes to it. —

Role Required. One of the roles the organisation has set up, and only those the person inviting may grant. Me:users.rolesRemote:grantable_roles

Locations Required. One or more of the organisation's locations. Client:multi_location

Send invite now Optional. On by default; off creates the account without an email, for someone who starts later. —

Filters

Which accounts the list holds.

Element What it decides Permissions

Role Narrows the list to the roles chosen. —

Department Narrows the list to the departments chosen. —

Status Invited · Active · Deactivated. —

Search Finds accounts by name or email, within what the filters already hold. —

Table

What one account shows in a row.

Element What it decides Permissions

Selection Choosing rows replaces the column headings with the bulk band: deactivate, or change the role of, every account chosen. Me:users.bulk

Name Full name, with the email below it. —

Role What the account can do. —

Department Where the account works. —

Last active When the account last signed in. —

Status Invited · Active · Deactivated. —

At phone width Rows become cards with the name, the role and the status; department and last active move into the account. —

Row actions

What can be done to one account without leaving the list.

Element What it decides Permissions

Edit Opens the account's name, role and department to change. —

Reset credentials Asks to confirm, then signs the account out everywhere and sends a link to set a new password. Me:users.reset_credentials

Deactivate Asks to confirm, naming the account, then removes its access. Set apart at the end of the menu. Me:users.deactivateData:can_deactivate

Form · Edit user

What an account's details need before they are saved.

Field Validations Permissions

First name Required. Trimmed, and refused if only spaces are left. —

Last name Required. Trimmed, and refused if only spaces are left. —

Role Required. Only the roles the person editing may grant. Me:users.rolesRemote:edit_role

Department Optional. —

Errors

What the screen can refuse, and what the administrator sees when it does.

Error When What the reader gets

The role can no longer be granted The invitation is sent after what the person inviting may grant has changed.
POST /api/v2/users/invite → 403 A notice above the form, and the role list reloads with what can be granted now.

The list does not load Asking for the accounts fails.
GET /api/v2/users → any failure A notice in place of the table, with a way to try again.

The account is already deactivated Someone else deactivated it first.
DELETE /api/v2/users/:id → 404 A notice, and the account shows as Deactivated once the list reloads.

API calls

What the screen asks the backend for, and what makes it ask.

Endpoint Params Trigger

POST/permissions actionsubject_id Before a role list opens, in the invitation or in an edit, to learn which roles this person may grant. The answer depends on who is asking, so the session alone cannot decide it.

POST/api/v2/users/invite first_namelast_nameemailrole_idlocation_idssend_invite On sending the invitation.

GET/api/v2/users pageper_pageroledepartmentstatusqsort When the screen opens, and on every filter, search, sort or page change. The list is never narrowed in the browser, so the table shows what the query returned.

POST/api/v2/users/:id/reset-credentials — On confirming Reset credentials.

DELETE/api/v2/users/:id — On confirming Deactivate, once per account in a bulk deactivation.

PATCH/api/v2/users/:id first_namelast_namerole_iddepartment_id On saving an edit, or a bulk role change. Only the fields that changed are sent, so two people editing different fields of one account do not overwrite each other.