Where this file lives
- This path (
docs/settings/roles-limit-flow.md) is inside the rakletv3 repo for review and maintenance.- This document describes the current implemented process for the admin roles limit and add-on purchase flow.
Admin Roles Limit Flow¶
Generated: 2026-05-08
Repo: rakletadmin/rakletv3
Focus: Settings roles creation and role detail access when role credits are exhausted.
Purpose¶
Admin users manage custom roles from the settings roles screen. Custom role creation is controlled by the organisation subscription role credit limit, but existing roles must remain readable and editable for managers even when the organisation has reached that limit.
Scope¶
This covers the AngularJS settings roles screen and the v2 roles API endpoints.
Business Rules¶
| Scenario | Expected behavior |
|---|---|
| A manager opens an existing role detail | GET /v2/organisations/{organisationId}/roles/{roleId} returns the role when the role exists and the user has manager access. The role count limit is not checked for this read operation. |
| A manager edits an existing role | PATCH /v2/organisations/{organisationId}/roles/{roleId} updates the role when the role exists and the user has manager access. The role count limit is not checked for this update operation. |
| A manager clicks Add while role usage is below the role credit limit | The settings screen navigates to manager.settings.roles-edit with roleId: '0'. |
| A manager clicks Add while role usage has reached the role credit limit | The settings screen opens ModalManageAddonPurchaseController with the roles add-on type before the create request is sent. |
| A create request is still sent while the role limit is reached | POST /v2/organisations/{organisationId}/roles remains protected by HasRoleAccess and can return 403 Forbidden. |
Implementation Notes¶
Raklet.Backend/Content/scripts/core/manager/settings/settings-roles.controller.js reads RoleCredits and RoleCreditsUsage from OrganizationService.Organization.SubscriptionPlan. The addRole() handler opens the existing manage add-on purchase modal when usage is greater than or equal to the credit limit.
Raklet.Backend/Content/scripts/core/manager/settings/templates/roles.html routes the Add button through addRole() instead of linking directly to the role edit state.
Raklet.Api/Controllers/V2/V2RolesController.cs keeps manager authorization at the controller level. GetRole() and UpdateRole() do not use HasRoleAccess, because reading or editing an existing role should not depend on create-limit availability.
QA Checklist¶
Verify that a manager can open an existing custom role when the organisation has reached the role limit.
Verify that a manager can save changes to an existing custom role when the organisation has reached the role limit.
Verify that clicking Add at the role limit opens the roles add-on purchase modal and does not immediately send the create request.
Verify that clicking Add below the role limit still opens the create role screen.