Contact
Privacy
Legal Notice - Impressum
Career
News
Salesforce files migration breaks projects because a file is not one record. Every file is a ContentDocument that holds one or more ContentVersion records, plus a ContentDocumentLink for each record, user, or group it is shared with. Moving the file content is only part of the work. Rebuilding the version chain, the ownership, and every link in the target org decides whether the files are usable on arrival.
Files in a Salesforce-to-Salesforce migration can surface late. A published conemis project notes that the gap in file handling may become visible only when execution reaches that phase, when the timeline is already set. Volumes can be large, the structure spans several objects, and older orgs can carry legacy Attachments next to modern Files. In a Service Cloud org merge for a German automotive and industrial supplier, the scope included 1 million email messages and 40 GB of email attachments.
This article explains why files and attachments resist generic tools, what a correct file migration actually involves, how to decide what happens to legacy Attachments, and how conemis transition cloud (ctc) moves the document layer while maintaining data integrity.
Files and Attachments is one of the six object families covered in our guide to Salesforce complex object data migration.
Salesforce files migration breaks projects because one document is spread across three objects, and legacy attachments follow a fourth model with different rules. A tool that loads one object at a time leaves the connections between them to be rebuilt by hand.
A ContentDocument is a container. Salesforce describes it as "a container for multiple version records." The file content itself lives in ContentVersion. Creating the first version without a ContentDocumentId creates the parent document automatically. Every later version must reference that existing ContentDocumentId.
The third object, ContentDocumentLink, connects the file to every place it is shared: records, users, groups, and libraries. Each link carries its own ShareType and Visibility. A single file can be shared up to 2,000 times, a count that includes shares with records, people, and groups.
An Attachment is a single record with one parent and one encoded body. Its parent is set on create, and the update call cannot change it. The API create call caps attachments at 25 MB, and attachments parented by an email are not returned by a query unless the user holds the Modify All Data permission.
In Lightning Experience, attachments added on a record's related list are added as Salesforce Files. An org with Attachments created before that change can hold both models side by side, and both have to be scoped.
A SOQL query on ContentVersion returns every version of a document. Load those rows into a new org as they are, and each one becomes a separate document: Salesforce adds a version to an existing document only when it references that document's ContentDocumentId. The export can also miss files entirely. By default, even users with View All Data can only query files they have access to. A file shared only with a record is not returned by a query that does not specify its ID, unless the Query All Files permission is turned on.
The links follow the same rule. By default, a query on ContentDocumentLink must filter on Id, ContentDocumentId, or LinkedEntityId. Querying it without that filter requires API version 59.0 or later and the Query All Files permission, which itself requires View All Data. Without that permission, the link layer has to be collected record by record or document by document, and the result is only as complete as that enumeration.
A correct file migration rebuilds each document version by version, relinks it to every record and user it was shared with, and paces the load against platform limits. The work breaks into three parts.
The first version of each document loads without a ContentDocumentId, which creates the document in the target org. Every later version then loads against that new ContentDocumentId, in the order the source recorded them. Order matters because the platform leaves little room to correct mistakes. Salesforce does not allow a version to be deleted through the API, and only the latest published version can be updated. Deleting the document removes all of its versions. A history loaded out of sequence cannot be repaired version by version; the document has to be rebuilt.
Every ContentDocumentLink in the source points to a source ID: a record, a user, a group, or a library. Before a link can load, each of those IDs has to resolve to its counterpart in the target org, with the original ShareType and Visibility carried across. This is the same reference-resolution problem that shapes Salesforce Chatter migration, and the two are connected: files posted in Chatter feeds are the same documents.
Original dates need the same care. On the objects that support it, Salesforce allows the audit fields CreatedDate, CreatedById, LastModifiedDate, and LastModifiedById to be set on insert only, never on update. A load that runs first and corrects dates later cannot recover them.
File volume runs into documented ceilings. Contact Manager, Group, Professional, Enterprise, Unlimited, and Performance Edition orgs can publish a maximum of 200,000 new versions per 24-hour period; Developer Edition and trial orgs can publish 2,500. The maximum number of documents that can be published is 30,000,000. At the 200,000 rate, publishing one million versions takes at least five 24-hour periods.
File size adds a second constraint. The UI accepts files up to 10 GB, but Salesforce's limits page lists lower ceilings for content uploaded through the APIs: 2 GB through REST API, 150 MB through Bulk API 2.0, and 10 MB through Bulk API. Files larger than 2 GB can be downloaded only through the REST API and the download servlet. Content sent through the API is also base64 encoded, which Salesforce notes increases the document size by approximately 37%. A large library needs a plan for both file size and volume before the first file moves.
ctc includes native Salesforce connectors built for content and collaboration objects, with transformation logic for Salesforce content objects pre-built into the platform. It carries the version history, ownership, and sharing permissions that files hold, reattaches each document to its parent records, and sequences large file transfers within volume and API limits, alongside the rest of the data in a controlled, traceable workflow.
The pattern is visible in a published project for a global media and entertainment company. The scope covered Chatter data, attachments, and files between Salesforce orgs. The first tool selected, a general data integration tool, reached its limits on the Chatter and file phase. The project record lists what had to be solved: version history, ownership, and sharing permissions on ContentDocument and ContentVersion records; associations between files, attachments, and their parent records rebuilt in the target org; and sequenced handling of the file and attachment layer within volume and API limits.
ctc delivered that layer intact. Chatter feeds, files, and attachments arrived in the target org correctly associated with their parent records and immediately usable. The client's own team ran the migration after three hours of enablement from conemis.
In the Service Cloud org merge for a German supplier to the automotive and industrial sectors, the scope included 1 million email messages and 40 GB of email attachments. The project transferred a total of 2 million records across 10 objects and 200 fields, with full-scope UAT, production, and delta runs, and the case study reports success in time, scope, and budget.
Scale is documented as well. In a consolidation for a global electrification, automation, and digitalization company, conemis consolidated 25,000 users from four Oracle CRM On Demand systems into Salesforce Sales and Service Cloud. All 30 million records and 1 TB of attachments were migrated with ctc, and the migration finished almost two months before the deadline.
Whether legacy Attachments become Files is a scoping decision, and it belongs in the object inventory, not in the middle of the load. In Lightning Experience, new attachments are already added as Salesforce Files, so an older org can carry years of Attachment records next to a growing Files library.
Moving Attachments as Attachments keeps the old model in the new org. Converting them means creating ContentVersion and ContentDocumentLink records instead, which changes the record counts, the reconciliation, and the tests that UAT has to cover. Either path is valid. What breaks projects is leaving the decision open until the file phase begins. Settle it during the object inventory, when it can still shape the timeline.
Yes, if the versions are rebuilt in order. The first version creates the document in the target org, and each later version loads against that new ContentDocumentId. ctc carries version history, ownership, and sharing permissions across, and reattaches each document to its parent records.
Data Loader loads one object at a time. A file migration spans ContentVersion, ContentDocument, and ContentDocumentLink, and by default, link queries must be filtered by record or document ID. The ordering, ID resolution, and pacing have to be orchestrated by hand. See how Data Loader compares to ctc across a full migration.
The Attachment object remains available in the API. In Lightning Experience, attachments added on a record's related list are added as Salesforce Files. Orgs with a long history can hold both, so the migration scope has to cover both.
Enterprise, Unlimited, and Performance Edition orgs can publish a maximum of 200,000 new versions per 24 hours. Content uploads through the API are capped at 2 GB through REST API and 150 MB through Bulk API 2.0. A file can be shared a maximum of 2,000 times.
Files can hold the contracts, case evidence, and working documents that teams attach to records. A migration that moves the records and loses the document history has not finished the job, however clean the straightforward data looks.
ctc migrates Salesforce files and attachments with their version history, ownership, sharing, and record associations preserved, alongside the rest of your data in one controlled, traceable workflow.
To scope a files and attachments migration for your org: