Skip to content

hardis:org:files:export

Description

Command Behavior

Exports file attachments (ContentVersion, Attachment) from a Salesforce org based on a predefined configuration.

This command enables the mass download of files associated with Salesforce records, providing a robust solution for backing up files, migrating them to other systems, or integrating them with external document management solutions.

Key functionalities:

  • Configuration-Driven Export: Relies on an export.json file within a designated file export project to define the export criteria, including the SOQL query for parent records, file types to export, output naming conventions, and file size filtering.
  • File Size Filtering: Supports minimum file size filtering via the fileSizeMin configuration parameter (in KB). Files smaller than the specified size will be skipped during export.
  • File Validation: After downloading each file, validates the integrity by:
    • Checksum Validation: For ContentVersion files, compares MD5 checksum with Salesforce's stored checksum
    • Size Validation: For both ContentVersion and Attachment files, verifies actual file size matches expected size
    • Status Tracking: Files are categorized with specific statuses: success (valid files), failed (download errors), skipped (filtered files), invalid (downloaded but failed validation)
    • All validation results are logged in the CSV export log for audit purposes
  • Resume/Restart Capability:
    • Resume Mode: When --resume flag is used (default in CI environments), checks existing downloaded files for validity. Valid files are skipped, invalid files are re-downloaded.
    • Restart Mode: When resume is disabled, clears the output folder and starts a fresh export.
    • Interactive Mode: When existing files are found and --resume is not explicitly specified (non-CI environments), prompts the user to choose between resume or restart.
  • Interactive Project Selection: If the file export project path is not provided via the --path flag, it interactively prompts the user to select one.
  • Configurable Export Options: Allows overriding default export settings such as chunksize (number of records processed in a batch), polltimeout (timeout for Bulk API calls), and startchunknumber (to resume a failed export).
  • Support for ContentVersion and Attachment: Handles both modern Salesforce Files (ContentVersion) and older Attachments.

See this article for a practical example:

How to mass download notes and attachments files from a Salesforce org

Technical explanations

The command's technical implementation involves:

  • FilesExporter Class: The core logic is encapsulated within the FilesExporter class, which orchestrates the entire export process.
  • SOQL Queries (Bulk API): It uses Salesforce Bulk API queries to efficiently retrieve large volumes of parent record IDs and file metadata, including checksums and file sizes.
  • File Download: Downloads the actual file content from Salesforce.
  • File Validation: After each successful download, validates file integrity by comparing checksums (ContentVersion) and file sizes (both ContentVersion and Attachment) against Salesforce metadata.
  • Resume Logic: In resume mode, checks for existing files before downloading, validates their integrity, and only re-downloads invalid or missing files. This enables efficient recovery from interrupted exports.
  • File System Operations: Writes the downloaded files to the local file system, organizing them into folders based on the configured naming conventions.
  • Configuration Loading: Reads the export.json file to get the export configuration. It also allows for interactive overriding of these settings.
  • Interactive Prompts: Uses selectFilesWorkspace to allow the user to choose a file export project, promptFilesExportConfiguration for customizing export options, and prompts for resume/restart choice when existing files are found.
  • Error Handling: Includes mechanisms to handle potential errors during the export process, such as network issues, API limits, and file validation failures. Each file is assigned a specific status (success, failed, skipped, invalid) for comprehensive tracking and troubleshooting.

Parameters

Name Type Description Default Required Options
chunksize
-c		 option Number of records to add in a chunk before it is processed 1000
debug
-d		 boolean Activate debug mode (more logs)
flags-dir option undefined
json boolean Format output as json.
path
-p		 option Path to the file export project
polltimeout
-t		 option Timeout in MS for Bulk API calls 300000
resume
-r		 boolean Resume previous export by checking existing files (default in CI)
skipauth boolean Skip authentication check when a default username is required
startchunknumber
-s		 option Chunk number to start from
target-org
-o		 option undefined
websocket option Websocket host:port for VsCode SFDX Hardis UI integration

Examples

$ sf hardis:org:files:export