Common Properties (all operations)
| Property | Type | Required | Description |
|---|
operation | string | Required |
Operation to perform. One of: upload, download, list, delete, copy, getPresignedUrl. |
bucket | string | Required |
Name of the S3 bucket. For copy this is the destination bucket. Supports expressions, e.g. {@ $var.targetBucket }. |
credential_id | string | Required |
ID of the AWS credential stored in BizFirst Credentials Manager. Must include access_key_id, secret_access_key, and region. |
region | string | Optional |
AWS region override (e.g. us-east-1, eu-west-1). If omitted, the region from the credential is used. |
upload Properties
| Property | Type | Required | Description |
|---|
key | string | Required | The S3 object key (file path). Use forward slashes to organise into virtual folders: invoices/2026/05/INV-00421.pdf. Supports expressions. |
file_data | string | Required | File content to upload. For binary files (PDF, images, archives), provide base64-encoded data. For text files (JSON, CSV, TXT), provide the raw string. Supports expressions. |
content_type | string | Optional | MIME type of the object, e.g. application/pdf, text/csv, image/png, application/json. Sets the Content-Type header on the stored object. |
encoding | string | Optional | How to interpret file_data. Options: base64 (default for binary), utf-8 (for text). Default: auto-detected based on content_type. |
acl | string | Optional | Access control list. Options: private (default), public-read, authenticated-read. Use private for all sensitive business documents and use pre-signed URLs to share. |
metadata | object | Optional | Custom key-value metadata attached to the object as HTTP headers (prefixed with x-amz-meta-). Values must be strings. Example: {"workflow_id": "wf-123", "customer_id": "CUST-441"}. |
cache_control | string | Optional | HTTP Cache-Control header for objects served from S3 or CloudFront. Example: max-age=86400. |
download Properties
| Property | Type | Required | Description |
|---|
key | string | Required | The S3 object key to download. |
output_format | string | Optional | How to return file data. Options: base64 (default — safe for all file types), text (UTF-8 string, for text files), json (parsed JSON object, for JSON files). Default: base64. |
version_id | string | Optional | Retrieve a specific version of the object (requires bucket versioning enabled). |
list Properties
| Property | Type | Required | Description |
|---|
prefix | string | Optional | Filter objects to those whose keys begin with this string. Used to list a virtual folder, e.g. reports/2026/05/. If omitted, all objects in the bucket are listed. |
max_keys | integer | Optional | Maximum number of objects to return. Default: 1000. S3 maximum per request: 1000. |
delimiter | string | Optional | Delimiter character for grouping keys. Typically /. When set, the list operation groups keys by virtual folder and returns common_prefixes (sub-folder names) alongside matching objects. |
continuation_token | string | Optional | For paginated listing — pass the next_continuation_token from a previous list response to retrieve the next page of results. |
delete Properties
| Property | Type | Required | Description |
|---|
key | string | Required | The S3 object key to permanently delete. Deletion is irreversible for non-versioned buckets. |
version_id | string | Optional | Delete a specific version of the object (requires bucket versioning enabled). If omitted on a versioned bucket, a delete marker is created. |
copy Properties
| Property | Type | Required | Description |
|---|
source_bucket | string | Required | The source bucket name. |
source_key | string | Required | The source object key. |
dest_key | string | Required | The destination object key in the destination bucket (set as bucket in common properties). |
acl | string | Optional | ACL to apply to the copied object. If omitted the source ACL is preserved. |
metadata_directive | string | Optional | COPY (default — copy source metadata) or REPLACE (use new metadata from the metadata field). |
getPresignedUrl Properties
| Property | Type | Required | Description |
|---|
key | string | Required | The S3 object key to generate a URL for. |
method | string | Required | GET for a download URL, PUT for an upload URL. Use PUT to allow external parties to upload files directly to S3. |
expiry_seconds | integer | Optional | Seconds until the URL expires. Default: 3600 (1 hour). Maximum: 604800 (7 days) for IAM user credentials. For STS temporary credentials the maximum is the session duration. |
content_type | string | Optional | For PUT pre-signed URLs — the Content-Type the uploader must use. If set, the uploader must include this value in their PUT request Content-Type header or the upload will be rejected. |
Example: upload Configuration
{
"operation": "upload",
"bucket": "bizfirstgo-documents",
"key": "invoices/{@ $var.year }/{@ $var.month }/INV-{@ $var.invoiceNumber }.pdf",
"file_data": "{@ $node.pdfGenerator.file_data }",
"content_type": "application/pdf",
"acl": "private",
"metadata": {
"customer_id": "{@ $var.customerId }",
"workflow_run_id": "{@ $workflow.runId }",
"invoice_date": "{@ $var.invoiceDate }"
},
"credential_id": "aws-s3-prod"
}
Example: getPresignedUrl Configuration
{
"operation": "getPresignedUrl",
"bucket": "bizfirstgo-documents",
"key": "invoices/{@ $var.year }/{@ $var.month }/INV-{@ $var.invoiceNumber }.pdf",
"method": "GET",
"expiry_seconds": 86400,
"credential_id": "aws-s3-prod"
}
Key naming conventions: Use structured key paths with meaningful folder segments to keep buckets organised at scale. Recommended pattern: {document_type}/{year}/{month}/{entity_id}/{filename}. This makes listing, archiving, and lifecycle policies straightforward as the volume of stored objects grows.
Never use public-read ACL for sensitive data. Business documents, customer files, contracts, and financial records must always be stored as private. Use getPresignedUrl to grant temporary, auditable access. Publicly accessible objects are permanently accessible to anyone with the URL — there is no way to revoke access after the fact.
MIME Type Reference for Common Workflow Files
| File Type | Extension | Content-Type |
|---|
| PDF Document | .pdf | application/pdf |
| JSON Data | .json | application/json |
| CSV Spreadsheet | .csv | text/csv |
| Plain Text | .txt | text/plain |
| Markdown | .md | text/markdown |
| JPEG Image | .jpg / .jpeg | image/jpeg |
| PNG Image | .png | image/png |
| ZIP Archive | .zip | application/zip |
| Excel Workbook | .xlsx | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
| Word Document | .docx | application/vnd.openxmlformats-officedocument.wordprocessingml.document |
| HTML File | .html | text/html |
| Binary / Unknown | various | application/octet-stream |
content_type and browser behaviour: Setting the correct content_type on uploaded objects is important for pre-signed URL behaviour. When a browser follows a GET pre-signed URL, S3 returns the object with the stored Content-Type header. A PDF with application/pdf will open inline in most browsers; with application/octet-stream it will force a download. Set the content type appropriate to your user experience needs.
