v11.3: Update CPA default values behavior

source/administration-guide/configure/system-attributes.rst

@@ -10,6 +10,6 @@ Review and manage the following system attributes configuration options in the S
 
 You can define, manage, and enforce specific attributes, including:
 
-- **Custom attributes for user profiles**: Display details such as job titles, departments, or other metadata, on user profiles that align with your organizational structures and workflows. Learn more about :doc:`managing custom user profile attributes </administration-guide/manage/admin/user-attributes>`.
+- **Custom attributes for user profiles**: Display details such as job titles, departments, or other metadata, on user profiles that align with your organizational structures and workflows. Learn more about :doc:`managing custom user profile attributes </administration-guide/manage/admin/user-attributes>`. API responses for custom profile attributes return default visibility and sort order when those values are missing.
 - **Granular access controls based on user attributes**: Ensure users have access to only the resources and functionality relevant to their roles, bolstering security and compliance across the organization. Learn more about :doc:`managing access based on user attributes </administration-guide/manage/admin/attribute-based-access-control>`.
 - **Control user-managed attributes in attribute-based access control (ABAC)**: From Mattermost v10.11 (Enterprise Edition Advanced), user-managed attributes are excluded from ABAC rules by default to prevent unauthorized access. System admins can enable them with a configuration setting. Learn more about enabling user-managed attributes in ABAC rules in the :ref:`User Attributes documentation <administration-guide/manage/admin/user-attributes:before you begin>`.

source/administration-guide/manage/admin/user-attributes.rst

@@ -105,6 +105,9 @@ You can define and manage up to 20 system attributes using the System Console. E
   - **Hide when empty**: The attribute is only visible in user profiles when it has a value.
   - **Always hide**: The attribute is never visible in user profiles.
 
+.. note::
+  If an attribute is created or updated without explicit visibility or sort order (for example via API or automation), Mattermost returns default values in responses even if those attributes weren't stored. Visibility defaults to the server's default visibility, and sort order defaults to ``0``.
+
 4. Configure user editing permissions (Mattermost v11 or later) by enabling or disabling the **Editable by users** option.
 
 5. Save your changes.
@@ -122,6 +125,9 @@ Manage attributes
 
 - **Delete**: Delete attributes you no longer need or want by selecting **More** |more-icon| and selecting **Delete property**.
 
+.. note::
+  When updating custom profile attributes via API or automation, the ``attrs`` object replaces existing attribute settings rather than merging. If you send only visibility, the sort order resets to ``0`` unless you include ``sort_order`` in the same request. If a patch fails, the API may return the error string "Unable to patch Custom Profile Attribute field".
+
 - **User Edit Permissions**: From Mattermost v11, all user attributes are admin-managed by default for enhanced security. To allow user editing for specific attributes, administrators can enable this through the **More** |more-icon| menu and selecting **Allow user editing**. This should only be enabled for attributes that do not impact security access controls or organizational policies. Attributes used in ABAC policies should remain admin-managed unless there's a specific business need and the security implications are fully understood.
 
 - **Edit User Attribute Values**: From Mattermost v11.1, you can view and update custom profile attribute values for individual users through the System Console. See the :ref:`Manage user attributes <administration-guide/configure/user-management-configuration-settings:manage user attributes>` documentation for details.