This article gives a high-level overview of the process of migrating existing content to your new Help Center knowledge base and community.
Topics covered:
Migrating content to the knowledge base
Migrating content from an external system into Help Center is a multi-step process where data from one step is required for subsequent steps.
Planning is critical. You'll need to map the structure of your legacy content to Help Center's 3-layer structure:
Importing your authors as Zendesk users
First, import the authors of all your articles as Zendesk users. Article authors in Help Center must be Zendesk users with the role of "agent". An agent in Zendesk is not necessarily somebody who solves tickets. See Understanding Zendesk Support user roles.
To create Zendesk users with the API, see Create User in the Zendesk API docs. Make sure to set the role
attribute to "agent" in each POST request.
After a successfully creating a user, Zendesk returns the details of the user in the JSON response, including the user's new id:
{
"user": {
"id": 9873843,
"name": "Roger Wilco",
...
}
}
Record the id of each user. You'll need the ids to set the author_id
attribute of each article you create in Help Center.
Tip: You might want to create a map of each author id and their legacy articles.
If you plan on using organizations in user segments to segregate sections, the organizations have be to created before you create users. You can then assign the organization id to the user when creating the user. See Create Organization in the developer docs. If users will belong to multiple organizations, use organization memberships to add organizations to the user record.
Creating categories in the knowledge base
See Create Category in the Help Center API docs. Categories are collections of sections.
After creating a category, Zendesk returns a JSON response with the category's new id:
{
"category": {
"id": 37486578,
"name": "Super Hero Tricks",
"description": "This category contains a collection of Super Hero tricks",
"locale": "en-us",
"position": 2,
...
}
}
Record the id of each category. When you create the sections later, you'll need the ids to assign sections to specific categories.
Creating user segments (optional)
If you want to restrict access to certain sections in Help Center, you can assign user segments to the sections. See Create User Segment in the Help Center API docs.
After creating a user segment, Zendesk returns a JSON response with the user segment's new id:
{
"user_segment": {
"id": 7284
"name": "VIP agents",
"user_type": "staff",
"group_ids": [12, ...],
"organization_ids": [42, ...],
"tags": ["vip"],
"created_at": "2017-05-21T20:01:12Z",
"updated_at": "2017-05-21T20:01:12Z",
"built_in": false
}
}
Record the id of each user segment. When creating the sections later, you'll need the segment ids to assign access restrictions to sections.
Creating sections in the categories
See Create Section in the Help Center API docs. Sections are collections of articles.
Make sure to set category_id
and user_segment_id
(if any) in each POST request. Zendesk returns a JSON response with the section's new id:
{
"section": {
"id": 3457836,
"name": "Avionics",
"description": "This section contains articles on flight instruments",
"locale": "en-us",
"category_id": 3465,
...
}
}
Record the id of each section. When creating the articles later, you'll need the section ids to assign articles to specific sections.
Creating the articles in the sections
When you have all the section ids and user ids from the previous steps, you can create the articles. See Create Article in the Help Center API docs. In addition to title
and body
, make sure to set author_id
and section_id
in each POST request.
Note that all authors are automatically subscribed to their articles. If Help Center has been activated, they'll get an email notification when the article is created.
Zendesk returns a JSON response that looks as follows:
{
"article": {
"id": 37486578,
"author_id": 3465,
"promoted": false,
"position": 42,
"comments_disabled": true,
"section_id": 98838,
...
}
}
Uploading attachments (if necessary)
If an article has inline images that aren't hosted on a public file server such as Amazon S3, upload the images to Help Center. See Create Unassociated Attachment in the developer docs. Make sure to set inline
parameter to true
.
Zendesk returns a JSON response with a url (content_url
) for the attachment:
{
"article_attachment": {
"id": 1428,
"article_id": null,
"file_name": "icon.jpg",
"content_url": "https://company.zendesk.com/hc/article_attachments/1428/icon.jpg",
"content_type": "application/image",
"size": 58298,
"inline": true
}
}
Use the content_url
to update the image url in the article HTML.
See also Associate Attachments in Bulk to Article.
Importing article comments
To import comments, you'll need an author id and the article's id. Both agents and end users can be authors of comments. See Create Comment in the developer docs.
Note that a comment author is automatically subscribed to the article. If Help Center has been activated, they'll get an email notification when the comment is created.
Migrating content to the community
Importing community content has many of the same considerations as importing a knowledge base. You'll need to import users to assign authors to posts. You'll also need to map the structure of your legacy community content to the two-layer structure of the Help Center community:
Creating user segments (optional)
If you want to restrict access to certain topics, you'll need user segment ids. See Create User Segment in the developer docs. When creating the topics later, you'll need the user segment ids to assign access restrictions to topics.
Importing topics in the community
See Create Topic in the developer docs. If applicable, make sure to set user_segment_id
in the POST request.
Zendesk returns a JSON response with the topic id:
{
"topic": {
"id": 115000553548,
"name": "Help Center-Tricks",
...
}
}
Record the id of each topic. When creating the topics later, you'll need the topic ids to assign posts to specific topics.
Importing posts in the topics
See Create Post in the developer docs. In addition to title
and details
, make sure to set author_id
and topic_id
in each POST request.
Unlike KB articles, authors of community posts can be agents or end users.
When creating a post, the author is automatically subscribed to all updates in that topic and will be notified when a new post is created or updated.
All subscribers of the same topic receive an email notification when the post is created. To prevent subscribers from being overwhelmed by notifications when bulk importing posts, include a notify_subscribers
parameter with a value of false
in your POST requests.
{
"post": {
"id": 35467,
"author_id": 89567,
"title": "Help!",
"details": "My printer is on fire!",
"notify_subscribers": false,
...
}
}
Importing comments in the posts
After creating the posts and getting their ids, you can now add their associated comments. See Create Comment in the developer docs.
Comments can only be created one at time. When creating a post comment, the author of the comment is automatically subscribed to all updates in that topic and will be notified when a new post is created or updated.
All subscribers of the same topic receive an email notification when the comment is created. To prevent subscribers from being overwhelmed by notifications, include a notify_subscribers
parameter with a value of false
in your POST requests.
10 Comments
Follow this manual or just use a simple service Help Desk Migration to migrate your knowledge base to Zendesk https://help-desk-migration.com/zendesk
Hi folks - the link to "import users" is broken on this page, looks like this: https://support.zendesk.com/hc/en-us/articles/(https://developer.zendesk.com/rest_api/docs/core/users#create-user
JFYI
Hi Nick, thanks very much for pointing this link out! I've now fixed the problem, and the link is working now.
You mention above that authors need to be agents. Can they be Light Agents or do they need to be Full Agents? I am asking because I will be migrating content from an existing knowledge management platform into Zendesk and some of the articles are written by people who no longer work at the company...what do you recommend in such a scenario?
Hello Mercedes,
Thanks for your question!
When you're passing an article into Zendesk through the API, the system doesn't care so much who the original author is, so long as an authorized user is referenced as the author.
So regardless of who wrote the article in your former platform, so long as you give Zendesk a value for the author when you create the article, and said author has an agent equivalent role within Zendesk with the appropriate Guide permissions, your article creation will go over just fine.
Regarding whether a light agent can do this, it depends on the level of your subscription and the permissions granted to agent roles for your account:
That comes from our document on Understanding Guide Roles and Setting Permissions.
Hopefully this clears things up!
Hi Skip,
Any guidance on migrating existing content from Discourse? My company's current user articles are located within that platform and it seems quite intensive to be able to migrate to Zendesk.
Any tips? Or posts you can point me to?
Thanks in advance,
Mercedes
Hi Mercedes,
I reached out internally and it doesn't look like we have much information to provide with regards to migrating data over from Discourse to Zendesk. Your developers will want to use the Discourse API to export that data from Discourse and use the Zendesk API to import that data into Guide.
I hope the above information helps!
Hi Skip,
Could you give me a guideline on migrating from tiki wiki CMS groupware to Zendesk. I haven't found any way of doing so.
Hey Aziz,
We don't have any resources available that help with migrating content over from tiki wiki CMS groupware to Zendesk. If you need assistance migrating your content over, we do have a professional services team available that can assist with getting this set up at an additional cost.
Let me know if this is something you're interested in and I can connect you with your Account Manager to discuss further.
Cheers!
Hi Brett,
Any guidance on migrating existing content from Confluence, ensuring moves as a draft, so it may then be submitted for review?
We have an Enterprise licence.
Thanks!
Please sign in to leave a comment.