Skip to content

armgit / zulip

Public Imported from GitHub
0

Zulip server and web application. Open-source team chat that helps teams stay productive and focused.

api-docs: Document PATCH and DELETE /realm/profile_fields/{field_id}.

Agnish Bauria02fd83cdeee
diff --git a/api_docs/include/rest-endpoints.md b/api_docs/include/rest-endpoints.md
index 1cc0b46462c..1efa056d238 100644
--- a/api_docs/include/rest-endpoints.md
+++ b/api_docs/include/rest-endpoints.md
@@ -151,6 +151,8 @@
* [Get all custom profile fields](/api/get-custom-profile-fields)
* [Reorder custom profile fields](/api/reorder-custom-profile-fields)
* [Create a custom profile field](/api/create-custom-profile-field)
+* [Update a custom profile field](/api/update-custom-profile-field)
+* [Delete a custom profile field](/api/delete-custom-profile-field)
* [Update realm-level defaults of user settings](/api/update-realm-user-settings-defaults)
* [Get allowed domains](/api/get-realm-domains)
* [Add an allowed domain](/api/add-realm-domain)
diff --git a/zerver/openapi/curl_param_value_generators.py b/zerver/openapi/curl_param_value_generators.py
index 133aa806a82..64cc647cab0 100644
--- a/zerver/openapi/curl_param_value_generators.py
+++ b/zerver/openapi/curl_param_value_generators.py
@@ -14,6 +14,7 @@ from django.utils.timezone import now as timezone_now
from zerver.actions.channel_folders import check_add_channel_folder
from zerver.actions.create_user import do_create_user
+from zerver.actions.custom_profile_fields import try_add_realm_custom_profile_field
from zerver.actions.presence import update_user_presence
from zerver.actions.reactions import do_add_reaction
from zerver.actions.realm_domains import do_add_realm_domain
@@ -24,8 +25,9 @@ from zerver.lib.events import do_events_register
from zerver.lib.initial_password import initial_password
from zerver.lib.test_classes import ZulipTestCase
from zerver.lib.test_helpers import read_test_image_file
+from zerver.lib.types import ProfileFieldData
from zerver.lib.upload import upload_message_attachment
-from zerver.models import Client, Message, NamedUserGroup, UserPresence
+from zerver.models import Client, CustomProfileField, Message, NamedUserGroup, UserPresence
from zerver.models.channel_folders import ChannelFolder
from zerver.models.realms import RealmExport, get_realm
from zerver.models.users import UserProfile, get_user
@@ -359,6 +361,36 @@ def remove_realm_playground() -> dict[str, object]:
}
+@openapi_param_value_generator(["/realm/profile_fields/{field_id}:patch"])
+def update_custom_profile_field() -> dict[str, object]:
+ # A dropdown field, so that the documented field_data example validates.
+ field_data: ProfileFieldData = {
+ "0": {"text": "Vim", "order": "1"},
+ "1": {"text": "Emacs", "order": "2"},
+ }
+ field = try_add_realm_custom_profile_field(
+ get_realm("zulip"),
+ "Favorite IDE",
+ CustomProfileField.DROPDOWN,
+ field_data=field_data,
+ )
+ return {
+ "field_id": field.id,
+ }
+
+
+@openapi_param_value_generator(["/realm/profile_fields/{field_id}:delete"])
+def delete_custom_profile_field() -> dict[str, object]:
+ field = try_add_realm_custom_profile_field(
+ get_realm("zulip"),
+ "Field to delete",
+ CustomProfileField.SHORT_TEXT,
+ )
+ return {
+ "field_id": field.id,
+ }
+
+
@openapi_param_value_generator(["/users/{user_id}:delete"])
def deactivate_user() -> dict[str, object]:
user_profile = do_create_user(
diff --git a/zerver/openapi/python_examples.py b/zerver/openapi/python_examples.py
index 985e62e12be..1daa5a43374 100644
--- a/zerver/openapi/python_examples.py
+++ b/zerver/openapi/python_examples.py
@@ -661,7 +661,7 @@ def reorder_realm_profile_fields(client: Client) -> None:
@openapi_test_function("/realm/profile_fields:post")
-def create_realm_profile_field(client: Client) -> None:
+def create_realm_profile_field(client: Client) -> int:
# {code_example|start}
# Create a custom profile field in the user's organization.
request = {"name": "Phone", "hint": "Contact no.", "field_type": 1}
@@ -669,6 +669,30 @@ def create_realm_profile_field(client: Client) -> None:
# {code_example|end}
assert_success_response(result)
validate_against_openapi_schema(result, "/realm/profile_fields", "post", "200")
+ return result["id"]
+
+
+@openapi_test_function("/realm/profile_fields/{field_id}:patch")
+def update_realm_profile_field(client: Client, field_id: int) -> None:
+ # {code_example|start}
+ # Update a custom profile field in the user's organization.
+ request = {"name": "Cell", "hint": "Contact number."}
+ result = client.call_endpoint(
+ url=f"/realm/profile_fields/{field_id}", method="PATCH", request=request
+ )
+ # {code_example|end}
+ assert_success_response(result)
+ validate_against_openapi_schema(result, "/realm/profile_fields/{field_id}", "patch", "200")
+
+
+@openapi_test_function("/realm/profile_fields/{field_id}:delete")
+def delete_realm_profile_field(client: Client, field_id: int) -> None:
+ # {code_example|start}
+ # Delete a custom profile field in the user's organization.
+ result = client.call_endpoint(url=f"/realm/profile_fields/{field_id}", method="DELETE")
+ # {code_example|end}
+ assert_success_response(result)
+ validate_against_openapi_schema(result, "/realm/profile_fields/{field_id}", "delete", "200")
@openapi_test_function("/realm/filters:post")
@@ -2299,7 +2323,9 @@ def test_server_organizations(client: Client) -> None:
delete_custom_emoji(client)
get_realm_profile_fields(client)
reorder_realm_profile_fields(client)
- create_realm_profile_field(client)
+ profile_field_id = create_realm_profile_field(client)
+ update_realm_profile_field(client, profile_field_id)
+ delete_realm_profile_field(client, profile_field_id)
export_id = export_realm(client)
get_realm_exports(client)
get_realm_export_consents(client)
diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml
index cfd1573fc90..2dc6999d49d 100644
--- a/zerver/openapi/zulip.yaml
+++ b/zerver/openapi/zulip.yaml
@@ -15454,6 +15454,164 @@ paths:
description: |
The ID for the custom profile field.
example: {"result": "success", "msg": "", "id": 9}
+ /realm/profile_fields/{field_id}:
+ patch:
+ operationId: update-custom-profile-field
+ summary: Update a custom profile field
+ tags: ["server_and_organizations"]
+ x-requires-administrator: true
+ description: |
+ Update the configuration of a
+ [custom profile field](/help/custom-profile-fields) in the user's
+ organization.
+
+ The [type](/api/create-custom-profile-field#parameter-field_type)
+ of a custom profile field cannot be changed.
+
+ At most, 2 custom profile fields can have
+ [`display_in_profile_summary`](/api/update-custom-profile-field#parameter-display_in_profile_summary)
+ set to `true` in an organization.
+
+ For custom profile fields with type 7 (External account) that use
+ one of Zulip's configured default external account providers
+ (e.g., GitHub, LinkedIn, etc.), the field's
+ [`name`](/api/update-custom-profile-field#parameter-name),
+ [`hint`](/api/update-custom-profile-field#parameter-hint), and
+ [`field_data`](/api/update-custom-profile-field#parameter-field_data)
+ cannot be changed, and attempting to do so will return an error.
+
+ **Changes**: Before Zulip 9.0 (feature level 252), the `name`,
+ `hint`, `field_data`, `required` and `display_in_profile_summary`
+ parameters were all required in every request, even when their
+ values were unchanged.
+ parameters:
+ - $ref: "#/components/parameters/CustomProfileFieldId"
+ requestBody:
+ content:
+ application/x-www-form-urlencoded:
+ schema:
+ type: object
+ properties:
+ name:
+ description: |
+ The name of the custom profile field, which appears both in
+ the user-facing settings UI for configuring the custom profile
+ fields and in the UI displaying a user's profile.
+ type: string
+ example: "Programming language"
+ hint:
+ $ref: "#/components/schemas/CustomProfileFieldHintSchema"
+ field_data:
+ $ref: "#/components/schemas/CustomProfileFieldDataSchema"
+ display_in_profile_summary:
+ $ref: "#/components/schemas/CustomProfileFieldDisplayInProfileSummarySchema"
+ required:
+ $ref: "#/components/schemas/CustomProfileFieldRequiredSchema"
+ editable_by_user:
+ $ref: "#/components/schemas/CustomProfileFieldEditableByUserSchema"
+ use_for_user_matching:
+ $ref: "#/components/schemas/CustomProfileFieldUseForUserMatchingSchema"
+ encoding:
+ field_data:
+ contentType: application/json
+ display_in_profile_summary:
+ contentType: application/json
+ required:
+ contentType: application/json
+ editable_by_user:
+ contentType: application/json
+ use_for_user_matching:
+ contentType: application/json
+ responses:
+ "200":
+ $ref: "#/components/responses/SimpleSuccess"
+ "400":
+ description: Bad request.
+ content:
+ application/json:
+ schema:
+ oneOf:
+ - allOf:
+ - $ref: "#/components/schemas/CodedError"
+ - example:
+ {
+ "code": "BAD_REQUEST",
+ "msg": "Field id 4 not found.",
+ "result": "error",
+ }
+ description: |
+ A typical failed JSON response for when there is no custom profile
+ field with the requested ID:
+ - allOf:
+ - $ref: "#/components/schemas/CodedError"
+ - example:
+ {
+ "code": "BAD_REQUEST",
+ "msg": "A field with that label already exists.",
+ "result": "error",
+ }
+ description: |
+ A typical failed JSON response for when another custom profile field
+ already uses the requested name:
+ - allOf:
+ - $ref: "#/components/schemas/CodedError"
+ - example:
+ {
+ "code": "BAD_REQUEST",
+ "msg": "Only 2 custom profile fields can be displayed in the profile summary.",
+ "result": "error",
+ }
+ description: |
+ A typical failed JSON response for when setting
+ `display_in_profile_summary` to `true` would exceed the
+ organization's limit of 2 such fields:
+ - allOf:
+ - $ref: "#/components/schemas/CodedError"
+ - example:
+ {
+ "code": "BAD_REQUEST",
+ "msg": "Default custom field cannot be updated.",
+ "result": "error",
+ }
+ description: |
+ A typical failed JSON response for when attempting to change the
+ `name`, `hint`, or `field_data` of a default external account field:
+ delete:
+ operationId: delete-custom-profile-field
+ summary: Delete a custom profile field
+ tags: ["server_and_organizations"]
+ x-requires-administrator: true
+ description: |
+ Delete a [custom profile field](/help/custom-profile-fields) in
+ the user's organization.
+
+ This will also permanently delete any value configured for the
+ custom profile field from every user profile in the database.
+ Therefore, it's recommended that clients warn the active user of
+ the related data removal before submitting the request, e.g.,
+ notify them of how many users will have their profile data
+ deleted as a result of deleting the custom profile field.
+ parameters:
+ - $ref: "#/components/parameters/CustomProfileFieldId"
+ responses:
+ "200":
+ $ref: "#/components/responses/SimpleSuccess"
+ "400":
+ description: Bad request.
+ content:
+ application/json:
+ schema:
+ allOf:
+ - $ref: "#/components/schemas/CodedError"
+ - example:
+ {
+ "code": "BAD_REQUEST",
+ "msg": "Field id 4 not found.",
+ "result": "error",
+ }
+ description: |
+ A typical failed JSON response for when there is no custom profile
+ field with the requested ID:
/realm/user_settings_defaults:
patch:
operationId: update-realm-user-settings-defaults
@@ -28185,6 +28343,10 @@ components:
dropdown UI for individual users to select an option.
The interface for field type 7 is not yet stabilized.
+
+ See [profile field types](/help/custom-profile-fields#profile-field-types)
+ or the [`field_type` parameter](/api/create-custom-profile-field#parameter-field_type)
+ for what each field type number means.
type: object
example:
{
@@ -31713,3 +31875,12 @@ components:
type: integer
example: 17
required: true
+ CustomProfileFieldId:
+ name: field_id
+ in: path
+ description: |
+ The ID of the target custom profile field.
+ schema:
+ type: integer
+ example: 4
+ required: true
diff --git a/zerver/tests/test_openapi.py b/zerver/tests/test_openapi.py
index 773a3afc0cc..94dcabdfc4d 100644
--- a/zerver/tests/test_openapi.py
+++ b/zerver/tests/test_openapi.py
@@ -228,7 +228,6 @@ class OpenAPIArgumentsTest(ZulipTestCase):
"/bots",
"/bots/{bot_id}",
#### These "organization settings" endpoints have low value to document:
- "/realm/profile_fields/{field_id}",
"/realm/icon",
"/realm/logo",
"/realm/subdomain/{subdomain}",