Part 1. How to Get Prepared for Zendesk® Import
Part 2. Whats, Whys, and Hows of Importing Data to Zendesk®
- Zendesk® Import: Diving into the Ways and Details
- How to Make a Valid CSV File
- Zendesk® Data Import Limitation
- Setting up a CSV File for Bulk Import
- A List of Fields for Organizations Import
- How to Import the CSV Organization File
- A List of Fields for Users Import
- The Peculiarities of Assigning Custom Agents Roles
- How to Import the CSV User File
- Google Docs Importer for the Knowledge Base
- CSV Import Weak Spots
- Master the Art of Database Migration
- API Data Migration? It's Easy if You Do It Smart
Part 3. The Destination Reached: What to Do Next?
Whats, Whys, and Hows of Importing Data to Zendesk®
Zendesk® Import: Diving into the Ways and Details
- the technical limitations during export or import process
- the import tool or migration service doesn’t allow to upload large CSV files
- dump SQL files need rekeying to response to the requirements of the destination software
- API limits during the data migration and the like.
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:
Contact | Title | Tag | |
John Doe | Senior Manager | johndoe@email.com | Spoke Tuesday, he's interested |
Harry Winston | Head of Sales | hwinston@email.com | said to call again next week |
Cheryl Cole | Development Director | ccole@email.com | 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,
johndoe@email.com,”Spoke Tuesday, he's interested”
Harry Winston,Head of Sales,hwinston@email.com,”said to call again next week”
Cheryl Cole,Development Director,ccole@email.com,”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
- Save your file in proper formatting using UTF-8 character encoding.
- Double check the first row of the CSV file. It should be a header row.
- The header row must include any required fields or any other fields you want to import. (Ensure that all these fields are supported in bulk import.)
- Enter the included fields in the order they listed in the header row.
- List in the header row only fields for which you are going to import data.
- The date for Zendesk® import should be formatted as YY/MM/DD or YYYY-MM-DD.
- To add line breaks to notes or multiple custom fields, use the combinations: ALT + ENTER on Windows or CTRL + OPTION + RETURN on a Mac.
A List of Fields for Organizations Import
name | This field is required and represents the organization name. |
---|---|
external_id | If you have a unique identifying ID inside your documentation that differs from the organization’s name, you can import it via this field. |
notes | These are some notes about the organization. Only agents can see them, the end-users (aka customers) can’t see them. |
details | The field contains the detail information about the organization. Only agents can see them, the end-users can’t see them. |
default | Here you should add one or more email domains separated with spaces. This field is used for mapping end-users to an organization. |
shared | True or false. It sets the organization as a shared one. |
shared_comments | True 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. |
group | Here 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. |
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. 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. |
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:
- Click the Admin gear icon in the sidebar, and then clicking on People.
- Choose Bulk Organization Import.
- Select the import type you need:
- Create new organizations
- Update existing organizations
- Click Choose File or on the link Let me paste in data instead.
- 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.
name | Here you add a full user’s name. |
---|---|
Add 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_id | Here 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. |
details | This field allows adding extended information about the user. Only agents can see them, the end-users can’t see them. |
notes | These are some notes about this user. Only agents can see them, the end-userscan’t see them. |
phone | The 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_number | True 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. |
role | This 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. |
restriction | This 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:
|
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: |
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. |
The Peculiarities of Assigning Custom Agents Roles
- Legacy Agent is a transitory role for agents that haven’t been assign to other roles yet.
- Light Agents are available as a Professional or Enterprise Add-on. These agents can be CC'd on tickets, can view tickets, and add private comments to them within their groups. They cannot be assigned to or edit tickets. There are no limits of adding light agents at no charge.
- Staff deals with ticket solving. They can edit tickets, view reports, add and edit personal views and macros.
- Team Leader has more access rights than staff agents. They can read and edit all tickets, moderate forums, and create and edit end-users, groups, and organizations.
- Advisor manages the workflow and configures your Zendesk®. This agent doesn’t solve tickets.
- Administrators have control over Zendesk® except for changing billing information or payment plans.
How to Import the CSV User File
The CSV user importing needs five steps to complete:
- Click the Admin gear icon in the sidebar, and then clicking on People.
- Choose Bulk User Import.
- Select the import type you need:
- Create new users
- Update existing users
- Click Choose File or on the link Let me paste in data instead.
- 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
- In your Zendesk® Guide, go to Arrange content > Import articles.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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:- 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.
- You can not import contact information of the end-user from Facebook or X accounts. That can be done only via the Zendesk® REST API.
- 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
What Is Behind a Database Migration?
How to Export Data from a MySQL Database
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.
- 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
- Step 1. Create an export directory on the source server.
mkdir /path/path
- Step 2. Grant the Oracle user.
chown oracle /path/path
- Step 3. Create a directory in the database.
CREATE DIRECTORY Your_Dir_Name as '/path/path'
- Step 4. Add your Oracle user to EXP_FULL_DATABASE role.
Grant EXP_FULL_DATABASE to your_user
- Step 5. Grant your created directory in the database to the role.
GRANT READ, WRITE ON DIRECTORY Your_Dir_Name TO EXP_FULL_DATABASE
- Step 6. Execute expdp command with the Oracle user.
expdp your_db_user/password schemas=Your_Schema_Name tables=table_name directory=Your_Dir_Name version=your_version_for_target_db dumpfile=data.dmp logfile=data.log
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
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:- Go to the Admin gear icon, and then clicking on People.
- Select the type of the CSV file you are going to import:
- Select the import type you need:
- Bulk Organization Import.
- Bulk User Import.
- Select the one you need:
- the import type Create new organizations
- the import type Create new users
- Click Choose File or on the link Let me paste in data instead.
- Click Import.
Getting the Knowledge Base to Zendesk®
There are several steps to take:
- Go to Arrange content > Import articles.
- Click Connect to sign in your Google account and grant the access for Zendesk® Guide. Then click Next.
- In Select documents, click Open file picker and choose files to import. Then click Select.
- In Place documents, click Select section to define a section for this article in your Help Center. Click Next.
- 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.
- 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
What is an API?
- You make a “request” to a Zendesk® web server.
- Then it accesses to a Zendesk® database (with your data).
- After that, the web server returns it to you in a “response.”
Why Businesses Use the API?
- bulk records update
- create tickets
- migrate ticket data from old help desk (or database)
- bulk user editing
- record search
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:
Action | Description |
---|---|
GET | retrieve items |
POST | create items that didn't exist |
PUT | update existing items |
DELETE | remove 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 code | Description |
---|---|
200 | The request was successful |
400 | Request was unsuccessful |
409 | Merge or constraint error, try again |
422 | Unprocessable Entity |
429 | Rate limit has been exceeded |
500 | Warning 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
+ | 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 |