Migrating existing content to Help Center

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 to the community

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.