Migrate from HelpDeskZ to HubSpot Service Hub

HelpDeskZ tickets map directly to HubSpot Ticket objects. We extract the ticket subject, body, status (integer), priority (integer), created date, and updated date from the tickets table. The conversation feed in HubSpot is populated from the replies table, inserted in chronological order so the thread reads correctly. Custom fields stored in the serialized PHP column are decoded, extracted as key-value pairs, and written to HubSpot custom ticket properties that we pre-create during schema setup.

Each HelpDeskZ replies table row becomes a HubSpot Ticket comment. We map the reply body, author type (agent vs client), and timestamp. The author email resolves to a HubSpot Contact or User by email lookup. Private agent notes in HelpDeskZ (distinguished by a dedicated column or is_agent flag) map to HubSpot's internal notes on the Ticket rather than public comments. Original Message-ID and In-Reply-To headers are not transferred; HubSpot assigns its own thread identifiers at insert time.

HelpDeskZ users with role Admin or Agent map to HubSpot Users. We extract name, email, role, and created date from the users table. The user's hashed password is not migrated — agents must set a HubSpot password at onboarding. Agents who previously had admin privileges in HelpDeskZ should be granted Super Admin or standard user access in HubSpot based on the customer's org design.

HelpDeskZ users with role Client map to HubSpot Contacts. We extract name, email, phone, and created date. If a Contact with the same email already exists in HubSpot (from sales or marketing records), we match on email and update rather than create a duplicate. The original HelpDeskZ client ID is preserved in a custom field hd_client_id__c for audit and cross-reference.

HelpDeskZ departments are a flat id-name lookup table. We map each department to a HubSpot Team. Ticket assignments in HelpDeskZ that reference a department ID are translated to HubSpot team membership at migration time. If the customer has hierarchical departments, we flatten them to HubSpot Teams since HubSpot does not support nested team hierarchies natively.

HelpDeskZ stores file attachments on disk in the uploads/ directory, with only the filename stored in the tickets and replies tables. We read each filename, locate the corresponding file on the source filesystem, upload it to HubSpot's file manager API, and associate it with the target Ticket record. Missing files are logged as warnings and skipped to allow migration to proceed. Files exceeding HubSpot's attachment size limits are flagged for the customer to handle manually or host externally.

HelpDeskZ stores ticket status as integer codes (typically: 1=Open, 2=Pending, 3=Resolved, 4=Closed). We map these integers to HubSpot ticket pipeline status values during extraction. Customers who have added custom status values or renamed statuses via database edits must provide the full status code table during scoping so we can build the correct mapping before migration begins.

HelpDeskZ stores priority as an integer (1=Low, 2=Normal, 3=High, 4=Urgent). We map these to HubSpot ticket priority values (LOW, MEDIUM, HIGH, URGENT). If the customer has non-standard priority mappings, we document the custom mapping during scoping.

HelpDeskZ custom fields are stored as a PHP serialized string in the custom_fields column of the tickets table. We detect the PHP version on the source server, apply the correct unserialization method (handling PHP 7 vs PHP 8 serialization differences), and extract each key-value pair. Each custom field becomes a HubSpot custom ticket property with a type determined during scoping (text, number, date, dropdown). We pre-create all HubSpot custom properties before migration so that ticket inserts do not fail on unknown property errors.

HelpDeskZ email-to-ticket routing stores POP3/IMAP credentials and mailbox settings in the database. We extract these settings and flag them in the migration inventory. The actual email pipeline cannot migrate because HubSpot's connected email channel uses OAuth2 authentication and its own mailbox routing, not POP3/IMAP polling. We deliver the mailbox settings to the customer's HubSpot admin to reconfigure as a HubSpot connected email channel post-migration.

HelpDeskZ created_date and updated_date timestamps on each ticket are preserved as HubSpot ticket createdate and hs_last_modified_date. These timestamps are critical for reporting on historical ticket volume and agent response times. We set these via the HubSpot Tickets API at insert time rather than relying on HubSpot's default server-side timestamp.

The complete HelpDeskZ configuration schema — ticket statuses, priorities, departments, and any custom ticket type flags — is documented in the migration inventory. This document is the reference for rebuilding the equivalent configuration in HubSpot Service Hub. We deliver this before migration begins so that the customer can configure HubSpot pipelines and teams while data extraction is underway.