Importing tickets, users, groups and organizations

In this post we describe the process for importing users, groups, organizations and tickets into Zendesk using our Import app for Zendesk Support.

Zendesk is a powerful and extremely customizable customer service tool, but a common challenge for companies moving from another application is migrating large amounts of ticket and user data. We’ve dealt with this enough times now to warrant the creation of a custom app that you can use to streamline the process.

Our Import app for Zendesk Support, available through the Zendesk App Marketplace, has been built to make importing users, groups, organizations and tickets as easy as possible.

Overview

The process for importing objects into Zendesk Support can be summarized as follows:

1. Create

   The first step is to create rows representing your objects within the app. There are two ways to do this:

   1. One at a time by clicking on the Add Row button and entering the data manually.

      

   2. In bulk by adding rows from a CSV file.

      

   The app provides an editable table in which you can:

   • Edit individual fields directly within the table
   • Receive immediate visual feedback if a field value is invalid
   • Select and delete rows in bulk

   

   When creating rows or editing individual fields, you will be visually alerted to potential validation issues. The field type of each field matches that of the corresponding field in Zendesk, providing additional safeguards when editing data manually. For example, date fields present a date selector and number fields only allow numbers to be entered.

   Table columns can be added, removed and reordered by clicking on the Manage Columns button within the table’s dropdown menu.

   

   All user, organization and ticket custom field types are supported in addition to system fields.

   The table (and each subsequent import) supports up to:

   • 50,000 users
   • 100 groups
   • 50,000 organizations
   • 50,000 tickets

2. Review

   Once you have populated the table with your data, the next step is to review it before starting the actual import. To make this easy, the app allows you to:

   • Sort rows in the table by any column
   • Filter rows in the table by:
     • Column, using one or more keywords
     • Whether or not the row contains one or more validation errors

   

   Only the columns present within the table will be imported.

   If you have more than 50 rows to import, pagination links will allow you to view each page.

3. Import

   If you’re satisfied that the data is complete and accurate, you can import all rows by clicking the Import button.

   A progress indicator will guide you through the import itself. When the import has finished you can download a completion report containing all data, the newly created record IDs and status information (created, updated or failed with details where necessary).

Creating the CSV file

In order to ensure that your CSV file can be imported properly:

• The file must be properly formatted CSV and saved using UTF-8 character encoding.
• The first row of the CSV file must contain the headers that you want to import.
• The headers should match those described in the sections below (invalid headers will be removed by the app).
• If you are not importing data for a field, do not list it in the header row.
• Add line breaks to notes or multiline custom fields by pressing ALT + ENTER on Windows or CTRL + OPTION + RETURN on a Mac.

The following user field types are supported:

• Drop-down list, where each option value is the tag defined in the field settings
• Text
• Multi-line text
• Numeric
• Decimal
• Checkbox, where values are TRUE or FALSE
• Regular expression
• Date, in the format YYYY-MM-DD

Importing users

The following table outlines the column headers that can be specified when creating a CSV file containing your user data:

Name	Type	Description
id	integer	The ID of the user (used only when updating a user)
external_id	text	The external ID of the user
name	text	The user’s full name (required)
email	text	The user’s primary (upon creation) or secondary (open update) email address
phone	text	The user’s primary phone number
role	text	The user’s role (end-user, agent or admin)
custom_role_id	integer	The ID of a custom role if the user is an agent on the Enterprise plan
organization_id	integer	The ID of the user’s organization
default_group_id	integer	The ID of the user’s default group
alias	text	An alias displayed to end users
notes	text	Notes to store about the user
details	text	Details to store about the user (e.g., an address)
tags	text	The tag(s) to apply to the ticket, provided in a list separated by |
user_fields.{key}	*	The value for a custom field where the type corresponds to the type of field created

When adding custom user fields, the column header should be in the format user_field.{key} where {key} is the field key obtained when creating the field in Zendesk Support.

For detailed information about the user properties that are supported, visit the Users page of the Zendesk REST API documentation.

Specifying an id will update the associated user, whereas omitting an id will create a new one. Specifying an email or external_id will either create a new user or update an existing one, depending on whether a user already exists with those properties.

If you do not want emails to be sent to newly created users, you should disable the email verification message that’s sent out by default.

Importing groups

The following table outlines the column headers that can be specified when creating a CSV file containing your group data:

Name	Type	Description
id	integer	The ID of the group (used only when updating a group)
name	text	The name of the group (required)
description	text	The description of the group
default	boolean	True if the group is the default group

Specifying an id will update the associated group, whereas omitting an id will create a new one.

For detailed information about the group properties that are supported, visit the Groups page of the Zendesk REST API documentation.

Importing organizations

The following table outlines the column headers that can be specified when creating a CSV file containing your organization data:

Name	Type	Description
id	integer	The ID of the organization (used only when updating a organization)
external_id	text	The external ID of the organization
name	text	The name of the organization (required)
details	text	Details to store about the organization
notes	text	Notes to store about the organization
group_id	text	The ID of the group to which tickets from users in this organization should be assigned
shared_tickets	boolean	True if users in the organization can view organization tickets
shared_comments	boolean	True if users in the organization can view organization comments
tags	text	The tag(s) to apply to the ticket, provided in a list separated by |
domain_names	text	The email domain(s) that result in a user being automatically added to the organization, provided in a list separated by |
organization_fields.{key}	*	The value for a custom field where the key is that of your custom organization field

Specifying an id will update the associated organization, whereas omitting an id will create a new one. Specifying an external_id will either create a new organization or update an existing one, depending on whether an organization already exists with that external_id.

For detailed information about the group properties that are supported, visit the Organizations page of the Zendesk REST API documentation.

Importing tickets

The following table outlines the column headers that can be specified when creating a CSV file containing your ticket data:

Name	Type	Description
id	integer	The ID of the ticket (used only when updating a ticket)
external_id	text	The external ID of the ticket
subject	text	The subject line of the ticket
description	text	The description of the ticket (required)
internal	boolean	TRUE if the initial ticket comment should be an Internal Note, FALSE otherwise
type	text	The ticket type (problem, incident, question or task)
priority	text	The ticket priority (low, normal, high or urgent)
status	text	The ticket status (new, open, pending, hold, solved or closed)
requester_id	integer	The ID of the ticket requester (if blank, the requester will be the user performing the import)
requester_email	text	The email address of the ticket requester (if blank and no requester_id is specified, the requester will be the user performing the import)
group_id	integer	The ID of the group to which the ticket is assigned
assignee_id	integer	The ID of the individual ticket assignee
submitter_id	integer	The ID of the ticket submitter
organization_id	integer	The ID of the organization associated with the ticket
brand_id	integer	The ID of the brand associated with the ticket
due_at	date	The due date of the ticket in the format YYYY-MM-DD
tags	text	The tag(s) to apply to the ticket, provided in a list separated by |
custom_fields.{id}	*	The value for a custom field where the ID is that of your custom ticket field

Specifying an id will update the associated organization, whereas omitting an id will create a new one. Specifying an external_id will either create a new organization or update an existing one, depending on whether an organization already exists with that external_id.

For detailed information about the group properties that are supported, visit the Tickets page of the Zendesk REST API documentation.

If you are importing tickets with the On Hold status, make sure that you have that option enabled in the Status field with Zendesk Support before staring the import.

Summary

As you may have guessed, this app can be used for more than just imports. Examples of other use-cases made easy by the app include:

• Creating regular proactive ticket campaigns
• Updating agent roles (or downgrading agents) in bulk due to seasonal staffing changes
• Flagging tickets for inclusion in a business rule or report
• And the list goes on.

If you’ve been struggling with one-off or ongoing imports, you can now save time and money and take control over the process.

Updated on 1 February 2022