object/download FormID 20505
Download an object from S3 to a local path. Supports versioned objects and byte-range requests.
When to Use
- Report retrieval for email: Download an archived PDF report from S3 and attach it to an outgoing email notification.
- Configuration file fetch: Retrieve a workflow configuration or template file from S3 at runtime to parameterize downstream processing steps.
- Backup restoration: Download a backup archive from S3 to a local path as the first step in a data restoration workflow.
- ML model artifact retrieval: Fetch a trained model file from S3 to supply to a code execution or inference step within a workflow.
- Template-based document generation: Download a document template from S3, apply data merge operations, and re-upload the completed document.
Configuration
Connection
Credentials and region are not fields on this operation. Wire an S3 Server satellite node into this node's input. The satellite holds the vault credential (
ApiKey type — Username = access key ID, Password = secret key), the target AWS region, and an optional Service URL override for S3-compatible backends. Its values are merged onto this node at execution time and take precedence over anything set locally. See S3 Server (satellite) for the full field reference.
Tenant-prefixed:
objectKey is auto-prepended with tenants/{tenantId}/ before the request is sent to S3. The value you type is what other S3 nodes in this workflow should reuse; the output's effectiveObjectKey field carries the literal key actually read, for use with the AWS console, CLI, or other external tools.
Chaining straight into
object/upload: the raw downloaded bytes are always available on the node's data output regardless of dataMode — wire this node directly into an object/upload node's default Input Data Key (data) with no re-encoding step. dataMode only controls how the separate, human-inspectable fileData output field is encoded.
Operation Fields
| Field | Required | Description |
|---|---|---|
bucketName | Required | Name of the S3 bucket containing the object. |
objectKey | Required | Full key path of the object to download (e.g. reports/2026/05/summary.pdf). |
versionId | Optional | Specific version ID to download. Omit to retrieve the latest version. Only applicable to versioned buckets. |
downloadPath | Optional | Local file system path to save the downloaded file (e.g. /tmp/report.pdf). If omitted, the content is held in memory and passed downstream. |
rangeStart | Optional | Starting byte offset for a range request. Default: 0 (beginning of file). |
rangeEnd | Optional | Ending byte offset for a range request. Default: 0 (means full file — no range applied). |
Sample Configuration
// Credentials + region resolved from the connected S3 Server satellite — see s3-server-satellite.html
{
"resource": "object",
"operation": "download",
"bucketName": "acme-prod-reports",
"objectKey": "{{ $node.GetInvoiceRecord.output.s3Key }}",
"downloadPath": "/tmp/invoice-{{ $node.GetInvoiceRecord.output.invoiceId }}.pdf"
}Validation Errors
| Error Code | Cause & Resolution |
|---|---|
NoSuchKey | The specified objectKey does not exist in the bucket. Verify the key using bucket/search before downloading. |
NoSuchVersion | The specified versionId does not exist. The version may have been deleted. Omit versionId to download the latest version. |
AccessDenied | The IAM identity lacks s3:GetObject permission. Update the IAM policy to include s3:GetObject scoped to the bucket ARN. |
InvalidRange | The byte range (rangeStart–rangeEnd) is invalid (e.g. start exceeds file size). Verify range values against the known object size. |
Output
Success Port
| Field | Type | Description |
|---|---|---|
status | string | success on successful download. |
errorCode | string | Empty string on success. |
bucketName | string | Source bucket name. |
objectKey | string | Key of the downloaded object. |
downloadPath | string | Local path where the file was saved (if downloadPath was specified). |
size | long | Size of the downloaded object in bytes. |
eTag | string | ETag of the object — use for integrity verification. |
downloadedAt | string | ISO 8601 timestamp of the download. |
Error Port
On failure, activates with errorCode, errorMessage, and httpStatusCode. Handle NoSuchKey to trigger fallback generation or alerting when expected files are missing.
Sample Output
{
"status": "success",
"errorCode": "",
"bucketName": "acme-prod-reports",
"objectKey": "monthly/2026/05/billing-summary-2026-05.pdf",
"downloadPath": "/tmp/invoice-INV-20260526.pdf",
"size": 204800,
"eTag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
"downloadedAt": "2026-05-26T11:45:22Z"
}Expression Reference
| Expression | Result |
|---|---|
{{ $node.DownloadInvoice.output.downloadPath }} | Local file path — pass to an email attachment or document processing node. |
{{ $node.DownloadInvoice.output.size }} | File size in bytes — validate before processing large files. |
{{ $node.DownloadInvoice.output.eTag }} | ETag — compare against stored value to verify the correct version was downloaded. |
{{ $node.DownloadInvoice.output.downloadedAt }} | Download timestamp — log in the workflow execution audit trail. |
{{ $node.DownloadInvoice.output.objectKey }} | Confirm which S3 key was retrieved in log/notification messages. |
Node Policies & GuardRails
| Policy Area | Recommendation |
|---|---|
| Credential Storage | Store credentials in BizFirst Credentials Manager. Never hardcode. |
| IAM Permissions | Grant s3:GetObject scoped to the specific bucket ARN and key prefix. Add s3:GetObjectVersion if downloading versioned objects. |
| Key Validation | Always validate the object key expression before download — prevent downloading the wrong file by resolving keys from trusted workflow variable sources. |
| Temp File Cleanup | Delete temporary files from downloadPath after processing completes to prevent sensitive data accumulation on the workflow executor's file system. |
| Versioned Downloads | Specify versionId when reproducibility matters (e.g. legal holds, audit reviews). Omit for general-purpose downloads to always get the latest version. |
| Range Request Use | Use byte-range requests (rangeStart/rangeEnd) to extract headers or metadata from large binary files without downloading the full object. |
| ETag Verification | Compare the downloaded object's eTag against a stored expected value to detect unintended overwrites or corruption. |
| Sensitive Data Handling | Do not log downloadPath contents or pass file data through notification nodes that may store or display content. |
Examples
Example 1: Invoice Retrieval and Email Delivery
A customer requests a copy of their invoice. The workflow retrieves the stored PDF from S3 and delivers it as an email attachment.
// Node: LookupInvoice (Database → returns s3Key)
// Node: DownloadInvoicePDF (S3 — object/download)
{
"bucketName": "acme-billing-archive",
"objectKey": "{{ $node.LookupInvoice.output.s3Key }}",
"downloadPath": "/tmp/invoice-{{ $node.LookupInvoice.output.invoiceId }}.pdf"
}
// Node: EmailInvoice (EmailSmtp — send with attachment downloadPath)Example 2: Runtime Configuration Fetch
At workflow start, fetch the current environment configuration JSON from S3 and parse it for use throughout the workflow.
// Node: FetchConfig (S3 — object/download)
{
"bucketName": "acme-workflow-configs",
"objectKey": "environments/{{ $env.DEPLOY_ENV }}/config.json"
}
// Node: ParseConfig (JSON Transform → parse downloadPath contents)
// Sets $workflow.config = parsed JSON objectExample 3: Versioned Document Retrieval for Legal Review
A legal hold workflow retrieves a specific version of a contract document as it existed on a particular date.
// Node: GetSpecificVersion (S3 — object/download)
{
"bucketName": "acme-contracts",
"objectKey": "contracts/{{ $node.HoldRequest.output.contractId }}.pdf",
"versionId": "{{ $node.HoldRequest.output.requiredVersionId }}",
"downloadPath": "/tmp/hold-{{ $node.HoldRequest.output.contractId }}.pdf"
}
// Node: LogAccess (Jira — create issue for legal tracking)