S3 — folder/get-many

S3 Folder Model: S3 has no native folders — folders are key prefixes. folder/get-many lists all objects whose keys begin with the specified folderPath prefix. The folderPath should end with / to scope results to the intended directory level (e.g. reports/2026/) and avoid accidentally matching sibling prefixes.

When to Use

Tenant folder inspection: List all files in a tenant's dedicated folder for administrative review or usage reporting.
Pre-deletion empty check: Verify a folder is empty before attempting bucket/delete or folder/delete to prevent unexpected failures.
Navigation UI support: Enumerate the contents of a folder prefix to populate a file browser or document picker interface within an admin application.
Sub-folder enumeration: List entries within a specific level of the folder hierarchy to identify sub-folders (common prefixes) for navigation or processing.
Upload completeness check: After a bulk upload, list the target folder to confirm all expected files are present before proceeding.

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 bucket.

Operation Fields

Field	Required	Description
`bucketName`	Required	Name of the S3 bucket containing the folder.
`folderPath`	Required	Folder prefix to list. Should end with `/` (e.g. `tenants/t1024/documents/`). Omitting the trailing slash may return sibling objects.
`continuationToken`	Optional	Pagination token from the previous call's `nextContinuationToken`. Omit for the first page.

Sample Configuration

{
  "connection": {
    "accessKeyId": "{{ $credentials.s3_prod.accessKeyId }}",
    "secretKey": "{{ $credentials.s3_prod.secretKey }}",
    "region": "us-east-1"
  },
  "operation": {
    "resource": "folder",
    "action": "getMany",
    "bucketName": "acme-tenant-storage",
    "folderPath": "tenants/{{ $node.TenantContext.output.tenantId }}/documents/",
    "continuationToken": "{{ $node.PreviousPage.output.nextContinuationToken }}"
  }
}

Validation Errors

Error Code	Cause & Resolution
`NoSuchBucket`	The specified bucket does not exist. Verify the bucket name and region settings.
`AccessDenied`	The IAM identity lacks `s3:ListBucket` on the target bucket. Update the IAM policy to include this permission scoped to the bucket ARN.
`InvalidToken`	The `continuationToken` is invalid or expired. Restart pagination from the first page (omit the token).

Output

Success Port

Field	Type	Description
`status`	string	`success` on successful listing (returns success even if the folder is empty).
`errorCode`	string	Empty string on success.
`bucketName`	string	The bucket that was listed.
`folderPath`	string	The folder prefix that was listed.
`entryCount`	int	Number of objects found under this prefix on this page. Returns `0` for empty folders.
`nextContinuationToken`	string	Token for the next page. Empty string if this is the last page or the folder has fewer entries than the page size.

Error Port

On failure, activates with errorCode, errorMessage, and httpStatusCode. A successful call with entryCount: 0 indicates the folder is empty — this routes through the success port, not the error port.

Sample Output

{
  "status": "success",
  "errorCode": "",
  "bucketName": "acme-tenant-storage",
  "folderPath": "tenants/t1024/documents/",
  "entryCount": 23,
  "nextContinuationToken": ""
}

Expression Reference

Expression	Result
`{{ $node.ListFolder.output.entryCount }}`	Number of entries in the folder — check for 0 to detect empty folder before deletion.
`{{ $node.ListFolder.output.nextContinuationToken }}`	Pass to next `folder/get-many` call for pagination. Empty string signals the last page.
`{{ $node.ListFolder.output.folderPath }}`	Confirm the folder path that was listed in log entries or UI responses.
`{{ $node.ListFolder.output.bucketName }}`	Confirm the target bucket in audit log or response payloads.

Node Policies & GuardRails

Policy Area	Recommendation
Credential Storage	Store credentials in BizFirst Credentials Manager. Never hardcode.
IAM Permissions	Grant `s3:ListBucket` on the target bucket ARN. Use `s3:prefix` IAM condition to restrict listing to specific folder prefixes if needed.
Trailing Slash	Always include a trailing `/` in `folderPath` to scope the listing to the intended directory level and avoid matching sibling key prefixes.
Empty Folder Handling	An empty folder returns `entryCount: 0` via the success port. Use an If Condition downstream to branch on `entryCount == 0` for pre-deletion checks.
Pagination Completeness	For folders with many objects, check `nextContinuationToken` and loop to retrieve all pages before making deletion or processing decisions.
Sensitive Path Exposure	Folder paths may expose tenant IDs or internal structure. Do not include `folderPath` in externally visible notifications or logs without sanitization.
Pre-Deletion Check Pattern	Use `folder/get-many` with `entryCount == 0` as a safety gate before `bucket/delete` to confirm the bucket is empty when `verifyEmpty` is bypassed.

Examples

Example 1: Pre-Deletion Empty Verification

Before deleting a tenant's storage bucket, verify all folder contents have been cleared.

// Node: CheckTenantFolderEmpty (S3 — folder/get-many)
{
  "bucketName": "acme-shared-storage",
  "folderPath": "tenants/{{ $node.OffboardRequest.output.tenantId }}/"
}
// Node: VerifyEmpty (If Condition)
// Condition: entryCount == 0
// True: proceed to bucket/delete
// False: alert operations team — folder not empty, manual review required

Example 2: Admin File Browser API

An admin portal requests a paginated list of files in a tenant's folder for display in a document management UI.

// Node: ListTenantFiles (S3 — folder/get-many)
{
  "bucketName": "acme-tenant-docs",
  "folderPath": "tenants/{{ $node.Request.output.tenantId }}/{{ $node.Request.output.subfolder }}/",
  "continuationToken": "{{ $node.Request.output.pageToken }}"
}
// Response:
// { entries: entryCount, nextPageToken: nextContinuationToken }
// Return as API response to admin portal

Example 3: Upload Verification Before Processing

After a client completes a bulk document upload, verify all expected files are present in the upload folder before triggering the review workflow.

// Node: VerifyUploads (S3 — folder/get-many)
{
  "bucketName": "acme-client-uploads",
  "folderPath": "submissions/{{ $node.ClientSubmission.output.submissionId }}/"
}
// Node: CheckCount (If Condition)
// entryCount >= $node.ClientSubmission.output.expectedFileCount
// True: TriggerReviewWorkflow
// False: NotifyClient("Upload incomplete — expected N files, found M")

folder/get-many FormID 20511

When to Use

Configuration

Connection

Operation Fields

Sample Configuration

Validation Errors

Output

Success Port

Error Port

Sample Output

Expression Reference

Node Policies & GuardRails

Examples

Example 1: Pre-Deletion Empty Verification

Example 2: Admin File Browser API

Example 3: Upload Verification Before Processing