Mapping Custom Fields When Migrating Help Desks: A 9‑Step Guide

Moving to a new help desk means more than copying tickets; every custom field that your team relies on, such as priority tags, product categories, SLA tiers, and customer tiers, must survive the switch intact. This tutorial shows you how to inventory those fields, build a reliable mapping, test the migration, and verify the results. Before you start, make sure you have admin access to both the source and destination platforms, an export of the current field definitions (CSV or API), and a sandbox or test environment in the new system.

1. Inventory every custom field in the current help desk

Why it matters: You cannot map what you do not know exists. A complete inventory prevents surprise gaps after go‑live.

• Export the field list from the source help desk (most tools provide a CSV export or an API endpoint).
• Capture for each field: internal name, display label, data type (text, dropdown, date, number, checkbox), whether it is required, default value, and any validation rules.
• Note dependencies such as fields that appear only when another field has a specific value.
• Store the export in a version‑controlled spreadsheet; you will reference it throughout the project.

2. Document field purpose and usage

Why it matters: Knowing why a field exists helps you decide whether to replicate, transform, or retire it.

• Interview a few agents and team leads: which fields drive routing, reporting, or automation?
• Check existing reports, dashboards, and automation rules for field references.
• Tag each field as keep, transform, or deprecate.
• Record any business logic (e.g., “Product = ‘Enterprise’ sets SLA to 4 hours”).

3. Review target help desk field capabilities

Why it matters: The new platform may not support every source field type or may enforce different limits.

• List the field types the destination supports (single‑line text, multi‑select, date‑time, numeric, etc.).
• Note naming conventions, character limits, and whether custom fields can be added to tickets, contacts, or organizations.
• Identify any fields that are built‑in (e.g., “Priority”) so you do not duplicate them.
• If the target system caps the number of custom fields, prioritize the ones marked keep.

4. Build a mapping spreadsheet

Why it matters: A single source‑of‑truth spreadsheet makes the migration repeatable and auditable.

Create columns for:

• Source field name
• Source field type
• Target field name (existing or new)
• Target field type
• Transformation rule (e.g., “map ‘High’ → ‘Urgent’”, “convert epoch ms to ISO‑8601 date”)
• Validation notes (required, default, allowed values)
• Owner (who approves the mapping)

Add a row for every source field tagged keep or transform. For deprecated fields, note the decision and any data you will archive.

5. Create or configure matching fields in the new system

Why it matters: Fields must exist before you can import data; mismatched types cause import errors.

• Using the admin UI or API, add each target field from the mapping sheet.
• Replicate dropdown options exactly (including order) to avoid value mismatches.
• Set required/optional flags and default values per the mapping notes.
• Apply any validation regex or range limits that mirror the source.
• Record the new field’s internal ID; you will need it for the import script.

6. Test migration on a sample set

Why it matters: A small‑scale run reveals formatting issues before they affect the full database.

• Select 50–100 representative tickets covering every field combination.
• Run your import tool (CSV upload, API script, or migration wizard) against the sandbox.
• Verify:
  • All values appear in the correct target fields.
  • Dropdown selections match the intended labels.
  • Date/time formats are preserved.
  • No required fields are left blank.
• Document any discrepancies and adjust the mapping sheet accordingly.

7. Run full migration and validate

Why it matters: Full‑scale validation confirms that the sample success scales.

• Execute the migration on the production dataset (or a staged copy).
• Perform automated checks: count of tickets per field value before vs. after, checksum of text fields, and verification that no tickets lost required fields.
• Run spot checks on a representative sample of tickets; open them in the new UI and compare key fields.
• If you use a migration service, request their validation report.
• Log any tickets that failed to import and plan a manual correction pass.

8. Update automations, macros, and reports

Why it matters: Workflows that reference old field IDs will break silently.

• Search all automation rules, macros, triggers, and saved searches for the source field identifiers.
• Replace each reference with the new field’s internal ID or name.
• Test each automation in the sandbox before enabling it in production.
• Update any external scripts or integrations that read/write these fields (e.g., a CRM sync).

9. Train agents on the new field layout

Why it matters: Even a perfect migration fails if the team cannot find or use the fields.

• Create a one‑page cheat sheet showing the old field label, the new label, and any behavior changes.
• Walk through the most common ticket flows in a short live session.
• Add the cheat sheet to your internal knowledge base.
• Schedule a follow‑up Q&A after the first week of live use.

Common mistakes to avoid

• Skipping the inventory – leads to missing fields discovered only after go‑live.
• Assuming field types match – a source “multi‑select” may become a single‑select in the target, truncating data.
• Ignoring dependent fields – conditional visibility rules often do not migrate automatically.
• Not testing date formats – epoch vs. ISO‑8601 mismatches corrupt timestamps.
• Forgetting to update automation – broken routing or SLA rules surface days later.
• Over‑mapping – creating duplicate fields (e.g., both “Priority” and “Ticket Priority”) confuses agents and reports.

If you want a help desk that makes field mapping simple, try NeuraDesk free.