Tags and macros never map one to one. Write the mapping document anyway.

Every migration splits into two kinds of work, and only one of them is a data transfer. Historical tickets, contacts and attachments move where the API exposes them. Everything that describes behaviour gets rebuilt.

Why one to one is a fantasy

Tag lists grow by accident. Macros multiply because cloning is faster than reading. Automation encodes staffing decisions from three reorganisations ago. None of it has a clean equivalent in the destination, because the destination models the problem differently.

Trying for a literal copy means importing the accumulated mess and paying to maintain it somewhere new. A migration is the one moment you get to delete things without a political fight, because everyone already expects change.

What the mapping document contains

• Every tag, with a decision: keep, merge, rename or retire, and who approved it.
• Every macro your team used in the last quarter. The rest are candidates for deletion, not migration.
• Automation described by intent rather than by rule, so you rebuild the outcome instead of the implementation.
• Reporting definitions, including which fields must be required for the report to mean anything.
• What is explicitly not moving, written down and signed off before cutover.

The reconciliation pass

After cutover, compare counts: tickets by period, attachments, contacts, and a sample of records opened by hand. A success message from an import tool is not evidence. A matching count against the source is.

This is also where the approved mapping earns its keep. When somebody asks why an old tag is gone, the answer is a document with their colleague's approval on it rather than a memory of a call.

One special case

Zendesk legacy custom objects have no automated migration path, and they were removed on July 27, 2026. A one-time six-month extension exists for accounts that requested it, so some instances still have them into early 2027. If your project touches those, treat it as its own workstream with its own sequence.

Verified against

• Zendesk developer docs, migrating legacy custom objects.
• Zendesk announcement, removal of legacy custom objects and the extension request form.
• Vendor API documentation on exportable ticket and attachment data.

Checked on August 6, 2026.