There are many ways to migrate content from one help center to another. This article primarily focuses on using your help center API to programmatically import content, and gives a high-level overview of the process of migrating existing content to your new help center knowledge base and community. You can also migrate content using the following approaches:
- Copying/pasting - If you are only migrating a few articles, then the fastest and easiest way is to simply copy and paste content from your previous help center into a new Guide article.
- Professional services - If you have large or complex migrations, you can hire Zendesk to help you with your migration.
- Partner Apps - You can explore the Zendesk apps marketplace to find partner apps such as Help Desk Migration.
This article covers the following topics:
Migrating content to your knowledge base
Migrating content from an external system into your 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 your help center's three-layer structure:
Importing your authors as Zendesk users
First, you must import the authors of all your articles as Zendesk users with the role of "agent" (an agent in Zendesk is not necessarily someone who solves tickets (see Understanding Zendesk Support user roles).
To create Zendesk users with the API (see Create user). Ensure you set the
role
attribute to "agent" in each POST request.
{
"user": {
"id": 9873843,
"name": "Roger Wilco",
...
}
}
Record
the ID of each user as you'll need the IDs to set the author_id
attribute of each article you create in your help center.
If you plan on using organizations in user segments to segregate sections, you must create the organizations before you create any users. You can then assign the organization ID to the user when you are creating the user (see Create organization). If your users will belong to multiple organizations, then use organization memberships to add organizations to the user record.
Creating categories in your knowledge base
{
"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, because when you create 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 your help center, you can assign user segments to your sections (see Create user segment).
{
"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 because when you are creating sections later, you'll need the segment ID to assign access restrictions to the sections.
Creating sections in your categories
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 because when you create articles later, you'll need the section IDs to assign articles to specific sections.
Creating articles in your sections
title
and body
, make sure you set the
author_id
and section_id
in each POST
request.{
"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, then upload the images to your help center (see Create unassociated attachment).
Ensure you set the inline
parameter to
true
.
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 HTML of the
article (see Associate attachments in bulk to
article).
Importing article comments
Migrating content to your 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 your help center community:
Creating user segments (optional)
If you want to restrict access to certain topics, you'll need user segment IDs (see Create a user segment). When creating the topics later, you'll need the user segment IDs to assign access restrictions to topics.
Importing topics in your community
If applicable, ensure you set the user_segment_id
in the POST
request (see Create topic).
Zendesk returns a JSON response with the topic ID:
{
"topic": {
"id": 115000553548,
"name": "Help Center-Tricks",
...
}
}
Record the ID of each topic because when you create topics later, you'll need the topic IDs to assign posts to specific topics.
Importing posts in topics
In addition
to the title
and details
, make sure you set
the author_id
and topic_id
in each POST
request (see Create post).
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 to 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 posts
After creating the posts and getting their IDs, you can now add their associated comments (see Create comment).
You can only create one comment at a time. When creating a post comment, the author of the comment is automatically subscribed to all updates to that topic and are 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.
13 comments
Alissa Wilczynski
I have content in 3 languages, where English is the "parent language" and Chinese and Japanese are linked as "child" articles. I need to move this content to Zendesk. How do I migrate while maintaining these linkages between languages?
1
Jim Davenport
For those that need to import content in bulk into their Help Center we've created an Import app which you can find in the Zendesk App Marketplace. It's a one-off payment to purchase the app, after which you can use the app to perform imports (categories, sections, articles and article comments) as often as you like.
You can find more information on our website and if you're interested or have questions, please don't hesitate to contact us.
-2
Maxine Clayman
Is it possible rather than to migrate existing content to the knowledge base to be able to link back to it so the bot can pick it up article suggestions from both the knowledge base and other sources?
0
Jason Schaeffer
Hi Maxine,
Unfortunately the Answer Bot can only suggest articles from within Zendesk and would not be able to pull in data from external sources. You can provide links in your Help Center articles to an external source but not directly from a Bot. There is more in the below article:
https://support.zendesk.com/hc/en-us/articles/360020318794-Inserting-and-editing-links-in-articles
Thank you!
Jason Schaeffer | Customer Advocate |
0
Ricardo Novais Pereira
Hi. How would it work for the migration of Content Blocks?
0
Anne Ronalter
The Help Center API has certain limitations if content blocks have been enabled for one or more articles.
More details on that topic can be found here:
https://developer.zendesk.com/documentation/help_center/help-center-api/using-the-help-center-api/content-blocks-limitations/
1
Cheyenne Trommels - Oorebeek
Hi, I have an interesting issue; one of my former colleagues has set two of our three help centers to the wrong version of English. We have three help centers, of which one is set to English UK (which is what we'd like to use), one to English US and one to English Netherlands.
This causes issues with for example dynamic content; we have to add all three versions of English here to get the correct translations to all Help Centers. It's also confusing as for end user languages it's not clear to which English we have to set their language. We want to use one version of English among all Zendesk Help Centers, Support etc. which should be English UK (en-gb).
I'm afraid I'm up to the task to manually create new translations in the correct English to each article and copy paste the content. Is there a way to 'easily' export/import articles and set them to a different language and solve this issue with less manual work?
0
Sharmila Govindarajan
Hi I am trying to create an article in a section as described in this article and am getting a 403 forbidden error. I do have Admin access to our Zendesk site. Can someone help me resolve this?
0
Jupete Manitas
Hi Cheyenne, thanks for writing in!
If the end goal is to provide English UK and English Netherlands Help Center, yes, you need to have translated content (Category, Section & Articles) for both languages including dynamic content then delete the wrong language once completed. In terms of automating the translations translating the content is not natively supported in the UI. Translations are being done outside Zendesk and use API to import the translated content. You can use third-party solutions for managing translations for example. To learn more about other solutions, you can check them here: Creating and managing translated content for your Zendesk Guide knowledge base.
-2
Natalia Tomchyshyn
The Zendesk team already mentioned Help Desk Migration as an option. The data transfer tool helps to migrate language versions of help centers. To check it, test the service for free to see if it meets your requirements accuratelly.
-2
Helpandoit Vendor
Helpando.it (their team worked at Zendesk before) specialises on custom Ticket & Help Center migrations. This is their migration partner page.
3
SeaSpace
+1 for Helpando.it - Zendesk Migrations
They Migrated our Help Center data from a clunky home made system.
2
SeaSpace
Hi Amy Rands, as stated on the other thread, for both the account merging and a recent Jira migration they charged less than the other providers we reached out to + were able to cater to our custom mapping requirements.
2