Dojo to Angular: Roles Portlet

Context

The Roles and Tools portlet (role hierarchy + role-to-user membership + per-role permissions + per-role Tool Group assignment) currently ships as a Dojo + JSP portlet built around dijit.Tree, dijit.layout.TabContainer, dojox.grid.DataGrid, dotcms.dijit.form.HostFolderFilteringSelect, and RoleAjax DWR calls. This epic migrates it to Angular + PrimeNG and reshapes the information architecture per the new design.

The migration is decomposed into a consolidated spike (current state + backend API + target UI mapping + iframe wrapper design), a single FE + BE implementation task (Angular library + portlet.xml registration as an opt-in Beta portlet), and a docs task. A follow-up swap-to-primary task is filed as a placeholder for after the Beta bakes in production.

The Users tab ships as a full Angular implementation. The Permissions and Tools tabs ship as iframe wrappers hosting the existing Dojo UI unchanged, because the Permissions Angular redesign is out of scope for this Epic and the Tools redesign is still being defined. Each iframe wrapper is intentionally thin so the eventual Angular replacements can be dropped in without touching the surrounding Angular shell — those replacements are tracked as follow-up [Task] issues.

Design reference: https://claude.ai/design/p/20548219-a454-4b14-becf-5dd4dc0b84a1?file=Roles.dc.html&via=share (internal — auth required).

Current State (Dojo)

Target State (Angular)

Information architecture shift

Structure

• New Nx library: core-web/libs/portlets/dot-roles/ (shell + page + SignalStore + data-access extension + models)
• Two-column layout: left Roles panel (p-tree with drag-and-drop), right Role detail (header + three-tab p-tabView)
• Three tabs on the right: Users (Angular), Permissions (iframe), Tools (iframe)
• Data-access extension: libs/data-access/src/lib/dot-roles/ covers /v1/roles/* and /v1/users/filter for the Angular surfaces; iframe-wrapped tabs keep calling their existing endpoints from inside the JSPs
• Reuse models from libs/dotcms-models: DotRole (extend as needed)
• PrimeNG only for every Angular UI component; iframe tabs render two new thin JSP wrappers dedicated to their surfaces
• License + role gating preserved; any gap surfaced in the spike's API audit is filed as a separate security task and linked here

Backend Wiring

• dotCMS/src/main/webapp/WEB-INF/portlet.xml: add a new roles-beta entry (com.dotcms.spring.portlet.PortletController, <portlet-url>/roles</portlet-url>, display name Roles and Tools (Beta)). The existing Dojo roles entry stays untouched so admins can revert by removing roles-beta from their layout and adding roles back
• New Angular route roles in core-web/apps/dotcms-ui/src/app/app.routes.ts loading @dotcms/portlets/dot-roles/portlet
• Reuse the existing PortletID.ROLES enum entry and the existing roles i18n title key; add a roles-beta i18n title key for the Beta display name
• Not added to any default layout or UpgradeTask — admins opt in via "Add Portlet" in Tools
• New JSP wrappers under html/portlet/ext/roleadmin/ for the Permissions and Tools iframes (thin, postMessage contract, roleId query-string input). Existing JSPs stay untouched
• Backend hardening discovered during the spike (drag-to-reparent endpoint if missing, OpenAPI gaps on legacy RoleResource, consolidation of remaining DWR methods) is tracked in separate [Task] issues filed by the spike and linked here

Acceptance Criteria

• Roles and Tools (Beta) appears in the "Add Portlet" picker
• Adding the Beta portlet to a layout serves the Angular shell at /#/c/roles
• Roles panel renders the full hierarchy with folder icons for parents and shield icons for children, expand/collapse, user-count badges, and Filter roles client-side filtering
• New opens the Add Role dialog; save creates the role and refreshes the tree
• Inline + on a parent row opens Add Role dialog with Parent prefilled
• Drag-and-drop of a role onto a different parent persists the reparent via v1 endpoint
• Edit Role opens the Edit dialog; save updates the role; Delete Role opens a confirm-destroy and removes the role
• Users tab: Grant to User popover searches users and grants the role on selection; members table renders NAME / EMAIL / GRANTED FROM (with inheritance chip); remove and bulk-remove work; empty state matches the design copy
• Permissions tab: iframe loads the new JSP wrapper and renders the existing permissions UI functional (matrix, cascade toggle, apply changes, cascade-progress) — behavior parity with the current Dojo portlet
• Tools tab: iframe loads the new JSP wrapper and renders the existing Tool Groups management functional (available / assigned layouts, New Layout dialog, save role-layouts) — behavior parity with the current Dojo portlet
• License + role gating preserved on every write path (roles portlet, admin-only surfaces)
• Rollback: Dojo roles portlet entry remains registered so admins can revert by removing roles-beta from their layout and adding roles back — no code change or redeploy needed
• Follow-up [Task] filed for the Angular replacement of the Permissions tab
• Follow-up [Task] filed for the Angular replacement of the Tools tab (once design is defined)

Sub-tasks

• #36929 — [Spike] consolidated audit (current state + backend API + target UI mapping + iframe wrapper design + backend hardening backlog)
• #36930 — [Task] Angular implementation + backend wiring
• #36931 — [Docs] document UI/UX changes after Dojo → Angular migration
• #36932 — [Task] promote Beta portlet to primary and rename Dojo portlet to Legacy (post bake-in)