TestLink provides four screens for managing users, roles, and role assignments. All four are accessible from the System section of the left navigation sidebar and share a common tab bar for quick navigation between screens.

Prerequisite: You must be logged in as admin (or a user with the mgt_users and/or user_role_assignment rights).

1. User Management
2. Role Management
3. Assign Test Project Roles
4. Assign Test Plan Roles
5. Role Hierarchy
6. Common Workflows

Path: System > User Management
URL: gui/templates/usermanagement/usersView.html
Purpose: Create, edit, enable/disable, and delete user accounts.

Legacy gui/templates/dashio/usermanagement/usersView.tpl showed a "Login [...] Manage user" form below the buttons that posted to usersEdit.php?doAction=edit&login=<login>, where initializeGui() resolves the login to a user id via tlUser::doesUserExist() and opens the edit screen — or shows login_does_not_exist for an unknown login.

The modern screen reimplements this in the toolbar:

1. Type a full login into the lookup box (placeholder = Login, maxlength 30, required).
2. Click Manage user → the BFF resolves it (GET /api/users/index.php?login=<login>) and opens the Edit User modal for that user.
3. Unknown login → localized alert "Login ___ does not exist" (user.loginDoesNotExist, present in all 10 locale bundles); empty input is blocked client-side (HTML5 required), and an empty parameter to the API returns 400 login_required.

The two legacy columns were re-added to the DataTable (same order as legacy lib/usermanagement/usersView.php:168-180): Locale sits between Role and Status, Expiration Date between Status and Actions. The BFF list route (api/users/index.php) already returned locale and expirationDate for every user and now additionally computes expirationDateFormatted with the same call legacy uses (localize_dateOrTimeStamp(null,null,'date_format',…)), so e.g. 2026-12-31 renders as 31/12/2026. Users without an expiration date show an empty cell.

• Edit (pencil icon): Opens the edit modal to change user details and global role
• Reset password (key icon, issue #884): Generates a new random password for the user, then either emails it (default password_reset_send_method = send_password_by_mail) or returns it to be displayed on screen (display_on_screen). Shown only for users whose effective authentication method has allowPasswordManagement = true (legacy usersEdit.tpl:169-178 parity)
• Enable/Disable (toggle icon): Toggles the user between Active (1) and Inactive (0) states
• Delete (trash icon): Soft-deletes the user (sets active = 2, hidden from UI but retained in database). Not available for the admin user

A second toolbar row sits under the Create/Export toolbar — the port of the legacy ExtJS grid toolbar (lib/usermanagement/usersView.php:215-217 + lib/functions/exttable.class.php:96-124). Five buttons:

The BFF list route now returns the raw role_id, user_id and is_special fields per user so the technical columns are populated client-side.

The legacy edit screen had a dedicated Reset password form (gui/templates/dashio/usermanagement/usersEdit.tpl:339-356 → usersEdit.php:222-269 createNewPassword() → lib/functions/users.inc.php:167-225 resetPassword()). The modern screen ports it to a row action backed by a new BFF route:

• UI (gui/templates/usermanagement/usersView.html): a key icon in the Actions column per row, gated by canResetPassword(u) against the /meta/authentication payload (the user's own authentication value, falling back to the configured default method — same rule as the legacy template). Clicking shows a confirm dialog, then POST /api/users/index.php/{id}/reset-password; the outcome is shown as an alert: the bundle message for sent-by-mail, user.passwordShownOnScreen with the fresh password for display-on-screen, or the localized error.
• BFF (api/users/index.php, POST /users/{id}/reset-password), mirroring the legacy createNewPassword() flow step by step:
  1. tlUser::isPasswordMgtExternal($u->authentication) → refuse with password_mgmt_external (defense-in-depth; the UI hides the action anyway);
  2. config_get('demoMode') → refuse (demo_reset_password_disabled);
  3. reads password_reset_send_method; unless it is display_on_screen, validates config_get('smtp_host') with Zend_Validate_Hostname(ALLOW_ALL) → invalid_smtp_hostname on failure;
  4. calls the legacy resetPassword($db,$userId,$method) (email send via email_send() when by-mail) and on success logs logAuditEvent(tls('audit_pwd_reset_requested',$login),'PWD_RESET',$id,'users').
• Config: config_get('password_reset_send_method') decides send-by-mail vs display-on-screen. With the default unconfigured SMTP host the by-mail path returns the same message as legacy: "Password Reset can not be done. Reason: SMTP Hostname seems to be invalid".
• New i18n keys in all 10 locale bundles: user.resetPassword, user.resetPasswordConfirm, user.passwordResetSent, user.passwordShownOnScreen, user.passwordResetInvalidSmtp, user.passwordResetDenied, user.resetFailed, user.passwordResetError.

The legacy edit screen offered a Generate a new key button (gui/templates/dashio/usermanagement/usersEdit.tpl:351-355) gated on $tlCfg->api->enabled and wired to usersEdit.php:274-318 createNewAPIKey(). The modern screen ports it to a row action backed by a new BFF route:

• UI (gui/templates/usermanagement/usersView.html): an id-card icon in the Actions column per row, rendered only when the /meta/authentication payload reports apiEnabled = true (canGenerateApiKey() — legacy $tlCfg->api->enabled parity). Clicking shows a confirm dialog (user.generateApiKeyConfirm), then POST /api/users/index.php/{id}/generate-apikey; the result is shown as an alert: "New API key has been sent via mail" (user.apiKeySent) or the localized error.
• BFF (api/users/index.php, POST /users/{id}/generate-apikey), mirroring the legacy createNewAPIKey() flow step by step:
  1. re-checks $tlCfg->api->enabled server-side → 403 api_disabled (defense-in-depth; the UI hides the action anyway);
  2. validates config_get('smtp_host') with Zend_Validate_Hostname(ALLOW_ALL) → 400 invalid_smtp_hostname on failure (same gate as legacy). The legacy lang key apikey_cannot_be_reseted_invalid_smtp_hostname is not defined in any strings.txt bundle (lang_get would emit a "not localized" WARNING event), so the BFF returns a plain message and the UI maps the code to the localized user.apiKeyInvalidSmtp;
  3. calls APIKey::addKeyForUser($id) (lib/functions/APIKey.class.php:38-50 UPDATE users SET script_key = md5(8×mt_rand())) and reads the fresh key via getAPIKey();
  4. emails the key via @email_send(...) (subject mail_apikey_subject, body your_apikey_is + key + contact_admin). A delivery failure is caught and written to the PHP error log only (error_log) — never to the Event Viewer (no new WARNING events), matching legacy's silent @ suppression;
  5. on success logs logAuditEvent(tls('audit_user_apikey_set',$login),'CREATE',...).
• Config: config_get('smtp_host') + the legacy mail_apikey_subject / your_apikey_is / from_email globals. With the default unconfigured SMTP host the route returns 400 invalid_smtp_hostname, same as legacy.
• New i18n keys in all 10 locale bundles: user.generateApiKey, user.generateApiKeyConfirm, user.apiKeySent, user.apiKeyFailed, user.apiKeyInvalidSmtp, user.apiKeyDisabled.

Legacy creates a user only with a non-empty password: the create form blocks submit with warning_empty_pwd (usersEdit.tpl:153-155 sets check_password=1, validateForm hook, password input required) and the server rejects empty passwords — doCreate() checks setPassword() and treats tlUser::E_PWDEMPTY (< 0) as a failure, so writeToDB() never runs (usersEdit.php:153-171).

The modern screen now enforces the same rule on both layers:

• BFF (api/users/index.php, POST create): the setPassword() return value is checked — anything < tl::OK (i.e. E_PWDEMPTY = "The password must not be empty!") returns HTTP 400 {status:error, code:'warning_empty_pwd', message:<legacy string>} before writeToDB(), so no blank-password row can be persisted (not even via a direct API POST). S_PWDMGTEXTERNAL (2 >= OK) remains allowed, matching legacy doCreate, which validates the password against the configured default auth method.
• UI (usersView.html): the password input carries required in the create modal (removed again on edit — "leave empty to keep"), and saveUser() blocks an empty-password create client-side with the localized user.passwordRequired message, focusing the field — mirroring legacy validateForm(f, check_password=1).
• i18n: new key user.passwordRequired in all 10 locale bundles, used for both the client-side block and the server 400 mapping.

When $tlCfg->demoMode = ON; in config.inc.php the whole User Management screen becomes read-only, mirroring legacy usersEdit.tpl:312-355 where the Save button is replaced by the demo_update_user_disabled note (on doUpdate) and the Reset password / Generate key form by demo_reset_password_disabled.

• BFF enforcement (api/users/index.php): a shared demoModeBlockedWrite() helper (mirror of api/userinfo) returns HTTP 403 {status:error, code:'demo_mode'} from every write route — POST create, PUT update, PUT /active, DELETE, POST reset-password and POST generate-apikey. The UI can never bypass it.
• UI gating (usersView.html): with demo mode on a read-only amber banner appears under the header, the Create User toolbar button disappears, grid rows show only the Edit icon (no reset-password / generate-API-key / enable-disable / delete), and the create/edit modal replaces Save with a user.demoUpdateDisabled notice and disables every field. Cancel/close stay usable.
• Discovery: GET /api/users/index.php/meta/authentication now returns demoMode so the front-end knows the state.
• New i18n keys in all 10 locale bundles (values from the legacy strings.txt): user.demoUpdateDisabled, user.demoResetPasswordDisabled.

Legacy usersEdit.tpl:189-193 showed a question/help icon (title show_event_history) next to the "User Details" legend that drilled into the Event Viewer pre-filtered to the edited user's audit activity via showEventHistoryFor(user_id,'users'). The icon was gated on grants->mgt_view_events (usersEdit.php:457-458, hasRight('mgt_view_events')).

The modern edit modal replicates it:

• BFF (api/users/index.php GET /meta/grants): the grants payload now includes mgt_view_events ('yes'/'no'), mirroring the legacy separate assignment in usersEdit.php:457-458 (the value is deliberately NOT part of getGrantsForUserMgmt(), exactly like legacy).
• UI (usersView.html): a Show event history button (#btnEventHistory, fa-history + data-i18n="user.showEventHistory") appears in the edit modal header only while editing an existing user and the current logged-in user holds mgt_view_events. It is hidden in the create modal and for users without the right. Clicking it submits a hidden GET form (object_id=<user id>&object_type=users) which opens the modern Event Viewer at eventviewer.html?object_id=<id>&object_type=users in a new tab, showing "Filtered by users #" — the same pattern as the user profile (userInfo.html) and milestones (planMilestones.html) screens.
• The Event Viewer BFF (api/eventviewer/index.php) independently enforces mgt_view_events (403 without it), so the filter cannot be abused.
• New i18n key in all 10 locale bundles: user.showEventHistory (values match the existing profile.showEventHistory translations).

Legacy lib/usermanagement/usersView.php:47 (disable) and lib/usermanagement/usersEdit.php:169/214 (create/update) filled $gui->user_feedback with localized messages — user_created ("User %s was successfully created"), user_disabled ("User %s was successfully disabled"), getUserErrorMessage() for failures — rendered as a banner by inc_update.tpl. The modern screen used to close the modal / reload the grid after every write with no success feedback at all.

The 2.0.1 screen now mirrors that feedback with a Dashio toast (bottom-right, auto-hides after ~3 s, teal for success / red for errors):

• BFF (api/users/index.php): every write-success route now returns feedback_key with the same key namespace legacy used for $gui->user_feedback: POST /users → user_created, PUT /users/{id} → user_updated, PUT /users/{id}/active → user_enabled|user_disabled, DELETE /users/{id} → user_deleted.
• UI (gui/templates/usermanagement/usersView.html): a fixed .toast element (same pattern as cfieldsAssignView.html / planUpdateTC.html) plus a userFeedback(feedbackKey, login) mapper to the client-side i18n keys. Create/update save (saveUser()), enable/disable (toggleActive()) and delete (deleteUser()) all show the localized toast with the affected login; toggle/delete errors moved from alert() to the red toast; the confirm dialogs (user.confirmDelete/Disable/Enable) and the status badges (user.active/user.inactive) are localized too.
• i18n: new keys in all 10 bundles — user.feedback.created, user.feedback.updated, user.feedback.disabled, user.feedback.enabled, user.feedback.deleted, user.confirmDelete, user.confirmDisable, user.confirmEnable — translations taken from the legacy locale/<XX>/strings.txt messages.

Screenshot: docs/screenshots/issue-890-operation-feedback-toast.png (create toast "User was successfully created").

• Only users with active = 1 (Active) appear in the table
• Deleted users (active = 2) are hidden but preserved for audit trail
• The admin user cannot be deleted or disabled
• Changes to other users are logged in the Event Viewer as AUDIT events

Path: System > Role Management
URL: gui/templates/usermanagement/rolesView.html
Purpose: Create custom roles and manage their permission sets (rights).

System roles cannot be edited or deleted. They are protected by the system:

These roles ship with TestLink and can be edited (but not deleted):

Rights are color-coded in the table:

• Only Custom roles can be deleted (roles with IDs > 3)
• Before deletion, the system shows how many users currently have this role assigned
• Users assigned to a deleted role are automatically reset to the configured replacement role (role_replace_for_deleted_roles, legacy rolesView.tpl:61 warning warning_users_will_be_reset)

Every create/update/duplicate/delete operation now surfaces a localized feedback toast (bottom-right Dashio banner), mirroring the legacy inc_update.tpl user_feedback/$sqlResult area of rolesEdit.tpl:53 and rolesView.tpl:43:

• BFF (api/roles/index.php): write-success routes return the same feedback_key namespace #890 added for User Management — role_created (POST), role_updated (PUT), role_deleted (DELETE), role_duplicated (POST /duplicate). Error routes return messageKey that resolves the legacy localized messages via getRoleErrorMessage() (roles.inc.php:440-466): error_duplicate_rolename → role.error.nameExists, error_role_no_rolename → role.error.noRoleName, error_role_no_rights → role.error.noRights, error_role_not_updated → role.error.notUpdated, error_role_deletion → role.error.deleted; the system-role guards map to role.editLocked / role.systemDeleteDenied.
• UI (rolesView.html): Dashio .toast (ok = teal, err = red, auto-hide ~3s), toast() + roleFeedback() helpers. Success → OK toast ("Role X was successfully created / saved / deleted / duplicated"); errors → red toast or the modal error line, always localized — no alert() dialogs remain.
• i18n: 9 keys added to all 10 bundles (role.feedback.created/updated/ deleted/duplicated, role.error.deleted/nameExists/noRoleName/noRights/ notUpdated), translations taken from legacy locale/*/strings.txt.

• Create roles with only the permissions needed (principle of least privilege)
• Role rights apply globally — they are not project-specific
• Changes to roles immediately affect all users assigned to that role

Path: System > Assign Test Project Roles
URL: gui/templates/usermanagement/usersAssignProject.html
Purpose: Assign a role to each user at the test project level.

Test project roles control what a user can do within a specific test project. This overrides or supplements the user's global role for project-scoped activities.

1. Select a Test Project from the dropdown
2. The table loads all active users and their current role assignment for that project
3. Change the Assigned Role dropdown for any user
4. Modified rows are highlighted in yellow with a modified badge
5. Click Save Changes to persist

• Users see only projects they have access to (based on global role + project public/private settings)
• Admin users see all projects regardless of assignments
• A user with no project role on a private project will NOT have access to it

• Project roles do not override the global role — they supplement it
• For public projects, any user with a valid global role can participate unless explicitly denied
• For private projects, users must be explicitly assigned a role

Legacy opened this screen through usersAssign.php:23 testlinkInitPage(...), which ran checkSessionValid() before the first render, so a session idle past config_get("sessionInactivityTimeout") minutes never painted the assignment form — it went straight to login.php?note=expired&destination=…, carrying the localized “Session expired. Please log in again.” box.

The modern screen reproduces that behaviour on every request it makes:

Between the toast and the redirect the page is put in the legacy “nothing to act on” state: the tab bar, the toolbar and the grid are hidden, the Test Project combo is emptied and disabled, Save is disabled and the footer is cleared — no misleading “Select a test project above…” box is shown and no dead control can be clicked. A 403 is unaffected: it still shows the “You do not have enough rights…” deny box. The helper keys on the HTTP status, so an absent session (401 {"message":"Not authenticated"}, no code key) is handled too.

Because the Dashio shell never refreshes the session timer, this is the normal fate of a shell tab left open past the timeout — a screen that handles the 401 itself bounces by itself. All four user-management screens now do: the two assign-roles screens (this one, #1620, and Assign Test Plan Roles, #1646), plus User Management and Role Management themselves (#1760 — 12 and 8 request paths respectively, and api/users/index.php never enforced the inactivity window at all, so a stale session could even create users).

Details: Task-Issue-1760-User-Role-Management-Session-Expired-Bounce.md

Details: Task-Issue-1620-Assign-Project-Roles-Initial-Load-Session-Expired.md

Path: System > Assign Test Plan Roles
URL: gui/templates/usermanagement/usersAssignPlan.html
Purpose: Assign role overrides to users for a specific test plan.

Test plan roles allow you to narrow or change a user's permissions for a specific test plan, overriding their test project role. This is useful when a user needs different permissions for different test plans within the same project.

1. Select a Test Project from the first dropdown
2. The Test Plan dropdown populates with active plans in that project
3. Select a Test Plan
4. The table loads all active users with:
   • Their inherited role from the test project assignment
   • Their current plan role override (if any)
5. Change the Plan Role Override for any user
6. Click Save Changes to persist

When determining what a user can do in a test plan, TestLink checks (in order):

1. Test plan role (highest priority) — if set, this overrides everything
2. Test project role — the role assigned at the project level
3. Global role (lowest priority) — the user's system-wide role

User tester1 has:

• Global role: tester
• Project role for P2: tester
• Plan role override for "smoke" plan in P2: senior tester

Result: On the "smoke" test plan, tester1 operates as a senior tester (can create builds, execute tests, view metrics). On all other plans in P2, they operate as a tester.

• Use plan overrides sparingly — they add complexity to the permission model
• The Inherited Role column helps you understand what the user's effective role would be without an override
• Setting "-- no override --" removes the plan-specific override and falls back to the inherited project role

Global Role (system-wide, assigned in User Management)
  └── Test Project Role (assigned in Assign Test Project Roles)
        └── Test Plan Role Override (assigned in Assign Test Plan Roles)

• Global role applies everywhere unless overridden
• Project role applies within a specific project (supplements global)
• Plan role override applies within a specific test plan (overrides project role)

1. Go to User Management > click Create User
2. Fill in login, name, email, password; select tester as global role
3. Go to Assign Test Project Roles > select the project
4. Set the user's role to tester for that project
5. (Optional) Go to Assign Test Plan Roles > select project + plan
6. Set a plan override if needed

1. Go to Assign Test Project Roles > select the project
2. Set the user's role to admin for that project only
3. Their global role remains unchanged — admin access is limited to this project

1. Go to Assign Test Plan Roles > select project + plan
2. Set the user's Plan Role Override to guest (read-only)
3. On all other plans they retain their normal project role

1. Go to Role Management > click + Create Role
2. Enter a name and description
3. Use Select All to quickly check all permissions, then uncheck what you don't need
4. Click Save
5. The new role appears in all role assignment dropdowns across the system

Since issue #879, every User Management BFF endpoint enforces the legacy mgt_users right (right id 13) on the session user — same check as legacy lib/usermanagement/usersView.php checkRights(), also enforced in legacy usersEdit.php and usersExport.php.

• A user with mgt_users (e.g. admin): gets GET /api/users, POST, PUT, DELETE and GET /meta/grants — full management.
• A user without mgt_users (e.g. guest): any request to /api/users/… returns 403 {"status":"error","message":"no_permissions_for_action","right":"mgt_users"}. No user data leaks; no mutation is possible.
• The denial is also written to the audit trail as audit_security_user_right_missing (AUTH event).

The modern User Management screen calls GET /api/users/meta/grants, which mirrors legacy getGrantsForUserMgmt() (lib/functions/users.inc.php). The resulting grant map controls which tabs the user sees:

Legacy parity: when the user holds mgt_users, tproject/tplan assignment grants are forced to "yes" (those tabs stay visible). A user without mgt_users sees only the no-access notice (i18n user.noRights) instead of the tab bar. This mirrors legacy gui/templates/dashio/usermanagement/menu.inc.tpl.