What order should help desk data be migrated in?

The typical dependency order is: Users first, then Organizations, then Ticket fields/forms, then Tickets, then Comments/Conversations, then Attachments, and finally Satisfaction ratings. Each entity depends on the ones before it existing in the target system.

What are the most common data mapping mistakes in help desk migrations?

The most common mistakes are deferring custom field mapping, forgetting about attachments and how they link to tickets, ignoring data dependencies (migrating tickets before users exist), and not validating data after import.

How do you validate a help desk migration?

Post-migration validation should include comparing record counts between source and target, checking status distributions, spot-checking 10-20 tickets across different statuses and date ranges, verifying user-ticket associations, confirming attachment integrity, and validating date/timezone accuracy.

Your Ultimate Guide to Data Mapping for a Flawless Help Desk Data Migration (with CSV Templates)

Q: What is data mapping in a help desk migration?

Data mapping defines how data from your source help desk corresponds to data in your target system. It involves three distinct operations: schema mapping (matching field names and structures), value mapping (translating allowed values within fields), and data transformation (converting data formats like dates or rich text).

Migrating a help desk is one of those projects that looks simple on paper but falls apart in execution. The most common point of failure isn't the import tool or the API — it's the data mapping. When field mappings are wrong, incomplete, or vaguely defined, you get tickets assigned to the wrong agents, customer histories that vanish, and custom fields full of garbage data.

This guide covers what data mapping actually involves, breaks it into its distinct operations, provides field mapping tables you can use as starting points, and walks through the edge cases that cause real problems in production migrations.

What is Data Mapping in a Help Desk Migration?

Data mapping is the process of defining how data from your source help desk corresponds to data in your target help desk. It involves three distinct operations that are often conflated but need to be handled separately:

Schema mapping: Matching field names and structures between systems. Your source system's requester_email becomes the target's customer.email. This is the structural translation layer.
Value mapping: Translating the allowed values within a field. Your source system's "Pending" status becomes "On-hold" in the target. The field name might be identical (status → status), but the valid values differ.
Data transformation: Converting data formats or restructuring data to fit the target schema. Date formats (MM/DD/YYYY → YYYY-MM-DD), timezone normalization, HTML-to-markdown body conversion, or splitting a single name field into first_name and last_name.

Getting any one of these wrong produces different failure modes. Schema mapping errors cause import failures. Value mapping errors cause silent data corruption — tickets that import successfully but with wrong statuses. Transformation errors cause subtle bugs that surface weeks later.

Why Data Mapping Determines Migration Success

Good data mapping ensures:

Continuity: Agents can pick up conversations with customers right where they left off.
Integrity: Historical data and reports remain accurate and trustworthy.
A smooth launch: You avoid Day 1 chaos where agents scramble to find information while frustrated customers wait.

This isn't just a technical task for the IT department; it's a foundational step in the overall help desk migration process that directly impacts your customer experience.

Pre-Mapping Preparation

Before building your field map, handle these two prerequisites:

1. Audit and Scope Your Data

A migration is the right time to decide what data actually needs to come over. Do you need every spam ticket from five years ago? Probably not. Before you map your data, you must decide which data to migrate. Scoping reduces mapping complexity and results in a cleaner target system.

2. Back Up Everything

Before you do anything else, back up your data. Having your own backup is non-negotiable. It's your rollback path if the migration produces unexpected results.

Migration Dependency Order

Data mapping doesn't happen in a vacuum — the order you migrate entities matters because of referential dependencies. You can't import a ticket that references a user who doesn't exist yet in the target system.

The typical migration sequence:

Users — agents, admins, and end-users must exist before anything references them
Organizations / Companies — user-to-organization relationships depend on both existing
Ticket fields and forms — custom fields and dropdown values must be created before tickets reference them
Tickets — the core records, referencing users, orgs, and field definitions
Comments / Conversations — threaded under tickets, referencing author users
Attachments — linked to specific tickets or comments
Satisfaction ratings — reference both tickets and end-users

Skipping this order or running imports in parallel without accounting for dependencies is a common source of broken references and orphaned records.

Field Mapping Tables

Below are starting-point mapping tables. Real migrations will have more fields — a typical help desk has 20-40 standard fields plus any custom fields your team has created.

Ticket Data Mapping

Source Field (Old System)	Target Field (New System)	Mapping Type	Notes
ticket_id	external_id	Schema	Preserve the old ID for cross-referencing and troubleshooting.
subject	subject	Schema	Usually a direct 1:1 map.
description	description	Transformation	Check whether source is HTML and target expects markdown, or vice versa.
status	status	Value	"Pending" → "On-hold", "Open" → "New", etc. List all values from both systems and match them explicitly.
priority	priority	Value	"Urgent" may not exist in the target — map it to "High" or create the value.
type	type	Value	"Question", "Incident", "Problem", "Task" — values often differ between platforms.
requester_email	customer.email	Schema	Field name change only.
assignee_id	assignee_id	Schema	Requires users to be migrated first. The ID in the target system will differ from the source.
group_name	team_name	Schema	Support group/team naming varies by platform.
tags	labels	Schema	Some systems use tags, others use labels. Check character and length limits.
created_at	created_at	Transformation	Verify format (ISO 8601 preferred). Handle timezone conversion — source may store UTC, target may expect local time, or vice versa.
updated_at	updated_at	Transformation	Same format and timezone considerations as created_at.
due_date	due_date	Transformation	Date-only vs. datetime handling.
custom_field_12	custom_field_product_name	Schema	Rename cryptic field IDs to human-readable names in the target.
custom_field_region (dropdown)	custom_field_region (dropdown)	Value	Dropdown values must exist in the target before import. Export the full value list from the source.
custom_field_notes (multi-line text)	custom_field_notes (multi-line text)	Schema	Check character limits — some systems cap text fields at different lengths.

User & Organization Data Mapping

For a deeper dive, see our guide on how to migrate users and organizations.

Source Field (Old System)	Target Field (New System)	Mapping Type	Notes
user_id	external_id	Schema	Preserve for cross-referencing.
email	email	Schema	Primary key for matching users across systems.
name	full_name	Schema	Some targets split into first_name / last_name — requires transformation.
role	role	Value	"Admin" in one system may have different permissions than "Administrator" in another. Map carefully and verify permission levels.
organization_name	company_name	Schema	Field name change.
phone	phone	Transformation	Normalize phone number formats if target validates formatting.
created_at	created_at	Transformation	Same date format considerations as tickets.
suspended	active	Transformation	Boolean inversion — suspended=true may need to map to active=false.

CSV Examples

Here's how schema mapping plus value mapping looks in practice.

Source CSV:

ticket_id,subject,requester_email,status,priority,created_at
101,"Password Reset",customer1@email.com,"Open","Normal","03/15/2024 09:30:00"
102,"Billing Inquiry",customer2@email.com,"Closed","High","03/16/2024 14:22:00"
103,"Bug report",customer3@email.com,"Pending","Urgent","03/17/2024 11:05:00"

Target CSV after applying your mapping:

external_id,subject,requester.email,status,priority,created_at
101,"Password Reset",customer1@email.com,"New","Normal","2024-03-15T09:30:00Z"
102,"Billing Inquiry",customer2@email.com,"Solved","High","2024-03-16T14:22:00Z"
103,"Bug report",customer3@email.com,"On-hold","High","2024-03-17T11:05:00Z"

Three mapping operations happened here:

Schema mapping: ticket_id → external_id, requester_email → requester.email
Value mapping: Open → New, Closed → Solved, Pending → On-hold, Urgent → High (value doesn't exist in target)
Data transformation: Date format converted from MM/DD/YYYY HH:MM:SS to ISO 8601 (YYYY-MM-DDTHH:MM:SSZ)

Edge Cases That Cause Real Problems

The standard fields are straightforward. The edge cases are where migrations break.

Custom Field Type Mismatches

A dropdown field in your source might need to become a text field in the target if the target system doesn't support the same dropdown values natively. Multi-select fields are particularly tricky — some systems store them as comma-separated strings, others as arrays. Check how each custom field type is represented in both systems before mapping.

Rich Text and Inline Images

Ticket descriptions and comments often contain HTML formatting, inline images, and embedded content. If your source stores rich text as HTML and your target expects markdown (or vice versa), you need a transformation step. Inline images that are referenced by internal URLs in the source system will break if those URLs aren't accessible from the target.

Attachments

Attachments are referenced differently across systems — some store them as URLs pointing to cloud storage, others as file IDs referencing internal blob storage, and some embed them directly in the ticket body. Your mapping needs to account for how attachments are referenced in the source and how they need to be provided to the target's import mechanism.

Merged and Deleted Tickets

Some systems maintain merged ticket records with pointers to the surviving ticket. Others delete the merged ticket entirely. Deleted or suspended tickets may or may not be included in your export. Decide upfront whether these edge cases need to be migrated and how they should be represented in the target.

Conversation Threading

Some help desks use flat comment lists on tickets. Others support nested conversation threads, side conversations, or internal-vs-external note distinctions. If your source supports side conversations but your target doesn't, you need a mapping decision: discard them, append them as internal notes, or merge them into the main thread.

Common Data Mapping Mistakes

These are the mistakes we see most often in migration projects:

Deferring custom field mapping: Custom fields are complex and unique to your setup. Map them with the same rigor as standard fields. Leaving them for "later" means they never get mapped correctly.
Forgetting about attachments: If you don't know where your attachments are stored and how they link to tickets, you'll lose critical context.
Ignoring data dependencies: Migrating tickets before the users they reference exist in the target system creates broken references. Follow the dependency order above.
Not validating after import: A successful import doesn't mean a correct import. You need to verify the data landed correctly.

Data mapping is a crucial part of the planning phase. Give it the time it requires.

Post-Migration Validation Checklist

After your migration completes, verify the results before declaring success:

Record counts: Compare total tickets, users, and organizations between source and target. The numbers should match your scoped migration set.
Status distribution: Pull a count of tickets by status in both systems. The distribution after applying your value mapping should be consistent.
Spot-check samples: Pick 10-20 tickets across different statuses, priorities, and date ranges. Verify that all fields — including custom fields, comments, and attachments — migrated correctly.
User-ticket associations: Verify that ticket requesters and assignees point to the correct users in the target system.
Attachment integrity: Open several attachments in the target system to confirm they're accessible and not corrupted.
Date verification: Check that timestamps preserved the correct dates and times, especially if timezone conversion was involved.
Custom field values: Verify that dropdown values, multi-select fields, and other constrained fields contain valid values in the target system.

If any of these checks fail, you need to identify whether the issue is in your mapping, your transformation logic, or the import process — and fix it before going live.

When to Use CSV, APIs, or a Migration Service

Not every migration method suits every situation:

CSV export/import works for small datasets (under a few thousand records) with simple field structures. It's manual, error-prone at scale, and typically doesn't handle attachments or relationships well.
API-based migration gives you programmatic control over the import process, handles relationships and attachments properly, and scales better. It requires development effort and you'll need to handle rate limits, pagination, and error recovery.
Engineer-led migration services make sense when you have complex data, large volumes, tight timelines, or limited internal engineering bandwidth. The tradeoff is cost for speed and reliability.

For anything beyond a small, simple dataset, CSV-based migration becomes increasingly fragile. One malformed row in a 50,000-line file can break the entire import.