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 api@zendesk.com and we will do what we can to help.
6 Comments
This article was updated to clarify that permission_group_id is required for article creation.
"After February 8th, 2019 you will need to provide a permission_group_id at article creation."
Please note the new changeover date of February 8th, 2019 to allow developers more time to incorporate the new required field.
Question: How can the ability to create an article be governed on a per-article bases?
Greg,
Sorry for any confusion. I've updated this article to reflect how creation permissions will work, specifically:
"The ability to limit a user's ability to edit/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."
Thanks for clearing up the text Daniel.
Creation permissions are set at the Category level, correct?
Hi Greg. Don't know if you got your question answered -- article creation and publish rights are controlled through a combination of User Segments and Management Permissions.
All agents who have been given 'Guide Admin' privileges (Admin > People > Roles/Edit > Guide/Can Manage Guide) are in the built-in 'Managers' user segment. Outside of the built-in Managers user segment, you can further narrow article editing and creation down to just the user segments you want through Management Permissions (Guide Admin > User Permissions > Management Permissions).
You create a Management Permission entry that contains the User Segments that you want to Edit and/or Publish.
Example:
Identify a set of users through the tags they have and/or groups that they belong to:
Assign that User Segment to a Management Permissions entry. It's the "Edit permissions" portion that controls who can create new articles.
The users that meet the criteria set in the "Article Creators Users Segment" can now create and edit articles. In this case, anyone who is in the "Content Creators" user group (defined in Admin > People > Groups/Edit).
Hope this is in line with what you were looking for and maybe clarifies things.
Please sign in to leave a comment.