salesforce-files-architecture
Working with Salesforce Files at the data layer — `ContentVersion` (the binary content + version metadata), `ContentDocument` (the parent / shareable handle), `ContentDocumentLink` (the sharing / parent-record join), the 2 GB single-file size limit and the 10 MB feed-attached limit, the deprecated `Attachment` object, the `Document` object (Classic-only), and Files Connect for external file sources. Covers SOQL patterns to enumerate files attached to a record, Apex insert / link patterns, sharing implications of `ShareType` and `Visibility`, and the migration path from the legacy Attachment object. NOT for LWC file upload UI components (see lwc/lwc-file-upload-patterns), NOT for static-resource bundling (see lwc/static-resources).
Best use case
salesforce-files-architecture is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Working with Salesforce Files at the data layer — `ContentVersion` (the binary content + version metadata), `ContentDocument` (the parent / shareable handle), `ContentDocumentLink` (the sharing / parent-record join), the 2 GB single-file size limit and the 10 MB feed-attached limit, the deprecated `Attachment` object, the `Document` object (Classic-only), and Files Connect for external file sources. Covers SOQL patterns to enumerate files attached to a record, Apex insert / link patterns, sharing implications of `ShareType` and `Visibility`, and the migration path from the legacy Attachment object. NOT for LWC file upload UI components (see lwc/lwc-file-upload-patterns), NOT for static-resource bundling (see lwc/static-resources).
Teams using salesforce-files-architecture should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/salesforce-files-architecture/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How salesforce-files-architecture Compares
| Feature / Agent | salesforce-files-architecture | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Working with Salesforce Files at the data layer — `ContentVersion` (the binary content + version metadata), `ContentDocument` (the parent / shareable handle), `ContentDocumentLink` (the sharing / parent-record join), the 2 GB single-file size limit and the 10 MB feed-attached limit, the deprecated `Attachment` object, the `Document` object (Classic-only), and Files Connect for external file sources. Covers SOQL patterns to enumerate files attached to a record, Apex insert / link patterns, sharing implications of `ShareType` and `Visibility`, and the migration path from the legacy Attachment object. NOT for LWC file upload UI components (see lwc/lwc-file-upload-patterns), NOT for static-resource bundling (see lwc/static-resources).
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Salesforce Files Architecture Salesforce Files is the modern file-storage primitive on the platform, replacing the legacy `Attachment` object. The data model is more flexible than `Attachment` (a single file can be linked to many records, versioned, and shared via libraries), and it is more complex (three sObjects participate in every linked-file relationship). LLMs and inexperienced practitioners frequently misunderstand which object holds the binary, which holds the parent link, and how sharing is computed. This skill is the data-layer walkthrough. It covers the three-object model, the size limits practitioners hit in production, the deprecated objects (Attachment, Document) you may inherit, and Files Connect for external file sources. ## The three-object model A "file" linked to a record involves three sObjects: | Object | Holds | Cardinality | |---|---|---| | `ContentVersion` | The binary content (`VersionData`), file name, type, and version metadata | One row per version of the file | | `ContentDocument` | The shareable handle / "file identity" | One row per file (across all versions) | | `ContentDocumentLink` | The link from the `ContentDocument` to a parent record | Many rows per file (one per linked record) | The relationship is: ``` ContentVersion (binary + version metadata) | v ContentDocument (file identity) <-- ContentDocumentLink --> Account, Case, Custom__c, etc. ^ ContentVersion v2 (later upload of the same file) ``` When you upload a new file, you insert a `ContentVersion`. The platform creates the `ContentDocument` automatically. To link the file to a record, you insert a `ContentDocumentLink` with `LinkedEntityId = recordId`, `ContentDocumentId = contentDocId`, and a `ShareType` / `Visibility`. When you upload a *new version* of an existing file, insert a `ContentVersion` with `ContentDocumentId` set to the existing file's `ContentDocument.Id` — the platform appends the version. ## Size limits - **2 GB** — maximum file size for a single Salesforce File (uploaded via UI, REST, or SOAP API; subject to edition / license caveats). - **38 MB** — maximum size when uploaded via Lightning component (`lightning-file-upload`) without chunking; larger needs Apex / REST chunked upload. - **10 MB** — maximum size for a file attached to a Chatter feed comment. - **25 MB** — maximum for the legacy `Attachment.Body` field, one reason `Attachment` is deprecated. These limits are platform constraints; some can be raised via Salesforce Support, but expect the defaults in any greenfield design. ## Sharing — `ShareType` and `Visibility` `ContentDocumentLink` carries two fields that determine how a file is shared: - `ShareType` — `'V'` (Viewer), `'C'` (Collaborator), `'I'` (Inferred / parent-record-driven). - `Visibility` — `'AllUsers'` (anyone with parent-record access can see the file) or `'InternalUsers'` (internal users only; Experience Cloud / portal users excluded). `ShareType = 'I'` (Inferred) is the most common default — it makes file access mirror the parent record's sharing. `'V'` and `'C'` override that for explicit grant scenarios. ## Deprecated objects you may inherit - **`Attachment`** — the legacy object. Body field max 25 MB, no versioning, no multi-record link, no library support. New development should not use it. Migration path: read each Attachment's `Body` blob, insert as `ContentVersion`, link via `ContentDocumentLink`, then delete the original Attachment. - **`Document`** — Salesforce Classic-only object for static org- level documents. Replaced by Files / static resources / CMS for modern UIs. ## Files Connect Files Connect lets a Salesforce org browse / link files that live in external sources (Google Drive, SharePoint, Box, etc.) without copying them into Salesforce storage. Like External Objects for files: the file content stays at the source; Salesforce shows a reference. Auth is via named credential. ## Recommended Workflow 1. **Confirm whether legacy `Attachment` data exists.** Query `SELECT COUNT(Id) FROM Attachment`. If non-zero, plan a migration — the object remains supported but is deprecated for new development. 2. **Choose the right object for the use case.** Per-record file = ContentVersion + ContentDocumentLink. Org-wide library file = ContentVersion in a Library. External file source = Files Connect. 3. **Plan the sharing model.** Most use cases want `ShareType = 'I'` (inferred from parent record). Explicit grants (`'V'` Viewer or `'C'` Collaborator) for cross-record sharing. 4. **Size the file storage budget.** Salesforce Files counts against File Storage allocation, distinct from Data Storage. Check Setup -> System Overview for the org's file storage and forecast against expected upload volumes. 5. **For Apex inserts.** First insert `ContentVersion` with `VersionData = blob`, then query `ContentDocumentId` from the inserted ContentVersion, then insert `ContentDocumentLink` to link to the record. Three-step pattern, not one. 6. **For SOQL "files attached to this record".** Query `ContentDocumentLink WHERE LinkedEntityId = :recordId`, then traverse to `ContentDocument` and (if needed) the latest `ContentVersion`. 7. **Guard against the 2 GB single-file ceiling.** For media / video / large datasets above this, use external storage with Files Connect or another integration and link rather than upload. ## What This Skill Does Not Cover | Topic | See instead | |---|---| | LWC file upload UI components | `lwc/lwc-file-upload-patterns` | | Static resources for LWC bundling | `lwc/static-resources` | | Salesforce CMS for marketing content | `experience/salesforce-cms-patterns` | | Big-file media streaming use cases | App-layer (S3 + signed URLs, etc.) |
Related Skills
salesforce-shield-deployment
Roll out Shield (Platform Encryption + Event Monitoring + Field Audit Trail) end-to-end, sequencing feature enablement to avoid data lockout. NOT for Classic Encryption or general PE design.
ferpa-compliance-in-salesforce
Use this skill when implementing FERPA (Family Educational Rights and Privacy Act) compliance controls in Salesforce Education Cloud or Education Data Architecture (EDA): LearnerProfile FERPA boolean fields, directory information opt-out via FLS and Individual data privacy flags, ContactPointTypeConsent for parental and third-party disclosure, 45-day student records response window tracking, and consent workflow automation. Trigger keywords: FERPA, student records privacy, LearnerProfile, parental disclosure, directory information opt-out, education data privacy, student consent, education cloud compliance. NOT for GDPR/CCPA general data privacy (see gdpr-data-privacy skill), platform encryption at rest (see platform-encryption skill), or HIPAA health-data compliance.
industries-cpq-vs-salesforce-cpq
Use this skill when comparing Industries CPQ (formerly Vlocity CPQ) with Salesforce CPQ (Revenue Cloud managed package) — covering feature parity, decision criteria, migration paths, and coexistence patterns. Trigger keywords: Vlocity CPQ, Industries CPQ, Salesforce CPQ comparison, Revenue Cloud migration, CPQ selection, which CPQ to use. NOT for implementing, configuring, or debugging either CPQ product.
tableau-salesforce-connector
Tableau ↔ Salesforce integration patterns: Tableau Salesforce connector, Tableau for Salesforce, CRM Analytics alternative, Data Cloud + Tableau, embedded Tableau dashboards. Choose between connector modes (live, extract, direct-to-Data-Cloud). NOT for CRM Analytics Studio (use crm-analytics-foundation). NOT for generic Tableau Server setup.
slack-salesforce-integration-setup
Use this skill when setting up or troubleshooting the Salesforce for Slack managed app — including connecting a Salesforce org to a Slack workspace, configuring the three-party admin handshake, linking Slack channels to Salesforce records, enabling record preview sharing, and managing org-level limits. Triggers on: Salesforce for Slack app not connecting, Slack org connection setup, Salesforce record sharing in Slack, Slack workspace admin approval, connecting Salesforce to Slack. NOT for building custom Slack apps or Slack bots (separate development platform), not for Slack Workflow Builder Salesforce connector (use slack-workflow-builder skill), not for Flow-based Slack messaging (use flow-for-slack skill).
salesforce-to-salesforce-integration
Use this skill to implement Salesforce-to-Salesforce integration patterns — covering the native S2S feature, API-based cross-org sync, Platform Event bridging, and Salesforce Connect Cross-Org adapter. Trigger keywords: Salesforce to Salesforce integration, cross-org data sharing, S2S feature, cross-org Platform Events, Salesforce Connect cross-org. NOT for multi-org strategy or architecture decisions (use architect/multi-org-strategy), single-org data sharing, or external (non-Salesforce) system integration.
salesforce-maps-setup
Use when configuring Salesforce Maps (formerly MapAnything) — territory planning, route optimization, live tracking, geo-grid visualizations, and check-in/check-out workflows for Sales or Service field reps not on Field Service. Covers package installation order (Maps + Maps Advanced + Maps Routing/Live Tracking add-ons), the MapsTerritoryPlan / MapsAdvancedRoute / MapsLayer object family, base-data syncs (Geocoding and Routing services), and integration with Sales and Service Cloud records. Triggers: 'Salesforce Maps setup', 'MapAnything migration', 'territory planning by polygon', 'route optimization for sales reps', 'live tracking field reps', 'plot accounts on a map', 'check-in to the closest account'. NOT for Field Service Lightning territory and scheduling (use admin/fsl-scheduling-optimization-design and data/fsl-territory-data-setup) — Maps and FSL are different products. NOT for Consumer Goods Cloud retail visit planning (use admin/consumer-goods-cloud-setup) — RoutePlan/Visit objects are CG-specific. NOT for Tableau / CRM Analytics geo charts.
salesforce-functions-replacement
Salesforce Functions is retired (EOL Jan 2025). This skill maps Functions workloads to replacements: Heroku (with Hyperforce), external containers, Apex (where viable), Agentforce Actions, external compute via Named Credentials. NOT for Lambda / Azure Functions tutorials. NOT for Apex @future replacement (use async-selection tree).
salesforce-data-pipeline-etl
Export large Salesforce datasets to a lakehouse via Bulk API 2.0, CDC streams, or Salesforce Data Pipelines. NOT for ad-hoc exports.
salesforce-connect-external-objects
Use when deciding whether Salesforce Connect and External Objects are the right fit for external data access, or when reviewing OData, cross-org, and custom adapter patterns, query limitations, and latency tradeoffs. Triggers: 'Salesforce Connect', 'External Objects', '__x', 'OData adapter', 'custom adapter'. NOT for ordinary ETL or replicated-data designs where the data should live inside Salesforce.
outbound-webhook-from-salesforce
Use when Salesforce must POST a webhook to a third-party endpoint after a record change — with signed payloads, retries, dead-lettering, rate limits, and idempotency. Covers design choice between Outbound Message, Flow HTTP Callout, Apex Queueable callout, and Event Relay. Does NOT cover inbound webhooks into Salesforce (see inbound-webhook or apex-rest-webhook).
mulesoft-salesforce-connector
Designing and configuring MuleSoft Anypoint Salesforce Connector flows: API selection (SOAP/REST/Bulk/Streaming), OAuth 2.0 JWT Bearer auth, watermark-based incremental sync with Object Store, batch processing with record-level error isolation, and replay topic subscriptions. Use when building Mule 4 flows that read from or write to Salesforce, migrating from Mule 3 watermark to Mule 4 Object Store, or troubleshooting connector authentication and API limits. NOT for native Salesforce-to-Salesforce integration without MuleSoft (use platform-events-integration or change-data-capture-integration). NOT for generic REST callout patterns from Apex (use rest-api-patterns).