53,640 Salesforce Files, 770 HubSpot Tickets, and One Migration Lesson

The reporter was initially focused on the challenges of schema mapping and CSV cleanup during a Salesforce-to-HubSpot migration. However, the most significant hurdle turned out to be the historical support data. There were 53,640 case-related files that needed to be preserved in their original state, while only 770 support tickets existed in the destination at the time.

The CSV format is capable of transferring property information, but it does not automatically maintain the relationships between records, their attachments, physical files in an export, and the objects representing those records in another platform. Therefore, the reporter realized that they needed to establish an explicit identity layer first, establishing the relationship between source case numbers, source records, exported files, and destination tickets.

This formed the basis for the control plane of the migration. The reporter initially thought that CSVs would be the difficult part, given that the migration generally started with inventorying Salesforce objects, cleaning the data, mapping fields, and importing records. However, historical support cases posed a unique challenge.

The Salesforce export arrived in multiple archives, containing thousands of physical files linked to historical cases. Upon completion, the destination only had 770 HubSpot tickets. This led to the realization that they needed to answer three questions for each file: which Salesforce case it belonged to, whether that case had a corresponding destination ticket, and how to attach the correct file to the correct ticket without losing its original identity.

This presented an identity-mapping issue, not a CSV-import problem. Salesforce exports maintain the data but do not necessarily preserve the human context. The export process uses Salesforce IDs rather than original filenames for physical attachment files, which can be confusing for humans trying to retrieve files six months later.

Hence, the reporter decided to keep both the IDs and the original filenames to maintain the evidence of each file's origin. A normalized manifest was created to resolve source-system relationships before migration. This manifest provided a clear, structured outline of each file's journey, including its original case number, source file ID, original file name, exported file path, and destination ticket ID.

By creating a manifest, the reporter could answer basic questions about file counts, case tickets, source file origins, and migration status without querying either CRM. Each case was given a directory structure, even if it didn't have any associated files. This made it clear which cases had no attachments, providing a definitive answer to the ambiguity of missing directories.

Finally, the reporter emphasized that the migration process should not only transfer data into the destination application. It should also leave behind an archive that future engineers could understand without needing to reverse-engineer the migration script.