Zendesk Migration Checklist

Migrating your support operations to Zendesk can streamline workflows and improve customer experiences, but it requires careful planning and execution. With years of experience in Zendesk migrations, we’ve found that successful transitions come from thorough pre-migration setup, understanding Zendesk's API capabilities, and managing the manual configurations within the platform.

This checklist will guide you through the entire migration process, from planning and setup to execution and post-migration checks.

Scope the Migration

Start by defining the scope of your migration. This phase will determine what needs to be brought over and what can be left behind.

• Historical Data Range: How far back should you migrate? Typically, migrating 1-3 years of ticket history is sufficient.
• Identify Users and Agents: Include all active agents and legacy agents whose names appear on historic tickets to ensure proper ownership.
• Select Objects for Migration: Decide which data needs to be migrated, such as:
• • Tickets, conversations, messages
  • Customers, companies, and profiles
  • Tags, custom fields, and ticket metadata
  • Attachments, internal notes, and other files
• Determine What to Skip: Identify irrelevant data such as spam, test tickets, and outdated records.
• Mapping Legacy Data: Document how old statuses, priorities, custom fields, and tags map to Zendesk’s ticket and user system.

What Can Be Migrated Via API

Zendesk’s robust API allows for seamless data transfer. The following critical data types can be migrated programmatically:

• Users & Organizations: Migrate customer profiles, their contact details, legacy IDs, and associated organizations.
• Tickets & Conversations: Rebuild tickets as conversations, preserving the full message history, internal comments, timestamps, and attachments.
• Attachments: Import images, PDFs, and documents and attach them to the correct ticket, retaining filenames and formats.
• Tags & Custom Fields: Recreate legacy tags and custom fields, ensuring proper alignment with Zendesk's ticketing model.
• Ticket Metadata: Include important ticket metadata like statuses (open, solved, pending) and priority levels.

What Needs to Be Configured in the Zendesk UI

While the API handles much of the heavy lifting, there are several key elements that need to be manually configured within Zendesk’s user interface:

• Mailboxes & Email Channels: Set up your email channels, including support and sales inboxes, and configure routing rules.
• Users & Teams: Invite agents, assign roles (Admin, Agent, Light Agent), and configure team structures manually.
• Workflows & Automations: Create automation rules such as auto-assign based on tags, keywords, or specific triggers. These need to be rebuilt in the UI.
• Macros & Saved Replies: Pre-configure commonly used macros and canned responses to speed up agent workflows post-migration.
• Help Center Content: While articles can be imported via the API, you will need to manually set up help center sections, SEO settings, and article organization.

Pre-Migration Setup in Zendesk

Before migrating data, it’s crucial to set up the target environment to ensure smooth data transfer.

1. Create Your Zendesk Account & Set Up Core Settings:
2. • Choose the right Zendesk plan that suits your needs (e.g., support, tickets, reporting).
   • Configure organization settings (company name, timezone, default language).
   • Set up roles and permissions for key stakeholders (admins, lead agents).
2. Configure Teams, Roles, and Permissions:
3. • Create all active agents and any legacy agents (for ticket ownership mapping).
   • Assign appropriate roles (Admin, Agent, Light Agent).
   • Set up team structures, ensuring the right permissions for each role.
3. Map Legacy Data to Zendesk Fields:
4. • Pre-create custom fields, ticket statuses, and priority levels.
   • Define ticket categories and tags.
   • Set up triggers and automation rules for post-migration workflows.
4. Test with Small Pilot Import:
5. • Import a small set of sample data (e.g., 100 contacts and 50 tickets) to verify the accuracy of mappings.
   • Check ticket threading, attachment visibility, and data integrity.

Migration Execution

Now it’s time to run the full migration. Here’s how to execute it smoothly:

1. Import Users & Organizations First: Begin by importing your user base, ensuring each contact is properly linked to their respective organization.
2. Migrate Tickets & Conversations: Import tickets as conversations, preserving their threads, attachments, status, timestamps, and participant assignments. Attach tickets to the correct users and organizations.
3. Run Delta Import: After the initial import, capture any new data (e.g., tickets created after the initial export) through a delta import.
4. Switch Email Routing: Change the email forwarding and routing rules so that new tickets are routed into Zendesk, not the old system.
5. Monitor API Calls and Errors: Track API usage and fix any failed imports or errors as they occur.

Post-Migration Checklist

Once the data is loaded and agents are actively using Zendesk, perform these checks to ensure everything is functioning correctly.

• Data Verification:
• • Spot-check records for accuracy. Verify ticket ownership, timestamps, and attachments.
  • Ensure customers and organizations are linked correctly.
• Channel & Workflow Testing:
• • Test each channel (email, chat, social) to ensure that new tickets are routed correctly.
  • Verify that workflows, triggers, and SLAs function as expected.
• Agent Readiness:
• • Ensure agents have the correct permissions and roles.
  • Train agents on Zendesk’s workflows, including internal comments, macros, and collaboration features.
• Final Cleanup & Cutover:
• • Once everything looks good, make the old system read-only or decommission it entirely.
  • Re-enable any customer-facing notifications and workflows that were paused during migration.

Common Mistakes and Pro Tips

• Not Mapping Legacy Agent IDs: Ensure agents are pre-configured in Zendesk before importing data to avoid orphaned tickets.
• Skipping Custom Field Creation: Custom fields must be created before the import; otherwise, data may be dropped.
• Ignoring Attachment Size Limits: Validate attachment size and format before migration to avoid issues during the import.
• Overloading Automation Rules: Avoid overly complex workflows early on. Start with simple automation and build complexity later.