How to Insert Files into Salesforce: A Practical, Step‑by‑Step Guide
Insert Salesforce Files during a migration or bulk update of Salesforce is less mysterious than it sounds. Follow a clear four‑step process, prepare a proper mapping file, and you’ll move files into Salesforce reliably. This guide walks through the core concepts, exact Excel prep, Data Loader settings, and the follow‑up steps needed to link files to records.
Table of Contents
Download the "Files Workbook" Excel template here.
Instructions: The link takes you to google drive. Click “File” and choose Download, then click on Microsoft Excel. This will send the workbook to your downloads.
Overview: The four core elements
Successfully inserting files into Salesforce requires attention to four things:
- Set Data Loader batch size to 1.
- Prepare a mapping file that points Data Loader to your local files.
- Insert into the ContentVersion object. Optionally map a parent record via the
FirstPublishedLocationIdto attach during insert. - Link files to records by inserting rows into
ContentDocumentLinkafter ContentVersion inserts succeed.
Understand how Salesforce stores files
A file upload creates a ContentVersion record — that is where the actual file is stored. Salesforce automatically creates a ContentDocument record to group versions of the same file. You do not insert ContentDocument directly.
If you set FirstPublishedLocationId during your ContentVersion insert, Salesforce also creates a corresponding ContentDocumentLink that attaches the file to a record (Account, Opportunity, etc.). If you omit that field, files go into private files and can be linked later by inserting ContentDocumentLink records.
Step-by-step: Build the mapping file
The mapping file is an Excel workbook that tells Data Loader where each file lives on your machine and supplies required metadata for ContentVersion. If you are migrating between Salesforce orgs, your full backup should include a ContentVersion CSV and a folder of actual files.
1. Filter and copy the ContentVersion CSV
Open the exported ContentVersion CSV. Filter to keep rows where ContentUrl is blank (this excludes non-file records). If your source uses multiple versions, also filter where IsLatest = 1. Copy the filtered rows into a new sheet in your workbook.
2. Collect the actual files into one folder
Download all exported file folders to your hard drive. If the export split files across multiple zip archives (Salesforce zip limit is ~512 MB), move files out of extra folders into a single folder so the path is consistent.
3. Capture the local path
In the workbook, add a column (example header: XMyPath) and paste the folder path to the files. Prefix the header with X to avoid Data Loader auto-mapping it. On macOS use forward slashes and append a trailing slash; on Windows use backslashes and append a trailing backslash.
4. Create VersionData and PathOnClient
VersionData must be a full local path to the file. Create a new column named VersionData and use Excel concatenate to join the local path and the file name (in Salesforce exports, file names are often the ContentVersion IDs).
PathOnClient should include the file name plus extension. Concatenate VersionData with a period and the file type (extension) so Salesforce’s native preview works from a record’s files list.
After using formulas, replace them with values (Paste Special → Values) so Data Loader reads static paths.
5. Required and optional fields
- Required:
Title(file name),VersionData,PathOnClient. - Optional:
Description,OwnerId,CreatedById,CreatedDate,FirstPublishedLocationId.
Handling user and record lookups
To preserve OwnerId and CreatedById you can either:
- Bring target org user IDs into your mapping file via a VLOOKUP in Excel.
- Use Data Loader Step 2B to reference legacy IDs you previously loaded into the User object.
If your source references multiple object types (Accounts, Opportunities, etc.), prefer Excel VLOOKUPs to pull in the correct target IDs for FirstPublishedLocationId.
Best practices before inserting
Add legacy ID field on ContentVersion
Create a Legacy ID field on ContentVersion and map the source ContentVersion ID to it. This helps with later joins.
Test with a small batch insert
Create a Legacy ID field on ContentVersion and map the source ContentVersion ID to it. This helps with later joins.
Insert ContentVersion first, then ContentDocumentLink
Do a small test insert with a few rows to catch issues early.
Insert into ContentVersion
With the mapping file ready, insert into ContentVersion using Data Loader. If you mapped FirstPublishedLocationId and the IDs are correct, the ContentDocumentLink will be created automatically.
If you did not publish during the first insert (or need multiple links per file), follow these steps after ContentVersion insert:
- Export
ContentDocumentfrom the target org with fieldsIdandLatestPublishedVersionId. - Use a VLOOKUP to match each ContentVersion (success file) to its ContentDocument Id via
LatestPublishedVersionId. - Create a mapping file with
ContentDocumentIdandLinkedEntityId(the record to attach to). - Set Data Loader batch size back to a higher number (for example 200) and insert into
ContentDocumentLink.
After the ContentDocumentLink insert you can spot‑check a few linked records in Salesforce to confirm files appear on the related record’s files list.
Troubleshooting tips
- If paths fail, ensure files are on local hard drive (avoid iCloud or synced folders on Mac that can return virtual paths).
- To take advantage of previewing files, confirm PathOnClient includes a file extension.
- When multiple zip archives were created during export, consolidate files into one folder so a single path address works for all.
- Keep a success and error output folder from Data Loader to iterate quickly on any failures.
Quick checklist
- Create mapping workbook and filter ContentVersion rows
- Download and consolidate files to a local folder
- Capture folder path and build
VersionDataandPathOnClient - Add legacy ID field on ContentVersion and map source ID
- Set Data Loader batch size to 1 and run a small test
- Insert into ContentVersion, export ContentDocument, perform VLOOKUP
- Insert ContentDocumentLink to attach files to records
FAQ
Why set Data Loader batch size to one?
Files must be uploaded individually. A batch size of one ensures each ContentVersion receives the full file payload without being split across batches, which prevents corrupted uploads and mapping errors.
What is the difference between VersionData and PathOnClient?
VersionData is the full local file path used by Data Loader to read the file. PathOnClient tells Salesforce the file name (including extension) to display and enables native file preview functionality.
How do I attach one file to multiple records?
After inserting ContentVersion and obtaining the ContentDocumentId, insert one or more ContentDocumentLink rows per record you want the file attached to, mapping ContentDocumentId and LinkedEntityId.
Can I preserve original ownership and created dates?
Yes. You can map OwnerId, CreatedById, and CreatedDate if you bring the corresponding target org IDs into your mapping file (via VLOOKUP) or use Data Loader step 2B with legacy IDs for the User object.
What if I receive nested folders or multiple zip archives?
Move all files into a single folder so the path is consistent. If the export split content across zips, combine the files into one directory and then use that path in your mapping file. I have had to write code to mass move files from nested sub folders and will explain that in a separate lesson.
Final note
When inserting files, allocate time to prepare your data maps correctly, respect Data Loader settings, and follow the two‑step insert/link pattern. A small test insert will save time and headaches later. Once everything is in place, you can attach files to any record and retain metadata that matters.
2 Responses