Migrate from Hesk to Zoho Desk

Hesk Ticket records (id, subject, message, status, priority, owner, category, custom field values) map to Zoho Desk Ticket records. We read the hesk_tickets table via direct MySQL query, transform each row to a Zoho Desk Ticket API payload (POST /api/tickets), and post via batched requests with rate-limit handling. The ticket history table (hesk_log) threads as separate Comment records in Zoho Desk under the same ticket ID. Priority and status values from Hesk map to Zoho Desk's enumerated picklist values (Open, Pending, On-Hold, Resolved, Closed and Low, Medium, High, Urgent).

Hesk end-user accounts (name, email, IP address, creation date) map to Zoho Desk Contacts. The email field is the dedupe key during import. IP addresses from Hesk store as a custom field on the Contact record for GDPR audit purposes if required. Hesk allows emailless users for phone-only contacts — these create Contacts without an email address in Zoho Desk, which is valid for the Contact object but requires downstream handling if email routing is needed.

Hesk Staff records (name, email, role: administrator/manager/agent, password hash, permission flags) require mapping to Zoho Desk Agents, which are Zoho user accounts scoped to specific Departments. We resolve Hesk staff by email match against the destination Zoho Desk agent list. If a matching Zoho Agent does not exist, we hold the record and flag it for provisioning before production migration. Role hierarchy (admin vs agent) maps to Zoho Desk permission profiles and department membership rather than a direct role translation.

Hesk ticket categories (hesk_categories: id, name, description) map to Zoho Desk Departments because Zoho Desk routes tickets by Department rather than flat category IDs. We create a Zoho Desk Department for each Hesk category during the schema-setup phase, and re-map the foreign key reference on each ticket record during import so that tickets land in the correct department. The customer decides whether to merge multiple Hesk categories into a single Zoho Desk department or preserve a 1:1 mapping.

Hesk KB articles (title, content in HTML, category association, publication status) map to Zoho Desk KB articles via POST /api/articles. The Hesk category-to-department mapping applies here too. Publication status (published/draft) in Hesk maps to Zoho Desk's Published/Internal status. We preserve article content including embedded images as ContentDocument or image URL references where possible, noting that Hesk KB attachments may require path re-mapping after migration (see Gotcha on attachment re-mapping).

Hesk canned responses (title, HTML content) map to Zoho Desk Macros, which are pre-built action sequences that agents can trigger from a ticket. We import canned responses as Macro templates with the message body pre-populated. If the canned response references ticket fields via Hesk's variable syntax, we document those placeholders for the customer to re-configure in Zoho Desk's Macro editor using Zoho Desk's own variable syntax (${ticket.id}, ${contact.lastName}, etc.).

Hesk custom field definitions (field label, type: text/date/dropdown/checkbox/radio) and their per-ticket values migrate to Zoho Desk custom fields scoped to the Ticket module. We read hesk_custom_fields for definitions and hesk_ticket_fields for values, then create equivalent Zoho Desk custom fields during schema setup using the Fields API before importing data. The field type must match: Hesk dropdown maps to Zoho Desk Picklist, checkbox maps to Multi-Select Picklist, date maps to Date field. We flag any Hesk custom field that exceeds Zoho Desk's field-name character limit (50 characters) for manual renaming before migration.

Hesk ticket and KB article attachments are files stored on disk with paths in MySQL (hesk_attachments table: file_key, article_id, ticket_id). We export the entire attachments directory alongside the database dump, re-upload each file via Zoho Desk's Attachments API (POST /api/tickets/{ticketId}/attachments or /api/articles/{articleId}/attachments), and update the file path reference in the imported records. If the destination Zoho Desk portal uses a different domain than the source Hesk instance, all embedded image URLs inside KB article HTML content are re-written to reflect the new portal URL.

Hesk's hesk_log table records ticket events (opened, replied, status changed, reassigned) as structured rows with timestamps and actor. We export the full history and import each log entry as a Zoho Desk Comment record on the parent Ticket, preserving the original timestamp and attributing the comment to the mapped Agent if the actor is a staff member, or to the Contact if the actor is the customer. Status-change log entries without a message body are imported as private internal notes in Zoho Desk to preserve the audit trail without creating spurious public comments.

Hesk stores configuration (email routing, ticket statuses, priority labels, branding) in hesk_settings as serialized rows. We export the full settings bundle as a written configuration inventory document, mapping each Hesk setting to its equivalent Zoho Desk setup location (Admin > Channels > Email > Email Configuration, Admin > Ticket Fields, Admin > Departments). We do not apply settings programmatically; the document guides the customer's Zoho Desk administrator through manual configuration after migration.

Hesk stores the creating IP address on every user record. For GDPR-aware migrations, we offer an optional anonymisation pass that strips IP addresses from imported Contacts before they land in Zoho Desk. We apply this as a pre-transform step. If full anonymisation is required (name, email, and message content stripped), ticket subjects and thread structure remain but message bodies are replaced with [Anonymised] — we confirm the customer's GDPR scope before applying this option because it permanently reduces migration fidelity.

Mods-for-HESK community add-ons extend Hesk's database schema with non-standard fields and tables. We discover any non-standard tables during the schema scan, document their structure, and flag them for the customer to review. These tables do not have a standard Zoho Desk equivalent and must be handled as custom objects or external references post-migration. We do not include them in the standard migration scope without explicit scope extension.