Add documentation for bulk set channel members API#8876
Add documentation for bulk set channel members API#8876
Conversation
Add setChannelMembers audit event to the audit log schema and document
the new PUT /api/v4/channels/{channel_id}/members endpoint in the
team and channel members admin guide. Introduced in Mattermost v11.7.
|
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:
📝 WalkthroughWalkthroughAdded documentation noting a new API to bulk-replace channel memberships (server computes diffs) and added the Changes
Sequence Diagram(s)sequenceDiagram
participant AdminClient as Admin Client
participant API as API Server
participant DB as Database
participant Audit as Audit Log
AdminClient->>API: PUT /api/v4/channels/{channel_id}/members (bulk replace request)
API->>DB: Read current channel members
DB-->>API: Current members
API->>API: Compute diff (adds/removes)
loop per batch (if batching applied by server)
API->>DB: Apply add/remove batch operations
DB-->>API: Batch operation results
API->>AdminClient: Stream NDJSON status lines (added/removed/errors)
end
API->>Audit: Emit `setChannelMembers` audit event
Audit-->>API: Acknowledgement
API-->>AdminClient: Final NDJSON summary/complete line
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
There was a problem hiding this comment.
🧹 Nitpick comments (1)
source/administration-guide/manage/team-channel-members.rst (1)
162-165: Consider adding a minimal request + NDJSON response example.A tiny concrete example would make integration/testing faster, especially for clients unfamiliar with streaming NDJSON.
Example doc snippet
System admins can set the complete membership of a channel in a single API call using ``PUT /api/v4/channels/{channel_id}/members``. The request body is a JSON array of user IDs representing the desired membership. The server computes the diff against the current membership and adds or removes users as needed, leaving existing members untouched. Results are streamed back as NDJSON (``application/x-ndjson``), one line per batch. Each line contains ``added``, ``removed``, and ``errors`` arrays for that batch. Query parameters ``batch_size`` (default 100) and ``batch_delay_ms`` (default 500) control the processing rate. + +Example request body:: + + ["user_id_1", "user_id_2", "user_id_3"] + +Example NDJSON line:: + + {"added":["user_id_3"],"removed":["user_id_4"],"errors":[]}🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@source/administration-guide/manage/team-channel-members.rst` around lines 162 - 165, Add a minimal concrete example showing a sample JSON request body and a few NDJSON response lines for the PUT /api/v4/channels/{channel_id}/members endpoint so readers can see the exact shape of input and streaming output; include the endpoint path and show a tiny request array of user IDs and then 2–3 NDJSON lines demonstrating the batch objects with "added", "removed", and "errors" arrays and note the query parameters batch_size and batch_delay_ms used to produce the example.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@source/administration-guide/manage/team-channel-members.rst`:
- Around line 162-165: Add a minimal concrete example showing a sample JSON
request body and a few NDJSON response lines for the PUT
/api/v4/channels/{channel_id}/members endpoint so readers can see the exact
shape of input and streaming output; include the endpoint path and show a tiny
request array of user IDs and then 2–3 NDJSON lines demonstrating the batch
objects with "added", "removed", and "errors" arrays and note the query
parameters batch_size and batch_delay_ms used to produce the example.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: c22fa3db-4086-4a78-88c5-cf773f73af10
📒 Files selected for processing (2)
source/administration-guide/comply/embedded-json-audit-log-schema.rstsource/administration-guide/manage/team-channel-members.rst
|
Newest code from mattermost has been published to preview environment for Git SHA 57adbed |
|
Newest code from mattermost has been published to preview environment for Git SHA f4b4dbc |
esethna
left a comment
There was a problem hiding this comment.
@wiggin77 Perhaps we can just add a small ..note in the docs here about this feature, with a link to the API docs.
Based on the context of the rest of this doc as is, it doesn't seem to fit here, and it should really live in the API docs
|
Can you also help rebase this to the 11.7 docs branch once it gets cut in the next few days? @wiggin77 |
There was a problem hiding this comment.
Pull request overview
Adds admin-facing documentation for a new bulk channel membership API and updates the embedded JSON audit log schema to include the corresponding audit event, aligning docs with the upcoming Mattermost v11.7 server change.
Changes:
- Document
PUT /api/v4/channels/{channel_id}/members(bulk set/replace channel members), including NDJSON streaming response behavior and restrictions. - Add
setChannelMembersto the embedded JSON audit log schema “Channel Management Events” table.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| source/administration-guide/manage/team-channel-members.rst | Adds a new section documenting the bulk set channel members API, with example request/response and constraints. |
| source/administration-guide/comply/embedded-json-audit-log-schema.rst | Adds the setChannelMembers audit event to the channel management events table. |
|
Newest code from mattermost has been published to preview environment for Git SHA 28dce30 |
|
Newest code from mattermost has been published to preview environment for Git SHA 97582c3 |
@esethna this is done. The examples have been moved to the API docs. |
There is no 11.7 branch yet. If this gets merged to master it will be picked up when the branch is cut. |
|
Newest code from mattermost has been published to preview environment for Git SHA 0db8e3d |
|
@wiggin77 master is live production for docs. So we need to wait for the 11.7 branch to be cut then rebase this, looks good otherwise, thanks. |
|
Newest code from mattermost has been published to preview environment for Git SHA e3f6303 |
|
Newest code from mattermost has been published to preview environment for Git SHA 80b9f69 |
|
Newest code from mattermost has been published to preview environment for Git SHA ed7a4db |
Summary
Add
setChannelMembersaudit event to the embedded JSON audit log schema tableDocument the new
PUT /api/v4/channels/{channel_id}/membersbulk membership API in the team and channel members admin guideAccompanies mattermost/mattermost#36031 which adds the endpoint in Mattermost v11.7.
Ticket Link
https://mattermost.atlassian.net/browse/MM-68269