Salesforce Attachment Object: From Legacy to Files

Salesforce may have moved on to the newer Files framework, but the Attachment object still shows up in many orgs through older setups, integrations, or historical data. 

In this article, we’ll look at what the Attachment object is, how it differs from Files, the main challenges it presents, and what to keep in mind when working with these legacy records.

What Is the Salesforce Attachment Object?

The Attachment object is a legacy Salesforce object used to store files on individual records through the ParentId field. It remains available for backward compatibility but has been replaced by Salesforce Files.

Key Details

• Storage: File content stored in the Body field as Base64.
• Limit: Maximum size is 25 MB per file attachments and 2 GB for feed attachments.
• Linking: One attachment can be associated with one record only.
• Versioning: Not supported; uploads overwritten existing files.
• Search: Not available in Lightning global search.

Attachments still exist in older orgs, legacy integrations, and historical records or backups.

In Lightning Experience, new file uploads no longer create attachments. Instead, they are stored as Salesforce Files using the ContentVersion, ContentDocument, and ContentDocumentLink objects.

Why did Salesforce Replace Attachments with Files?

With the Salesforce Spring ’17 release, files uploaded to the Notes & Attachments related list began storing as Salesforce Files instead of traditional Attachments. This update replaced the older Attachment object with the more flexible ContentDocument architecture.

The Architectural Change

Salesforce does not use a single “File” object. Instead, it relies on three objects: ContentDocument, ContentVersion, and ContentDocumentLink.

• ContentDocument – Represents the file itself.
• ContentVersion – Stores each version of the file, past and present.
• ContentDocumentLink – Defines where the file is shared, such as with users, records, groups, or libraries.

Versioning

Salesforce Files support version history. Users can upload a new version of a document while keeping all previous versions accessible. Attachments lacked this capability because every upload created a separate file.

Multi-Record Linking

A single file can be related to multiple records using ContentDocumentLink. Any updates to the file automatically apply everywhere it is linked, reducing storage use and ensuring consistency.

Improved Search, Preview, and Sharing

• Search: Files support full-text search within documents, not just filenames.
• Preview: Many file types can be previewed directly in Salesforce without downloading.
• Sharing: Files allow granular sharing settings and can be distributed easily through Chatter, links, or Salesforce libraries.

By moving to Salesforce Files, organizations gain a scalable, collaborative, and more manageable way to store and share content inside Salesforce.

Salesforce Files vs Notes and Attachments

Salesforce provides two primary options for storing and managing documents: Files and Notes & Attachments. Although both serve the purpose of associating content with records, they differ significantly in functionality, flexibility, and long-term usability.

Common Issues with Legacy Attachments

Attachments were once Salesforce’s standard for storing files, but they have not evolved alongside the platform. As Salesforce focuses on Files, several limitations have become clear.

API Limitations 

Salesforce no longer adds features to attachments. They remain functional, but all improvements in file storage and sharing are in the Files framework, making attachments less suitable for future needs.

Customization Limits 

The Attachment object cannot be customized. You can’t add fields to store extra metadata, and the Notes & Attachments related list is hardcoded, limiting layout changes.

Migration Difficulties

Converting Attachments to Files requires understanding the relationship between ContentDocument, ContentVersion, and ContentDocumentLink objects. Migration must carefully preserve ParentId relationships and metadata to prevent data loss. The process is further complicated by large volumes of files and varied formats.

XL-Connector helps simplify this process by allowing you to download attachments in bulk to your local system. To migrate them as Salesforce Files, you can use XL-Connector to upload the files in bulk into the ContentVersion object.

This saves time and gives admins a no-code way to handle large volumes of files. For a detailed walkthrough, check out our related article: Download Attachments from Salesforce: Complete Guide.

 

Accessing Legacy Attachments in Lightning Experience

In Lightning Experience, users can still open and view legacy attachments from the Notes & Attachments related list on records. However, these attachments do not appear in global or record-level searches, which limits their visibility.

Conclusion

The Attachment object offered a simple way to store files in Salesforce, but its capabilities were limited. Salesforce Files provide a more flexible model, built on the ContentDocument framework, that supports sharing, collaboration, and linking a single file to multiple records.

If your org still relies on Attachments, start planning a migration. Use available tools to export and convert them into Salesforce Files to keep your data accessible and aligned with Salesforce’s current file storage model.