Introduction

Migrating between CRM platforms is rarely just about moving data from point A to point B. When the transfer involves tens of thousands of attached files, the real challenge emerges from preserving context and relationships that spreadsheets and exports often obscure.

What Happened

A recent migration from Salesforce to HubSpot began with the expectation that field mapping and CSV cleanup would be the hardest parts. Instead, the team faced 53,640 case-related files that needed to remain traceable against only 770 corresponding support tickets in the destination. The mismatch forced a rethink of how attachments are tracked across systems.

Why This Matters

Without a deliberate identity layer, a CSV can carry properties but cannot map the chain from a source record to its physical files and finally to the target ticket. The engineer behind the project built an explicit manifest that linked source case numbers to exported files, then to destination ticket IDs, turning a chaotic upload into a deterministic process.

Key Takeaways

  • Build a manifest before uploading to resolve source-to-destination relationships upfront.
  • Treat empty cases as intentional records so the migration structure remains auditable.
  • Use business identifiers like case numbers as stable bridges between disparate systems.
  • Index source files once and reuse the mapping rather than scanning repeatedly during upload.
  • Design migration scripts to be restartable, persisting state so a mid-process halt doesn't require starting over.
  • Preserve original source IDs even after renaming or reorganizing files to maintain traceability.

Conclusion

When the storage model changes, identity and context must lead the way. Treating the manifest—not the upload script—as the primary artifact ensures that 53,640 files don't become 53,640 isolated decisions, but become a coherent, auditable migration. The real takeaway is that CRM migrations are ultimately about preserving meaning, not just moving bytes.