Skip to content

Add documentation for bulk set channel members API#8876

Open
wiggin77 wants to merge 8 commits intomasterfrom
MM-68269_set_channel_membership_api_docs
Open

Add documentation for bulk set channel members API#8876
wiggin77 wants to merge 8 commits intomasterfrom
MM-68269_set_channel_membership_api_docs

Conversation

@wiggin77
Copy link
Copy Markdown
Member

Summary

  • Add setChannelMembers audit event to the embedded JSON audit log schema table

  • Document the new PUT /api/v4/channels/{channel_id}/members bulk membership API in the team and channel members admin guide

Accompanies mattermost/mattermost#36031 which adds the endpoint in Mattermost v11.7.

Ticket Link

https://mattermost.atlassian.net/browse/MM-68269

  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.
@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented Apr 10, 2026

Note

Reviews paused

It 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 reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

Added documentation noting a new API to bulk-replace channel memberships (server computes diffs) and added the setChannelMembers audit event type to the Channel Management Events table.

Changes

Cohort / File(s) Summary
Audit Event Schema Reference
source/administration-guide/comply/embedded-json-audit-log-schema.rst
Inserted setChannelMembers into the "Channel Management Events" audit event types table (new event_name entry), positioned between removeChannelMember and restoreChannel.
API Documentation
source/administration-guide/manage/team-channel-members.rst
Added note that, starting with Mattermost v11.5.2, system admins can replace a channel's entire membership via a single API call; server diffs requested vs current membership and adds/removes users accordingly, with link to the public API operation.

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
Loading

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Title check ✅ Passed The title accurately summarizes the main change: documentation for a bulk set channel members API endpoint across two files.
Description check ✅ Passed The description clearly relates to the changeset, detailing the audit event addition and API documentation updates with supporting context.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch MM-68269_set_channel_membership_api_docs

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 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

📥 Commits

Reviewing files that changed from the base of the PR and between b888ded and 57adbed.

📒 Files selected for processing (2)
  • source/administration-guide/comply/embedded-json-audit-log-schema.rst
  • source/administration-guide/manage/team-channel-members.rst

@github-actions
Copy link
Copy Markdown
Contributor

Newest code from mattermost has been published to preview environment for Git SHA 57adbed

@github-actions
Copy link
Copy Markdown
Contributor

Newest code from mattermost has been published to preview environment for Git SHA f4b4dbc

Copy link
Copy Markdown
Contributor

@esethna esethna left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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

@esethna esethna added this to the v11.7.0 milestone Apr 13, 2026
@esethna
Copy link
Copy Markdown
Contributor

esethna commented Apr 13, 2026

Can you also help rebase this to the 11.7 docs branch once it gets cut in the next few days? @wiggin77

@esethna esethna added the Do Not Merge/Awaiting Next Release To be merged with the next release (e.g. API documentation updates) label Apr 13, 2026
Copilot AI review requested due to automatic review settings April 15, 2026 02:39
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 setChannelMembers to 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.

Comment thread source/administration-guide/manage/team-channel-members.rst Outdated
Comment thread source/administration-guide/manage/team-channel-members.rst Outdated
Comment thread source/administration-guide/manage/team-channel-members.rst Outdated
@github-actions
Copy link
Copy Markdown
Contributor

Newest code from mattermost has been published to preview environment for Git SHA 28dce30

@github-actions
Copy link
Copy Markdown
Contributor

Newest code from mattermost has been published to preview environment for Git SHA 97582c3

@wiggin77
Copy link
Copy Markdown
Member Author

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

@esethna this is done. The examples have been moved to the API docs.

@wiggin77
Copy link
Copy Markdown
Member Author

Can you also help rebase this to the 11.7 docs branch once it gets cut in the next few days?

There is no 11.7 branch yet. If this gets merged to master it will be picked up when the branch is cut.

@wiggin77 wiggin77 requested a review from esethna April 15, 2026 05:10
@github-actions
Copy link
Copy Markdown
Contributor

Newest code from mattermost has been published to preview environment for Git SHA 0db8e3d

@esethna
Copy link
Copy Markdown
Contributor

esethna commented Apr 16, 2026

@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.

@esethna esethna removed the 1: Dev Review Requires review by a core commiter label Apr 16, 2026
@github-actions
Copy link
Copy Markdown
Contributor

Newest code from mattermost has been published to preview environment for Git SHA e3f6303

Comment thread source/administration-guide/manage/team-channel-members.rst Outdated
@github-actions
Copy link
Copy Markdown
Contributor

Newest code from mattermost has been published to preview environment for Git SHA 80b9f69

@github-actions
Copy link
Copy Markdown
Contributor

Newest code from mattermost has been published to preview environment for Git SHA ed7a4db

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Do Not Merge/Awaiting Next Release To be merged with the next release (e.g. API documentation updates)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants