#37233: feat(users): return direct roles per user on GET /v1/users/filter

[hassandotcms]

Proposed Changes

• New includeRoles query param on GET /v1/users/filter. When true, each item gains a roles array of the user's directly assigned roles as {id, name, roleKey}; inherited roles and the personal role are excluded (legacy Roles-tab parity). Lets the Users list drop its per-row GET /v1/roles/users/{id} calls.
• Opt-in: without the flag the response is byte-identical to today.
• includeRoles=true requires CMS Administrator or Roles + Users portlet access (same gate as GET /v1/roles/users/{id}), otherwise 403.
• OpenAPI updated; openapi.yaml regenerated.

Checklist

• Tests — UserResourceIntegrationTest (7 new: opt-out parity, direct roles, inherited excluded, keyless role, roleKey + paging, 403 gate, root role named "User…" kept), UserPaginatorTest, UserResourceTest

This PR fixes: #37233

[claude]

Claude finished @hassandotcms's task in 2m 32s —— View job

---

Code Review — #37233 direct roles on GET /v1/users/filter

• Read PR diff and changed files
• Verify SmallRoleView / loadRolesForUser signatures
• Confirm permission-gate parity with GET /v1/roles/users/{id}
• Cross-check personal-role exclusion vs legacy UserAjax#getUserRoles
• Review test coverage

I reviewed the implementation against the legacy behavior it mirrors and the existing role endpoint it claims parity with. The design is sound: the opt-in flag keeps the default payload byte-identical, the permission gate (isRoleAdministrator) is a verbatim match of RoleResource#loadUserRoles (RoleResource.java:1209-1213), and the personal-role exclusion faithfully reproduces the legacy DBFQN check in UserAjax#getUserRoles (UserAjax.java:454-463) rather than the fragile name-based Role#isUser(). Role loading is correctly lifted out of addRequestPasswordAttr so a lookup failure surfaces as a 500 rather than silently emptying the item.

New Issues

• 🟡 Medium: dotCMS/src/main/java/com/dotcms/util/pagination/UserPaginator.java:181 — directRolesOf calls roleAPI.loadRolesForUser(userId, false) once per user in the page, so a page of N users issues N role lookups (an N+1 pattern). This is still a net win over the per-row GET /v1/roles/users/{id} fan-out it replaces (in-process + role cache vs. N HTTP round-trips), so it's not a blocker — but worth noting there is no batch variant, and large perPage values will scale linearly. If a bulk loadRolesForUser for a set of user IDs exists or can be added later, this is the spot to use it.

Notes (non-blocking, no action required)

• isPersonalRole uses DBFQN.contains(usersRootRoleId) — substring match on role UUIDs. This is exactly the legacy semantics (UserAjax.java:459), and UUID collision within a DBFQN path is not a realistic concern, so preserving it is the right call for parity.
• Degradation path is well-handled: if the cms_users root role can't be resolved, usersRootRoleId() logs a warning and returns null, and isPersonalRole short-circuits to false (personal roles simply not excluded) rather than throwing. Logger.warn is used correctly.
• The asset/permission branch passes adminRoleIds = null into toItem, preserving the pre-PR userToMap behavior (no requestPassword attr). ✅
• Test coverage is strong: opt-out parity + never() verification that the lookup is skipped, keyed/keyless/personal/User Managers-named-root discrimination, and includeImplicitRoles=false assertion. The isUser()==true stub on the "User Managers" mock nicely pins the exact regression the DBFQN approach avoids.

Overall this looks correct and well-tested. No blocking issues.

· branch 37233-users-filter-direct-roles

[wezell]

Is there a way to get inherited roles with the API?

[wezell]

Is there any way or flag to include inherited roles with this api?

[hassandotcms]

Is there any way or flag to include inherited roles with this api?

currently no, in this api.

if consumer need inherited roles per user as well, it can use GET /v1/roles/users/{id}.

@wezell