# Salesforce Files Bulk Downloader: A Robot Framework tool for audited file exports > A Robot Framework and Python tool that downloads Salesforce files by ContentDocumentId, validates each download against ContentSize, and produces Data Loader-ready workbooks. Suited to migration teams that need an auditable, batch-oriented export path. **b-vamsipunnam/salesforce-files-downloader-tool** — Bulk Salesforce Files downloader built with Robot Framework and Python. Supports parallel batches, validated downloads, CI, and Data Loader-ready migration workbooks. - Repository: https://github.com/b-vamsipunnam/salesforce-files-downloader-tool - Stars: 24 · Forks: 14 - Language: RobotFramework - License: MIT - Published: 2026-08-27 · Updated: 2026-08-27 · Language: en - Canonical page: https://hysenlabs.com/projects/b-vamsipunnam-salesforce-files-downloader-tool ## What the tool actually does The Salesforce Files Bulk Downloader solves a narrow problem: given a spreadsheet of ContentDocumentId values, it downloads the current file content to local storage and produces a set of audit artifacts. It does not discover file IDs. It does not upload files to a target org. The README is explicit that the tool only downloads the current file content to local storage. That makes it a migration preparation tool, not a full data mover. The intended users are developers or migration teams who already have an approved query or export that produces the file IDs. The tool's value is in the validation and the audit trail, not in the discovery step. If you expect a tool that scans Salesforce for files matching criteria, this is the wrong starting point. ## How the download and validation flow works The architecture mixes Salesforce REST APIs for metadata with an authenticated Selenium browser for the binary download. The README states that Salesforce REST APIs provide the metadata, and an authenticated Selenium browser downloads the binaries from Shepherd. Shepherd is a Salesforce service that serves file content. The Robot Framework orchestrates the workflow, and Pabot can run isolated batches in parallel. A file counts as successful only after four conditions are met: the download finishes, its size matches the Salesforce ContentSize, it is moved to its final folder, and any requested migration rows are saved. This strict definition means a partial or missing file is never reported as downloaded. The tool also handles the case where one ContentDocument is attached to several records: it downloads one physical file per unique ContentDocumentId but writes multiple link records. That distinction is important for migration workbooks because a single file can appear in many ContentDocumentLink rows. ## Setup: from clone to first batch The quick start requires Python 3.10 or later, Google Chrome, Salesforce CLI, and a spreadsheet editor. After cloning the repository, you create a virtual environment and install requirements.txt, which pulls in Robot Framework, browser libraries, and Excel libraries. Sign in to Salesforce with the CLI: `sf org login web --alias source-org`, then verify with `sf org display --target-org source-org --json`. The tool needs a session file, generated by running a Robot Framework authentication task: `robot --variable ORG_ALIAS:source-org --output NONE --log NONE --report NONE src/robot/orchestrators/authenticate.robot`. This produces `org_info.json` in the repository root, which contains an access token and is ignored by Git. The README warns not to commit, print, or share it. The input is an Excel workbook with a worksheet named `Input`, where column A1 holds the header `ContentDocumentId` and each row below holds a valid ID starting with `069`. Blank cells are ignored, and duplicate forms of the same valid ID are processed once. To run the first batch, you execute a single Robot Framework test: `robot --test Download_Batch_1 --outputdir results src/robot/orchestrators/download.robot`. The command reports a failed test if any file remains unresolved, which is a deliberate design choice to prevent silent success. ## Output structure and the audit trail Every batch writes to a new directory whose name ends in a unique ID. Downloaded files go to `downloads/Download_Batch_1_//`. The migration workbooks, if requested, go to `artifacts/Download_Batch_1_/`. The failed-ID workbook is created only when failures occur, and it lists each unresolved ID with a failure code, message, and attempt count. The execution manifest is a JSONL file that provides a line-by-line audit log of the batch, its attempts, and committed successes. Robot Framework also produces `log.html`, `report.html`, and `output.xml` in the `results` directory. The README notes that these outputs can contain sensitive Salesforce IDs, metadata, filenames, and local paths, so they should be treated as migration data. The JSONL manifest is particularly useful for compliance because it records exactly what succeeded and what failed, with attempt counts. ## Failure handling and its limits The tool has a structured failure path. When a download fails, you open the failed-ID workbook and `results/log.html`, use the `FailureCode` and `FailureMessage` to diagnose, then fix the cause and rerun the batch. The README states that automatic retry applies only to failure types marked as transient. It does not repair invalid IDs, missing metadata, permissions, or expired sessions. Each retried download starts from the beginning. This is a genuine limitation. If your org session expires mid-batch, you must regenerate `org_info.json` and rerun the entire batch, not just the failed files. The tool also does not handle cases where the file content is corrupted but the size matches, because validation is based solely on ContentSize. That is a weak spot for data integrity checks, though it is a common trade-off in bulk download tools. ## Parallelism and CI readiness The repository mentions Pabot for running isolated batches in parallel, and the README lists CI as a supported use case. The GitHub Actions badge in the README implies a CI pipeline exists, though the details are not in the provided material. Parallel batches mean you can process multiple input workbooks at once, but each batch still requires its own authenticated session. The tool's reliance on a Selenium browser makes headless CI more complex, but not impossible. The README does not specify how to configure Pabot or how to run the tool in a headless environment. That is a gap you must fill from the docs/Architecture.md file, which is not included here. If your CI runners do not have Chrome or a virtual display, you will need to adapt the setup. ## Maintenance, license, and the alternative approach The project is MIT licensed, which permits commercial use with attribution. The last push was July 2026, and version 2.0.0 was released the same day, so the project appears actively maintained. The repository is not archived. Maintenance cost is moderate: you need to keep Python, Robot Framework, and browser libraries updated, and you must handle Salesforce API changes. The tool depends on Salesforce REST APIs and Shepherd, both of which can change without notice. A real alternative is using Salesforce CLI's own data export commands, such as `sf data export`, which can export records but not file binaries directly. Another alternative is writing a custom Python script using the Salesforce REST API to fetch ContentVersion data and download files via the `VersionData` field. That approach gives you full control over validation and retry logic, but you lose the built-in manifest and failed-ID workbook. The difference is that this tool provides a ready-made audit trail and a Robot Framework reporting layer, while a custom script requires you to build those from scratch. ## Conclusion Adopt this tool if you are a developer or migration team that already has a list of ContentDocumentId values, needs an auditable download process with size validation, and can tolerate a Selenium-based browser dependency. Do not use it if you need to discover files by query, upload to another org, or run without a GUI session. Before adoption, verify that your org's API permissions allow reading ContentDocument and ContentDocumentLink records, confirm that your Python 3.10 environment can install the Robot Framework and browser libraries, and test a small batch with the provided input template. The tool's value is its strict success criteria and JSONL manifest, so confirm those match your compliance needs before scaling to thousands of files. ## FAQ ### Can the Salesforce Files Bulk Downloader bulk download files from Salesforce? Yes, but only for files you have already identified. You paste ContentDocumentIds into the Input worksheet of input/Inputfile_1.xlsx and the tool downloads exactly those; it does not search the org for files and does not upload to another org. One physical file is stored per unique ID in a batch. ### How does the Salesforce Files Bulk Downloader download a single file from Salesforce? You run one Robot Framework test per workbook, for example robot --test Download_Batch_1 --outputdir results src/robot/orchestrators/download.robot. The bytes land in downloads/Download_Batch_1_//, and the console ends with counts of successful, failed and total IDs. ### How does the Salesforce Files Bulk Downloader export a file from Salesforce for migration? It does not export through Salesforce itself. It writes optional Excel files into artifacts/Download_Batch_1_/ for a later ContentVersion import and ContentDocumentLink mapping, and Salesforce Data Loader remains a separate desktop import and export tool that you run yourself. ### Are Salesforce Attachments being deprecated, and how does the Salesforce Files Bulk Downloader handle it? The README does not address deprecation. It describes a Salesforce File as one logical ContentDocument record identified by a ContentDocumentId plus version and record link data, and it works with IDs that start with 069 and contain 15 or 18 alphanumeric characters. ## Sources - [Official README](https://github.com/b-vamsipunnam/salesforce-files-downloader-tool#readme) - [Project repository](https://github.com/b-vamsipunnam/salesforce-files-downloader-tool) - [Release notes](https://github.com/b-vamsipunnam/salesforce-files-downloader-tool/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/b-vamsipunnam-salesforce-files-downloader-tool