mirror of
https://github.com/zulip/zulip.git
synced 2025-11-03 13:33:24 +00:00
d3ea6520dc
This commit adds a server level setting which controls whether the setting can be set to anonymous user groups. We only allow it in the tests for now because the UI can only handle named user groups.
91 lines
3.9 KiB
Markdown
91 lines
3.9 KiB
Markdown
# Group-setting values
|
|
|
|
Settings defining permissions in Zulip are increasingly represented
|
|
using [user groups](/help/user-groups), which offer much more flexible
|
|
configuration than the older [roles](/api/roles-and-permissions) system.
|
|
|
|
!!! warn ""
|
|
|
|
This API feature is under development, and currently only values that
|
|
correspond to a single named user group are permitted in
|
|
production environments, pending the web application UI supporting
|
|
displaying more complex values correctly.
|
|
|
|
In the API, these settings are represented using a **group-setting
|
|
value**, which can take two forms:
|
|
|
|
- An integer user group ID, which can be either a named user group
|
|
visible in the UI or a [role-based system group](#system-groups).
|
|
- An object with fields `direct_member_ids` containing a list of
|
|
integer user IDs and `direct_subgroup_ids` containing a list of
|
|
integer group IDs. The setting's value is the union of the
|
|
identified collection of users and groups.
|
|
|
|
Group-setting values in the object form function very much like a
|
|
formal user group object, without requiring the naming and UI clutter
|
|
overhead involved with creating a visible user group just to store the
|
|
value of a single setting.
|
|
|
|
The server will canonicalize an object with empty `direct_member_ids`
|
|
and with `direct_subgroup_ids` containing just the given group ID to
|
|
the integer format.
|
|
|
|
## System groups
|
|
|
|
The Zulip server maintains a collection of system groups that
|
|
correspond to the users with a given role; this makes it convenient to
|
|
store concepts like "all administrators" in a group-setting
|
|
value. These use a special naming convention and can be recognized by
|
|
the `is_system_group` property on their group object.
|
|
|
|
The following system groups are maintained by the Zulip server:
|
|
|
|
- `role:internet`: Everyone on the Internet has this permission; this
|
|
is used to configure the [public access
|
|
option](/help/public-access-option).
|
|
- `role:everyone`: All users, including guests.
|
|
- `role:members`: All users, excluding guests.
|
|
- `role:fullmembers`: All [full
|
|
members](https://zulip.com/api/roles-and-permissions#determining-if-a-user-is-a-full-member)
|
|
of the organization.
|
|
- `role:moderators`: All users with at least the moderator role.
|
|
- `role:administrators`: All users with at least the administrator
|
|
role.
|
|
- `role:owners`: All users with the owner role.
|
|
- `role:nobody`: The formal empty group. Used in the API to represent
|
|
disabling a feature.
|
|
|
|
Client UI for setting a permission is encouraged to display system
|
|
groups using their description, rather than using their names, which
|
|
are chosen to be unique and clear in the API.
|
|
|
|
System groups should generally not be displayed in UI for
|
|
administering an organization's user groups, since they are not
|
|
directly mutable.
|
|
|
|
## Updating group-setting values
|
|
|
|
The Zulip API uses a special format for modifying an existing setting
|
|
using a group-setting value.
|
|
|
|
A **group-setting update** is an object with a `new` field and an
|
|
optional `old` field, each containing a group-setting value. The
|
|
setting's value will be set to the membership expressed by the `new`
|
|
field.
|
|
|
|
The `old` field expresses the client's understanding of the current
|
|
value of the setting. If the `old` field is present and does not match
|
|
the actual current value of the setting, then the request will fail
|
|
with error code `EXPECTATION_MISMATCH` and no changes will be applied.
|
|
|
|
When a user edits the setting in a UI, the resulting API request
|
|
should generally always include the `old` field, giving the value
|
|
the list had when the user started editing. This accurately expresses
|
|
the user's intent, and if two users edit the same list around the
|
|
same time, it prevents a situation where the second change
|
|
accidentally reverts the first one without either user noticing.
|
|
|
|
Omitting `old` is appropriate where the intent really is a new complete
|
|
list rather than an edit, for example in an integration that syncs the
|
|
list from an external source of truth.
|