Whats, Whys, and Hows of Importing Data to Zendesk

Zendesk Import: Diving into the Ways and Details

Many companies strive to get the perks technology offers. The help desk software drives the change along with simplifying the customer support routine. The complete migration plan has a detailed description of the processes, responsibilities, and timeframes. That’s the wise way to lower the risk of overriding budget and “surprise” staff with the tasks they have to do.

Before becoming Zendesk data, your records should go through the extract, transform, and load processes. The transform process is optional, the other two are inevitable. Either the organization import from dump SQL or from old help desk platform, the most important is the data. The amount and quality impacts on the decision to leave or to take data to Zendesk. The number of contacts, tickets, agents, and knowledge base content might get stuck due to

What data is wanted on the new shiny help desk platform? The major interest is shaped into importing users (agents and agent groups), contacts, companies, tickets, and a knowledge base.

The next question is how to get that data to Zendesk? Here we are going to provide tips on how to do this in three different ways: CSV importing, database or dump SQL migration and API-based data transfer.

Customer support data can be imported via CSV files. It sounds simple and implies the sense that this can be done fast. Zendesk supports bulk data import that works on specific conditions. Roughly speaking, you can import users (by that meant contacts and companies,) agents, agent groups, as well as and knowledge base into Zendesk Guide. To move tickets, you should use API. Thus, you may face a set of roadblocks to successful organization import. The import process also has some limitation for the plan tier you bought and some other limitation that will be covered here. So, keep on reading.

How to Make a Valid CSV File

Before jumping to Zendesk import, let’s find out a bit about CSV files and how to compile them right. CSV stands for comma-separated values. The simple examples are a spreadsheet or database. The programs where data stored in tables allow importing or exporting files in this format.

To be more specific, here is a sample of a table:

ContactTitleEmailTag
John DoeSenior Manager[email protected]Spoke Tuesday, he's interested
Harry WinstonHead of Sales[email protected]said to call again next week
Cheryl ColeDevelopment Director[email protected]Not interested, gave a referra

Note: if your records have a comma inside, you should take it into double quotes to avoid using those commas as delimiting signs.

Here’s what the records should look like in CSV:

Contact,Title,Email,Tag

John Doe,Senior Manager,[email protected],”Spoke Tuesday, he's interested”

Harry Winston,Head of Sales,[email protected],”said to call again next week”

Cheryl Cole,Development Director,[email protected],”Not interested, gave referral”

The header is tent to be optional (but for Zendesk import it is obligatory.) This first line of the file has the same format as the other record lines. It describes the names of the corresponding fields in the file. The header and the rest of the records in the file should contain the same number of fields.

Here’s an example of CSV file:

field_name,field_name,field_name

aaa,bbb,ccc

ddd,eee,fff

Another rule of CSV format to remember states that each line should have the same number of fields throughout the file. Spaces are considered a part of the fields and shouldn’t be ignored. Besides, the last record in line must not have a comma.

What is UTF-8 format? It is the dominant character encoding for the World Wide Web. To fix the error: invalid byte sequence in UTF-8, you need to open your file in Google Sheets Document (or Notepad, or Microsoft Excel) and save it again selecting UTF-8 encoding. In case, you exported the CSV file from the software, then check the options (maybe you can choose the format) and re-export the records again.

Zendesk Data Import Limitations

Within Zendesk, you can import the core data: users and organization. The option of bulk import is available for customers of

  • Essential
  • Team
  • Professional
  • Enterprise

Important: if you are going to use this Zendesk importing option, the organizations should be imported before the users.

Let’s take a look at some small, yet noteworthy issues that set limits in data import:

  • The bulk import doesn’t allow you to import timezones, photos, language preferences, and the like.
  • Your CSV file should contain up to 2000 rows of records: one row for the header and the rest for the company data.
  • You can import one CSV file (up to 2000 rows of data) per time.
  • If your file has more than 1999 rows of data, you should create two separate batches and then import them.

Setting up a CSV File for Bulk Import

A CSV file should be created in accordance with the specific requirements. It might be useful to give a little background here.

A List of Fields for Organizations Import

The mere enlisting of fields available for bulk import may be confusing. That’s why each field has a brief description to get the point.

nameThis field is required and represents the organization name.
external_idIf you have a unique identifying ID inside your documentation that differs from the organization’s name, you can import it via this field.
notesThese are some notes about the organization. Only agents can see them, the end-users (aka customers) can’t see them.
detailsThe field contains the detail information about the organization. Only agents can see them, the end-users can’t see them.
defaultHere you should add one or more email domains separated with spaces. This field is used for mapping end-users to an organization.
sharedTrue or false. It sets the organization as a shared one.
shared_commentsTrue or false. In case this field is true, it allows all users in the organization to add comments to each other’s tickets. Note: the “shared” field also should be set true to make it work.
groupHere you can enter a default (agent) group for the organization. Later this mapping can be changed, and the organization’s tickets will be assigned to the group you select in the menu: Admin > People > Organizations > Group.
tagsThis field will contain tags. Use a space to separate each tag. This option will work after it has been enabled in the menu: Admin > Customers > Tags on users and organizations > Enabled. Important: this option is available for Team, Professional, and Enterprise plans.
custom_fields.<field key>

You can import a custom organization field using a custom_fields. prefix and a field key. Simple example: for the field key registration_date, you should set value: custom_fields.registration_date

Important: to locate the key for a custom organization field, you should go to Admin > Organization Fields > click on the name of a custom field. After that, it appears in the properties panel on the right.

If you want to set the value of drop-down list options, you must use the tag added while the drop-down list was created.

How to Import the CSV Organization File

The bulk import allows to import new information about the organizations or update the existing one.

The CSV importing needs five steps to complete:

  1. Click the Admin gear icon in the sidebar, and then clicking on People.
  2. Choose Bulk Organization Import.
  3. Select the import type you need:
    • Create new organizations
    • Update existing organizations
  4. Click Choose File or on the link Let me paste in data instead.
  5. Click Import.

After that, your files are added into the queue. When the import process is complete, the organizations are added to your Zendesk Support. You will get an email when everything is done.

Note: Within the bulk import, you can add two batches to the queue at once. In case, there are more batches to import, you should wait until the importing of the first batch is finished. Only then you can import another batch.

About further updating: In case, you decide to update the data via the bulk import, remember the following. Updating the existing organizations means replacing the current data with the records from CSV file. It is wise to include only fields that you want to update, and the other columns left blank. So the empty columns will be overwritten with the existing data.

A List of Fields for Users Import

When compiling a user import CSV file, you can add the following fields.

Important: the name, email, and restriction fields are obligatory for importing new users. For the update, you will need only one unique identifier (for example an email or external ID.)

nameHere you add a full user’s name.
emailAdd here user’s email address. You can add more primary and secondary emails for a single user. Simply give the same external ID to emails of the user and the ID will route all emails to this user.
external_idHere you can import user’s ID that differs from the user’s email address (agent ID or customer reference number.) External IDs must be unique for each user.
detailsThis field allows adding extended information about the user. Only agents can see them, the end-users can’t see them.
notesThese are some notes about this user. Only agents can see them, the end-userscan’t see them.
phoneThe user’s phone numbers are imported here. Add the unique phone numbers as direct lines, the existing phone numbers as secondary lines. You also can add more than primary and secondary phone numbers for a single user. Give the same external ID to phone numbers of this user.
shared_phone_numberTrue or false. In case this field is true, it is a shared phone number. The shared phone number can’t be set as a user identity.
roleThis field is a case sensitive. Here you add “End-user,” “Agent,” or “Admin.” If you don’t fill in the role, the user will be set to end-user.
restrictionThis field is required for new users when the user’s role is an agent. It sets the privileges, the access to the tickets, and the like. You can add one of the values:
  • assigned means tickets assigned to this agent
  • groups means the tickets in this agent’s groups
  • none means there is no restriction and the agent can access all tickets
  • organization means the tickets requested by users in this agent’s organization
  • requested means that the agent is the requester and this is their tickets
  • Light Agent means that a user has the same restriction of a light agent
organization

In this field, you add the organization where the user will be imported. The organization should already exist; otherwise, your import will fall.

In case, you are a customer of Professional and Enterprise plans, you can add a user to multiple organizations. All you need to do is to enter multiple organizations separated by a pipe character in the organization sell of your CSV user data file. It supposed to look like this: Organization1|Organization2|Organization3. But you should note that the user’s default organization will be the first organization alphabetically.

tags

This field will contain tags. Use a space to separate each tag. This option will work after it has been enabled in the menu: Admin > Customers > Tags on users and organizations > Enabled.

brand

In case your account has multiple brands, here you can specify a subdomain (use mydomain and not mydomain.zendesk.com.) The selected subdomain predetermines the welcome email sent to the user on condition that the brand is active and has an enabled help center. If the brand isn’t active, doesn’t have an enabled help center, or doesn’t exist, the column will be ignored.

custom_fields.<field key>

You can import a custom user field using a custom_fields. prefix and a field key. Simple example: for the field key registration_date, you should set value: custom_fields.registration_date.

If the information imported into a checkbox, add “true” if it checked or “false” to leave it unchecked.

Important: to locate the key for a custom organization field, you should go to Admin > User Fields > click on the name of a custom field. After that, it appears in the properties panel on the right.

If you want to set the value of drop-down list options, you must use the tag added while the drop-down list was created.

The Peculiarities of Assigning Custom Agents Roles

The Enterprise plan gives an option of assigning agents predefined custom roles. They have more permissions than the standard restrictions. Here are the roles and their descriptions in brief:

You can create own custom agent roles. To import it, use the name of this role in the “restriction” column. Let’s say you use a role that doesn’t exist in Zendesk, and then your agent will be set to Light Agent. The role can be changed manually in your profile.

How to Import the CSV User File

The CSV user importing needs five steps to complete:

  1. Click the Admin gear icon in the sidebar, and then clicking on People.
  2. Choose Bulk User Import.
  3. Select the import type you need:
    • Create new users
    • Update existing users
  4. Click Choose File or on the link Let me paste in data instead.
  5. Click Import.

After that, your files are added into the queue. When the import process is complete, the organizations are added to your Zendesk Support. You will get an email when everything is done.

Google Docs Importer for the Knowledge Base

The knowledge base can be imported into Zendesk Guide by means of their native tool Google Docs importer.

Who can use it?

The option is available for Lite, Professional, and Enterprise plans.

How does it work?

You must be a Guide Manager to connect and import Google Docs, then you can upload Google Docs from your Google Drive. Due to the doc import, the document images and formatting will be handled appropriately. However, your Help Center theme will define the rendering of the content.

The Google Docs and your articles aren’t synced. Also, you can’t export them to Google Docs from the knowledge base.

If you receive an error message, that means the import may have exceeded the API requests. The Google Docs importer relies on the API and support Essential accounts have a limit of 10 requests per minute.

Import a Google doc into Zendesk Help Center

  1. In your Zendesk Guide, go to Arrange content > Import articles.
  2. If you aren’t signed in your Google account, click Connect. In case, you haven’t connected your Guide to Google Drive, the clicking Connect will walk you through the process of signing in to your account and granting the access for Zendesk Guide. Then click Next.
  3. In Select documents, click Open file picker. Then you will see all the folders and files that you can access. Search the file(s) you want to import and click Select.

    Note: you can import up to 100 files at a time.

  4. You may find the files in the Import Articles admin page. If you want to choose a different file, click Redo document selection. When you finished, click Next.
  5. In Place documents, click Select section to define a section for this article in your Help Center. Click Next. After importing the articles aren’t published. For Lite and Professional customers, the docs are imported as drafts, and Enterprise customers the docs are imported as work in progress articles.
  6. In Start import, click Start import. Don’t close the window while the import runs. The importing time depends on the number of files you selected to upload.
  7. When the import is finished, click Have a look to go to Arrange articles or click Start a new import to add more Google Docs.

CSV Import Weak Spots

There are three roadblocks that you may run into when getting your data to Zendesk via bulk import:
  1. The bulk import doesn’t allow you to import data not listed for the CSV file. To import more records, you need to use the Zendesk REST API.
  2. You can not import contact information of the end-user from Facebook or Twitter accounts. That can be done only via the Zendesk REST API.
  3. The bulk import doesn’t support the option of importing tickets. You can add them to your Zendesk Support via REST API.

Master the Art of Database Migration

When you decided to migrate records from the database to Zendesk, that may seem like a real pain in the neck. Start with figuring out details, and then decide whether to include this migration method to your project or look for another option.

What Is Behind a Database Migration?

Roughly speaking, the database migration is the old good CSV export of files from your current software and further importing into Zendesk. In the best-case scenario, you can extract CSV (or XML) from the database or get the SQL dump file. Either way, later you will have to format the received file into CSV that correspond to Zendesk requirements.

Currently, software providers offer built-in import and/or export tools. So, technically, you can generate a CSV export from your old help desk platform or another legacy system without any coding or extra help from a developer or other technician. All this possible if your software or database provides this option.

How to Export Data from a MySQL Database

If your current system uses MySQL database as storage, then you can export the SQL dump. This file will contain all the data of your old system. That’s a plus side. You can transfer any data from that file. But you should select the records that can be imported into Zendesk: spend time and efforts to form valid CSV files, and this is a drawback.

How do I make the SQL dump of the MySQL database on the command line?

There are two ways to make the dump that depends whether your MySQL user has a password.

  1. if your MySQL user has a password, then

    mysqldump -h localhost -u [MySQL user, e.g. root] -p[database password] -c --add-drop-table --add-locks --all --quick --lock-tables [name of the database] > sqldump.sql

    Important: do not put space between -p and the password.

  2. if there is no password, then

    mysqldump -h localhost -u [MySQL user, e.g. root] -c --add-drop-table --add-locks --all --quick --lock-tables [name of the database] > sqldump.sql

    Databases have a set of utilities, where you can find the export utility. Note that some utilities may extract only certain types of records. That’s why you need to check what data you can get with them and if it will enough to compile the CSV file for Zendesk import.

Extracting data using Oracle export utility

Let’s look at the Oracle exp utility as an example. To get started, here are a six steps export guide:

You can use a set of other parameters with EXPDP command. Visit the Oracle base for more parameters.

Enlisting Records Supported in Zendesk Bulk Import

Currently, Zendesk provides the customers of Essential, Team, Professional, and Enterprise plans with the bulk import option. To be specific, you can import your contacts, companies (aka organizations in Zendesk), agents (and apply restrictions to add an agent to a group). Thus, there is a limit of record types as the extended import available via REST API. The tickets can be imported only via REST API too. The mentioned above record types are divided between two bulk import options: organizations and users.

The Organization Import Fields

Your CSV file for importing organizations should include the following fields:
  • name (a required field, represents a company name)
  • external_id (a unique identifying ID different from a company name)
  • notes (only agents can see them)
  • details (address or some other information)
  • default (email domain, one or more separated with spaces)
  • shared (true if the organization is shared)
  • shared_comments (true if all users in the organization can add comments to each other’s tickets)
  • group (a default (agent) group for the organization)
  • tags (the option should be enabled in Zendesk before importing)
  • custom_fields.<field key> (e.g. the field key registration_date, set value: custom_fields.registration_date)

The User Import Fields

The CSV file for importing users into Zendesk Support may include the following list of fields.
  • name (a required field, a full user’s name)
  • email (a required field, user’s email address. You can add primary and secondary emails. Give the same external ID to user’s emails.)
  • external_id (user’s ID that differs from the user’s email address)
  • details (extended information about the user. Only agents can see them)
  • notes (only agents can see them)
  • phone (the user’s phone numbers are imported here. You can add primary and secondary phone numbers for a single user. Give the same external ID to phone numbers.)
  • shared_phone_number (If it is true, it is a shared phone number.)
  • role (This field is a case sensitive. You can add “End-user,” “Agent,” or “Admin.” If there is nothing in the field, the user will be set to end-user.)
  • restriction (a required field if the user is an agent. It sets the privileges and the like. The values to add are:
    • assigned means tickets assigned to this agent
    • groups means the tickets in this agent’s groups
    • none means there is no restriction and the agent can access all tickets
    • organization means the tickets requested by users in this agent’s organization
    • requested means that the agent is the requester and this is their tickets
    • Light Agent means that a user has the same restriction of a light agent
  • organization (add the organization where the user will be imported. If you are a customer of Professional and Enterprise plans, you can add a user to multiple organizations. It supposed to look like this: Organization1|Organization2|Organization3.
  • tags (use a space to separate each tag)
  • brand (If you have multiple brands, you can specify a subdomain (use mydomain and not mydomain.zendesk.com.)
  • custom_fields.<field key> (e.g. the field key registration_date, set value: custom_fields.registration_date)

Zendesk Bulk Import Guide

To import these CSV files follow the instruction:
  1. Go to the Admin gear icon, and then clicking on People.
  2. Select the type of the CSV file you are going to import:
  3. Select the import type you need:
    • Bulk Organization Import.
    • Bulk User Import.
  4. Select the one you need:
    • the import type Create new organizations
    • the import type Create new users
  5. Click Choose File or on the link Let me paste in data instead.
  6. Click Import.

Getting the Knowledge Base to Zendesk

Concerning the knowledge base migration, it is available via Google Docs Importer in Zendesk Guide. The customers of Lite, Professional, and Enterprise plans can get their articles from Docs to drafts (for Lite and Professional) or work in progress articles (for Enterprise) in Zendesk Guide.

The Google Docs Importer works via API. When the limits of 10 requests at a minute exceeded, you will receive an error message. Also, you can import up to 100 files at a time.

There are several steps to take:

  1. Go to Arrange content > Import articles.
  2. Click Connect to sign in your Google account and grant the access for Zendesk Guide. Then click Next.
  3. In Select documents, click Open file picker and choose files to import. Then click Select.
  4. In Place documents, click Select section to define a section for this article in your Help Center. Click Next.
  5. Click Start import and don’t close the window while the import runs. The more files you have selected, the longer import process will take.
  6. When the import is finished, click Have a look to go to Arrange articles or click Start a new import to add more Google Docs.

API Data Migration? It's Easy if You Do It Smart

Nearly every business owner has heard a piece of advice: “Just use API for importing data to Zendesk.” and thought to themselves “What is an API?” If you have Googled it, you saw dozens of results with acronyms, jargon, and unhelpful exposition. All that creates a rather vague or incorrect idea about what this term means.

What is an API?

An API stands for an Application Programming Interface. The term is heavily overloaded and may refer to several different things depending on the context. In Wikipedia you can get the broad explanation:

Technically, APIs explain the rules for developers to follow while they interact with a programming language, a software library, or any other software tool. However, this term is often used to describe a specific kind of web interface.

Web APIs represent a set of rules for interacting with a web server (for example a Zendesk server) usually for retrieving data. APIs give mechanisms for you to access and manipulate data stored by the API provider (here is Zendesk). The process looks like this:

  1. You make a “request” to a Zendesk web server.
  2. Then it accesses to a Zendesk database (with your data).
  3. After that, the web server returns it to you in a “response.”

Why Businesses Use the API?

The added value of the API is an extending functionality that isn’t available in the UI (both natively or according to your Zendesk plan). In that light, the API comes out as a resource for creating apps, bulk-import, pull data to external resources, and many more.

The Zendesk API is a part of a plan that is sold to companies. Organizations pay for Zendesk services and find the added value in the existence of API. It allows them to develop their own integrations or build applications.

Currently, Zendesk customers of Essential or Team price tiers can use API for direct exporting their data, while clients of Professional plan can even automate data exports. In the same way, you can use API to get a ticket, user, or any other type of data for reporting purposes. Within the ability list offered by API, you can find:

To find out more information about tasks that can be solved with API, visit this post at Zendesk Develop.

Overviewing the Format

Modern APIs prefer the JSON format, and Zendesk API returns data in this format too. If you want to send information to the API to create or update data in your Zendesk, you have to convert it to JSON first. In case, you want to get some data from Zendesk, it will send you it as JSON and, therefore, you should convert it to something that can be used. For more details on Zendesk JSON, go here.

The formatted data can be viewed in your web browser after installing a JSON viewer extension for Chrome or Firefox. JSON looks like this:

{
  "posts": [
    {
      "id": 36467,
      "title": "How do I open the safe"
    },
    {
      "id": 36468,
      "title": "How do I reset the combination?"
    },
  ]
}

Zendesk endpoint has the following view:

subdomain.zendesk.com/api/v2/users/me.json

Let’s list the actions that endpoints can perform:

ActionDescription
GETretrieve items
POSTcreate items that didn't exist
PUTupdate existing items
DELETEremove items

You can make only GET requests in a browser. The other actions can be performed with tools like cURL or the API console on the Zendesk Developer Portal.

A few words about cURL. It is a command-line tool that allows trying API commands without a browser. You can use cURL for the four types of calls mentioned above. For more information, look at Installing and Using cURL.

Every API request receives a response that let you know if it worked or not. The responses are called status code and give clues about why the request didn’t work. The basic requests are:

Status codeDescription
200The request was successful
400Request was unsuccessful
409Merge or constraint error, try again
422Unprocessable Entity
429Rate limit has been exceeded
500Warning or temporary state, contact support if it persists

To get more information about Zendesk Support API, go to Zendesk Developers page.

Does This Migration Method Work for You?

In general, this option of data import helps to transfer contacts, companies, agents and agent groups, tickets, and many more other record types (using Support API), and knowledge base (using Help Center API). Although, far not everything so easy-peasy. To get the actual value of this method, you should have an IT team experienced in working with APIs, or you can hire a freelance developer for writing a migration code.

First off, you should add the awaited expenses and the time frame when your IT team will handle the Zendesk data import instead of their primary tasks. Similarly, the hired developer will increase your budget and the project duration will be extended. Also, you should be ready for missing the deadlines.

The API-based migration plan to Zendesk is supposed to be offered by the team that will write the code. But it surely will include such steps as:

  • compare the current help desk platform and Zendesk APIs to define the data accessible for the switch
  • work out field mapping for correct placing in Zendesk
  • develop a migration code and test it

Benefits and Drawbacks of a Third-Party Importing Tool

Now before you jump into any conclusions, look at APIs offered by help desk platforms and other companies from another perspective. They offer an “easy to use API” and promise that you can use it to fetch, import and process the data collected by the help desk. Many of these APIs are far from “easy to use” and even veteran software engineers can hardly use them. This problem appears due to a lack of programming knowledge and/or corporate bureaucracy. That makes these APIs unusable outside the department that wrote them.

To overcome this bottleneck in your Zendesk import, you can find a third-party service that imports data between help desk platforms. The pros and cons are the following:

+the in-house IT team won’t be distracted from their tasks (if you have such a team)
+no need in working with a freelance developer
+organization data is secured (as a rule these services provide data encryption)
+saved time and a clear deadline
-the costs should be discussed
-the current platform may have no or restricted APIs, so some data may require a CSV import

To conclude, the API migration to Zendesk may import an extended list of records, but it needs a thorough preparation to be done right.

The Recap

Most organizations have caught on to the fact that Zendesk migration is more than just moving data from their old platform (or spreadsheets). The planning of the import process takes longer than migration itself. Gone are the days when it took weeks to import tickets, contacts, and rest of the records into a new place. Currently, this can be done within a few hours. Thus, there are conditions (data volume, migration service or API limits, and the like) that might influence the timeframe and budget.

Part 1. How to Get Prepared for Zendesk Import

Part 3. The Destination Reached: What to Do Next?

%s
— %s