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.

• Edit (pencil icon): Opens the edit modal to change user details and global role
• 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

• 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
• If users are assigned, you must reassign them to another role before deletion

When $tlCfg->demoMode = ON; in config.inc.php the whole Role Management screen becomes read-only, mirroring legacy rolesEdit.tpl:185-205 where on doUpdate the Save button is replaced by the demo_update_role_disabled note ("Demo mode enabled => Update Role DISABLED").

• BFF enforcement (api/roles/index.php): a shared demoModeBlockedWrite() helper (mirror of api/users) returns HTTP 403 {status:error, code:'demo_mode'} from every write route — POST create, PUT update, DELETE, POST /duplicate, and PUT /tproject-roles / /tplan-roles. The UI can never bypass it.
• UI gating (rolesView.html): with demo mode on a read-only amber banner appears under the header, the Create Role toolbar button disappears, grid rows show only the Edit icon (no duplicate/delete), and the edit modal replaces Save with a role.demoUpdateDisabled notice and disables every field (name, description, rights checkboxes, Select All). Opening a role for view stays possible — legacy allowed viewing the edit page, only the update was blocked. Cancel/close stay usable.
• Discovery: GET /api/roles/index.php now returns demoMode so the front-end knows the state.
• New i18n key in all 11 locale bundles (value taken from legacy strings.txt): role.demoUpdateDisabled.

• 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

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

All endpoints use session-based auth (browser cookie), return JSON, and are under /api/ base URL.

{
  "id": 1,
  "login": "admin",
  "firstName": "Admin",
  "lastName": "User",
  "email": "[email protected]",
  "locale": "en_GB",
  "active": 1,
  "globalRoleID": 8,
  "globalRoleName": "admin",
  "authentication": "",
  "expirationDate": "",
  "creation_ts": "2023-01-01 00:00:00"
}

{
  "login": "tester1",
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "password": "secret123",
  "globalRoleID": 7,
  "locale": "en_GB",
  "active": true
}

{ "active": true }

All endpoints return:

{ "status": "ok", "item": { ... } }
// or
{ "status": "error", "message": "Login already exists", "code": 201 }

{
  "id": 10,
  "name": "Custom Role",
  "description": "A custom role",
  "rights": [
    { "id": 1, "name": "mgt_view_events" },
    { "id": 2, "name": "mgt_users" }
  ],
  "isSystem": false
}

{
  "name": "Custom Role",
  "description": "Description here",
  "rightIDs": [1, 2, 3, 4]
}

{
  "tproject_id": 1,
  "assignments": {
    "5": 7,
    "6": 8,
    "7": 0
  }
}

assignments is {userId: roleId}. 0 removes the assignment.

{
  "tplan_id": 1,
  "assignments": {
    "5": 6,
    "6": 0
  }
}

Roles with id <= 3 are system roles:

• 1 — reserved1
• 2 — reserved2
• 3 — no rights (default for new users)

System roles cannot be edited or deleted via the API.

See Event Viewer Wiki for full documentation.