Update documentation for users, organization units, and roles#2972
Update documentation for users, organization units, and roles#2972Malith-19 wants to merge 1 commit into
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThis PR adds comprehensive documentation for role management, enhances API documentation across organization units and users guides, clarifies group membership types to include applications and agents, and integrates the new Roles guide into the sidebar navigation. ChangesUser Management Documentation Expansion
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Possibly related PRs
Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/content/guides/guides/organization-units.mdx`:
- Line 277: Update the headings that fail Vale title-case checks by correcting
their casing to match the repository’s title-case pattern: replace each
occurrence of the heading text "By Organization Unit ID" (and the other three
headings flagged nearby) with the repository-standard Title Case form (ensure
words like "Organization", "Unit", and the acronym "ID" are capitalized
correctly) so the four headings pass Vale; locate and adjust the headings in the
document where that exact heading text appears.
In `@docs/content/guides/guides/users/roles.mdx`:
- Around line 231-242: The Error Codes table is missing the backend contract for
invalid assignment `type` filter (ROL-1016); update the "Error Codes" markdown
table under the "Error Codes" heading to add a row for `ROL-1016` with the
correct HTTP status (400) and a clear cause message such as "The specified
assignment type filter is invalid or unsupported" so the docs reflect the
backend error for invalid `type` filtering referenced earlier in the guide;
ensure the new row matches the table format used by the existing entries
(columns: Error Code, HTTP Status, Cause).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 96999725-6ab9-4d6e-bd64-b36c100b4bdc
📒 Files selected for processing (5)
docs/content/guides/guides/organization-units.mdxdocs/content/guides/guides/users/manage-groups.mdxdocs/content/guides/guides/users/manage-users.mdxdocs/content/guides/guides/users/roles.mdxdocs/sidebars.ts
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Malith-19
added
documentation
Malith-19
force-pushed
the
improve-users-docs
branch
from
31e4a5e to
49d4bfd
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/sidebars.ts (1)
577-577:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winReplace hardcoded brand literal in sidebar label.
Is this hardcoded brand name intentional? This should be derived from config instead of a raw string literal.
Suggested fix
- {type: 'doc', id: 'community/contributing/overview', label: 'Contribute to ThunderID'}, + {type: 'doc', id: 'community/contributing/overview', label: `Contribute to ${productConfig.project.name}`},As per coding guidelines: "
**/*.ts: Scan for hardcoded occurrences of the string literalsThunderorThunderID... If it can be replaced, suggest reading the value from the app's config system ... rather than a raw string literal."🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/sidebars.ts` at line 577, The sidebar entry uses a hardcoded label 'Contribute to ThunderID' — replace the raw string literal on the sidebar item (the object with id 'community/contributing/overview' and its label property) with a value read from the app config (e.g., use the central config/getConfig()/siteConfig.brand or an exported getAppName() helper) and fall back to the existing literal if the config value is missing; update the import at the top of docs/sidebars.ts to pull the config helper and replace the label assignment to use that config-driven value instead of the hardcoded 'Contribute to ThunderID'.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/content/guides/guides/users/manage-users.mdx`:
- Around line 74-77: Update the table row for the `limit` parameter in the
Manage Users guide: change the Default column value for `limit` from 10 to 30 so
it matches the API contract; locate the markdown table containing the `limit`
and `offset` parameter rows in manage-users.mdx and edit the `limit` default
accordingly.
---
Outside diff comments:
In `@docs/sidebars.ts`:
- Line 577: The sidebar entry uses a hardcoded label 'Contribute to ThunderID' —
replace the raw string literal on the sidebar item (the object with id
'community/contributing/overview' and its label property) with a value read from
the app config (e.g., use the central config/getConfig()/siteConfig.brand or an
exported getAppName() helper) and fall back to the existing literal if the
config value is missing; update the import at the top of docs/sidebars.ts to
pull the config helper and replace the label assignment to use that
config-driven value instead of the hardcoded 'Contribute to ThunderID'.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 0081ca0e-d774-4c59-8583-9133e4a2ef14
📒 Files selected for processing (5)
docs/content/guides/guides/organization-units.mdxdocs/content/guides/guides/users/manage-groups.mdxdocs/content/guides/guides/users/manage-users.mdxdocs/content/guides/guides/users/roles.mdxdocs/sidebars.ts
✅ Files skipped from review due to trivial changes (2)
- docs/content/guides/guides/users/roles.mdx
- docs/content/guides/guides/organization-units.mdx
Malith-19
force-pushed
the
improve-users-docs
branch
2 times, most recently
from
1fc4ff9 to
7446080
Compare
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/sidebars.ts (1)
577-577: ⚡ Quick winReplace hardcoded
ThunderIDbrand literal with config-derived value.Is this hardcoded brand name intentional? If not, avoid the raw string and read the product name from config (in React surfaces via
useConfig, and in this file via the existing product config object), e.g.:
label: \Contribute to ${productConfig.project.name}``.As per coding guidelines, "
**/*.ts: Scan for hardcoded occurrences of the string literalsThunderorThunderIDin this file... If it can be replaced, suggest reading the value from the app's config system using theuseConfighook."🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/sidebars.ts` at line 577, The sidebar entry uses a hardcoded brand literal "ThunderID"; replace that raw string with the project name from the existing product config instead of hardcoding — update the label for the doc entry (the object with type 'doc' and id 'community/contributing/overview') to build the label using the product config (e.g. via productConfig.project.name as used elsewhere in this file) so the text reads "Contribute to <product name>" dynamically; ensure you import or reference the existing productConfig symbol already present in docs/sidebars.ts rather than adding a new hardcoded string.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@docs/sidebars.ts`:
- Line 577: The sidebar entry uses a hardcoded brand literal "ThunderID";
replace that raw string with the project name from the existing product config
instead of hardcoding — update the label for the doc entry (the object with type
'doc' and id 'community/contributing/overview') to build the label using the
product config (e.g. via productConfig.project.name as used elsewhere in this
file) so the text reads "Contribute to <product name>" dynamically; ensure you
import or reference the existing productConfig symbol already present in
docs/sidebars.ts rather than adding a new hardcoded string.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 609c4a75-40d0-43f1-88e0-db3499323c29
📒 Files selected for processing (5)
docs/content/guides/guides/organization-units.mdxdocs/content/guides/guides/users/manage-groups.mdxdocs/content/guides/guides/users/manage-users.mdxdocs/content/guides/guides/users/roles.mdxdocs/sidebars.ts
✅ Files skipped from review due to trivial changes (4)
- docs/content/guides/guides/users/roles.mdx
- docs/content/guides/guides/users/manage-users.mdx
- docs/content/guides/guides/users/manage-groups.mdx
- docs/content/guides/guides/organization-units.mdx
Malith-19
force-pushed
the
improve-users-docs
branch
from
7446080 to
667104f
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/content/guides/guides/users/manage-roles.mdx`:
- Line 94: The docs incorrectly mark the `permissions` field as required; update
the guide so `permissions` is optional to match the API contract for
CreateRoleRequest which only requires `name` and `ouId`. Locate the table row
referencing `permissions` in the manage-roles.mdx content and change the "Yes" /
required indicator to "No" or "Optional", and ensure any surrounding explanatory
text mentions that `permissions` may be omitted when creating a role per the
CreateRoleRequest schema (required: `name`, `ouId`).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: b5c806b0-7bb7-45bf-b9cf-5951a2ccf072
📒 Files selected for processing (5)
docs/content/guides/guides/organization-units.mdxdocs/content/guides/guides/users/manage-groups.mdxdocs/content/guides/guides/users/manage-roles.mdxdocs/content/guides/guides/users/manage-users.mdxdocs/sidebars.ts
✅ Files skipped from review due to trivial changes (3)
- docs/content/guides/guides/organization-units.mdx
- docs/content/guides/guides/users/manage-groups.mdx
- docs/content/guides/guides/users/manage-users.mdx
Malith-19
force-pushed
the
improve-users-docs
branch
3 times, most recently
from
ea5fe05 to
e92cad8
Compare
Malith-19
force-pushed
the
improve-users-docs
branch
from
e92cad8 to
4ba9c3c
Compare
| **Example — list with pagination:** | ||
|
|
||
| ```bash | ||
| curl -kL "https://localhost:8090/users?limit=10&offset=10" \ |
There was a problem hiding this comment.
Should this be in feature Docs? IIRC we have written current docs building experience around console try out. So listing and filtering should explain what's their in console.
API details will be there in API reference Docs.
Let's verify and modify this accordingly
| |------------|-------------|-------| | ||
| | `USR-1020` | 400 | The filter expression is malformed or uses an unsupported operator | | ||
|
|
||
| ## List Groups for a User |
There was a problem hiding this comment.
Same as previous comment
|
|
||
| The response includes pagination fields (`totalResults`, `startIndex`, `count`) and a `groups` array. Each group entry contains the group `id`, `name`, and `ouId`. | ||
|
|
||
| ## Manage Your Own Profile |
There was a problem hiding this comment.
IMO this shouldn't be here. We should have self service management documented in a different location/ page.
@himeshsiriwardana WDYT?
| 6. Optionally add **Assignments** to immediately assign the role to users, groups, applications, or agents. | ||
| 7. Click **Create**. | ||
|
|
||
| ### Using the API |
There was a problem hiding this comment.
Let's verify this is needed for feature docs. Ideally they can refer API docs for the API paths.
Applicable for all sections with API cURL commands. Current feature docs experience is built around console IIRC
|
|
||
| ## Error Codes | ||
|
|
||
| | Error Code | HTTP Status | Cause | |
There was a problem hiding this comment.
Better to have this in a separate catalog or API docs
|
Shall we also check "ThunderID includes two default user types with pre-defined schemas. " |
2 participants
Purpose
manage-users.mdx): Add missing sections for listing and filtering users (pagination,filterquery,include=display),listing a user's groups, and self-service profile management (
GET/PUT /users/me,POST /users/me/update-credentials).organization-units.mdx): Add Update OU section (console + API), document optional branding/policy API fields(
themeId,layoutId,logoUrl,tosUri,policyUri,cookiePolicyUri), add path-based API examples for get/update/delete, add ListUsers and List Groups sub-resource sections, and surface two previously undocumented error codes (
OU-1013,OU-1014).manage-groups.mdx): Expand member types from users-only to all four supported types (user,app,agent,group) witha reference table. Fix the broken "see the Roles guide" link.
roles.mdx): New guide covering the fully implemented but undocumented roles feature — CRUD operations, permissions model,assignment management with type filtering and
include=display, and an error code reference.sidebars.ts): Register the new Roles page under the Users category.Preview
Related Issues
Related PRs
Checklist
breaking changelabel added.Security checks
Summary by CodeRabbit