S3 — object/download

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

Field	Required	Description
`accessKeyId`	Required	AWS Access Key ID. Store in BizFirst Credentials Manager.
`secretKey`	Required	AWS Secret Access Key. Never log or expose.
`sessionToken`	Optional	STS session token for temporary credentials.
`region`	Required	AWS region of the source bucket.

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

{
  "connection": {
    "accessKeyId": "{{ $credentials.s3_prod.accessKeyId }}",
    "secretKey": "{{ $credentials.s3_prod.secretKey }}",
    "region": "us-east-1"
  },
  "operation": {
    "resource": "object",
    "action": "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 object

Example 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)

object/download FormID 20505