Migrate from Octadesk to Freshdesk

Octadesk Tickets map 1:1 to Freshdesk Tickets. The primary challenge is the customField array on Octadesk Tickets — each entry contains a field identifier, label, and value in a nested object structure. We parse the full customField array, match each entry against Octadesk's field definition metadata to retrieve the field data type, and then write to the corresponding Freshdesk custom field using the correct API field name. Date-typed fields stored as strings in Octadesk are normalised to ISO 8601 format before import to satisfy Freshdesk's date validation. Ticket status, priority, owner assignment, and channel metadata map directly to Freshdesk's equivalent fields.

Octadesk Chats are real-time conversation sessions retrieved via GET /chat with a hard cap of 100 items per page. Accounts with thousands of Chats require sequential pagination through all pages, each consuming API budget and susceptible to transient failures — we implement cursor-based resume logic to recover from mid-export failures. Each Chat is split into a Freshdesk Ticket (created with type=chat) and conversation events pulled from the per-chat conversation endpoint to avoid Freshdesk's embedded-conversation view limit of ten records. Agent attribution and timestamps are preserved on each conversation note.

Octadesk Contacts migrate 1:1 to Freshdesk Contacts where the destination schema supports equivalent field types. Contact lifecycle data, custom contact properties, and the primary company association migrate. If a contact's associated company in Octadesk has no match in the Freshdesk destination during the migration window, we create a placeholder Company record first to satisfy Freshdesk's foreign key requirement before inserting the Contact. Duplicate detection uses email as the dedupe key on Freshdesk Contacts.

Octadesk Company records map directly to Freshdesk Companies. The company identifier, name, domain, and any custom company properties migrate. Freshdesk Companies can be associated with multiple Contacts, preserving Octadesk's one-to-many Contact relationship. We create Companies before Contacts to ensure the company_id lookup resolves at Contact insert time. If Octadesk has no active Company records (Contact-only accounts), we skip the Company import phase entirely.

Octadesk Agents (name, email, role, and permission level) map to Freshdesk Agent profiles. We use email as the match key for agent reconciliation: any Octadesk Agent without a corresponding Freshdesk Agent profile goes to a reconciliation queue for the customer's admin to provision before the migration resumes. Agent role in Octadesk maps to Freshdesk group membership and permission level, with the specific permission matrix documented for the admin to configure post-migration. The Octadesk per-agent header (octa-agent-email) is used exclusively for export authentication and has no Freshdesk equivalent.

Octadesk Teams migrate to Freshdesk Groups. Team membership for each Agent is preserved by mapping the Octadesk team_id to a Freshdesk Group and setting the Freshdesk Agent's group membership during migration. If a Team has no corresponding Group in Freshdesk at migration time, we create the Group via the Freshdesk Groups API before agent assignment begins. SLA configurations tied to Octadesk Teams are documented separately as Freshdesk SLA policies require separate setup.

Octadesk Ticket customField arrays (containing field ID, label, type, and value) require field-level configuration in Freshdesk before data import can begin. We export the complete list of Octadesk custom field definitions via the Tickets customFields metadata endpoint, map each to a Freshdesk custom field with matching data type (text, numeric, dropdown, date, boolean), and deploy the field definitions to Freshdesk via the Custom Field API before any ticket records are imported. Field ordering, visibility, and required-flag matching are documented in the pre-migration field map.

Ticket and Chat attachments are referenced by URL in Octadesk. We download each attachment during the export phase, store it in a temporary bucket, and re-upload to Freshdesk via the Ticket Attachments API, mapping each file to the corresponding migrated Ticket or Conversation record. Attachment size limits in Freshdesk (15-20 MB per file depending on plan) are checked against Octadesk's stored file sizes; any files exceeding Freshdesk's limit are flagged for the customer to decide whether to store a link-only reference or host externally. Conversation attachments that exceed limits are noted in the migration report.