Changes to Guide Article Management Permissions

Currently, the ability to create, update, and delete articles in a section is governed by a combination of the manageable_by and user_segment_id properties using the Sections API. Beginning September 27th, 2018, permissions will be managed on a per article basis using the Articles API and Management Permission Groups API.

The ability to limit a user's ability to edit and publish articles to a single section will no longer be available. An agent with permission to create an article will be able to do so in any section.

This change will be optional until February 8th, 2019, when it will become permanent. Until that time, behavior will be backward compatible as long as the old method is used. Once an account begins to make use of the new behavior (managing these permissions on individual articles), they can no longer rely on the section value being a source of truth. We recommend making and testing changes to any code in your sandbox before using the new method in production.

If you currently use the Sections API to control management permissions, see the information below to take advantage of the new features that the Management Permission Groups API offers. 

Examples

The following examples show how permissions are changing.

OLD METHOD

This example updates a section using the old method of managing permissions. Updates were applied against using the Sections API and manageable_by and user_segment_id attributes:

curl https://{subdomain}.zendesk.com/api/v2/help_center/sections/{section_id}.json \
  -d '{ \
    "section": { \
      "manageable_by": "staff", \
      "user_segment_id": 12 \
    } \
  }' \
  -X PUT -v -u {email_address}:{password} -X PUT -H "Content-Type: application/json"

NEW METHOD

The new approach uses the Permission Groups API and Articles API. This example shows an update to a permission group, then applies that permission group to an article:

curl https://{subdomain}.zendesk.com/api/v2/guide/permission_groups/{permission_group_id}.json \
  -d '{ \
    "permission_group": { \
      "edit": [12], \
      "publish": [12] \
    } \
  }' \
-X PUT -v -u {email_address}:{password} -X PUT -H "Content-Type: application/json"

(In the above API call, `12` refers to a specific user_segment_id)

The permission group is then applied to the article:

curl https://{subdomain}.zendesk.com/api/v2/help_center/sections/{section_id}/articles/{article_id}.json \
  -d '{ \
    "article": { \
      "permission_group_id": 42 \
    } \
  }' \
-X PUT -v -u {email_address}:{password} -X PUT -H "Content-Type: application/json"

After February 8th, 2019 you will need to provide a permission_group_id at article creation. 

Backward compatibility details

The property manageable_by will not be deprecated immediately and will be backward compatible during the transition to Management Permission Groups. This is done transparently on the backend by syncing sections with a matching Management Permission Group. The following list covers the details and caveats of the API backward compatibility.

• If you only read sections with the API, then you can continue exactly as you do today with no caveats.
• If you modify the properties user_segment_id or manageable_by of sections with the API, then you can continue with some caveats.
• If manageable_by is set to “staff”, a matching Management Permission Group is found or created and applied to the section.
• All articles in the section will have the aforementioned Management Permission Group applied.
• If the permission_group_id  is changed on an individual article, the manageable_by and user_segment_id values shown in parent section may no longer accurately represent who can manager articles in the section.
• This can leave an account with many management permission groups that are automatically created by the system.

API Available: Sept, 27 2018

API Changeover Date: Feb 8, 2019

Please share this with your engineering team or those responsible for your Zendesk Apps and integrations. If you have any questions about how to migrate your App or require an exception, please send an email to [e-mail] and we will do what we can to help.