Categories
This guide covers how to create, edit, and manage Zendesk categories at GitLab. Administrators should review the Administrator tasks section.
Technical Details
- Deployment type:
Standard - Sync repos
CustSuppOps Zendesk Test Suite Generatorenabled
Understanding categories
What are categories
As per Zendesk:
Categories are the top-level organizing containers of the help center. Categories contain sections. The help center must have at least one category. If you have only one category in your help center, then the category itself is hidden to end users, and they see only the sections in your help center.
The knowledge center uses a three-level structure:
- Categories (top level) - Organize major topic areas, documented on this page
- Sections (middle level) - Subdivide categories into related groups, documented on sections page
- Articles (content level) - Individual help articles, documented on articles page
How we manage categories
While Zendesk offers a full way to manage categories via the UI, we turn to a more version controlled methodology. This allows for a set review process, the ability to perform rollbacks as needed, etc.
That being the case, we utilize sync repos.
Current categories in use
- Zendesk Global
- Zendesk US Government
Creating a category as a non-admin
For the creation of a category, please create a Feature Request issue (as it will require manual intervention by the Customer Support Operations team).
Editing a category as a non-admin
For the modification of a category, please create a Feature Request issue (as it will require manual intervention by the Customer Support Operations team).
Deleting a category as a non-admin
To request the deactivation of a category, please create a Feature Request issue (as it will require manual intervention by the Customer Support Operations team).
Administrator tasks
Note
- All sections in this section require
Administratorlevel access to Zendesk.
Viewing categories in Zendesk
To see the current categories in Zendesk:
- Navigate to the knowledge center dashboard for the Zendesk instance
- Click the
Arrange contenticon on the left side
Creating a category
Warning
- This should only be done if there is a corresponding request issue (Feature Request, Administrative, Bug, etc.). If one does not exist, you should first create one (and let it go through the standard process before working it).
- SEO Impact: Categories affect URL structure, search indexing, and article discoverability. Changing category names or structure can break existing links and impact search engine rankings.
- Exercise caution if you make changes to categories.
For the creation of a category, you will need to create a MR in the sync repo. The exact changes being made will depend on the request itself. A starting template you can use would be:
---
name: 'Your category name here'
previous_name: 'Your category name here'
description: 'Your description here'
locale: 'en-us' # This should always be used
position: 0 # Integer representing category display order
source_locale: 'en-us' # This should always be used
After a peer reviews and approves your MR, you can merge the MR. When the next deployment occurs, it will be synced to Zendesk.
Editing a category
Warning
- This should only be done if there is a corresponding request issue (Feature Request, Administrative, Bug, etc.). If one does not exist, you should first create one (and let it go through the standard process before working it).
- SEO Impact: Categories affect URL structure, search indexing, and article discoverability. Changing category names or structure can break existing links and impact search engine rankings.
- Exercise caution if you make changes to categories.
To edit a category, you will need to create a MR in the sync repo. The exact changes being made will depend on the request itself.
After a peer reviews and approves your MR, you can merge the MR. When the next deployment occurs, it will be synced to Zendesk.
Changing the name of a category
If you need to change the name of a category, copy the current value into the previous_name attribute and then change the name attribute. This allows the sync to still locate the category in question to update.
Deleting a category
Danger
- This should only be done if there is a corresponding request issue (Feature Request, Administrative, Bug, etc.). If one does not exist, you should first create one (and let it go through the standard process before working it).
- When you delete a category, all the sections contained in the category are also deleted, and all the articles (including any translations) contained in the sections are archived.
- Exercise extreme caution in doing this.
As the sync repos do not perform deletions, you will have to do 2 actions to delete a category.
First, you must delete the corresponding file from the sync repo. After a peer reviews and approves your MR, you can merge the MR.
After that is done, you then must delete it from Zendesk itself.
To delete a category from Zendesk:
- Navigate to the category list
- Click the three vertical dots to the right of the category you wish to delete
- Click the
Edit category - Click
Delete categoryon the left-hand side - Click
OKto confirm the change
Performing an exception deployment
To perform an exception deployment for categories, navigate to the categories sync project in question, go to the scheduled pipelines page, and click the play button for the sync item. This will trigger a sync job for the categories.
Common issues and troubleshooting
Not seeing category changes after a merge
As categories follow the Standard deployment type, they would only be deployed during a normal deployment cycle (or when an exception deployment has been done)
0df0e02d)
