File Uploads and Transfers

​

1. Choose Storage Providers to Integrate

• Amazon S3 - Industry-standard object storage with robust API and scalability
• Google Drive - Consumer and enterprise file storage with sharing and collaboration capabilities
• Google Cloud Storage - Enterprise-grade object storage for any amount of data
• SFTP - Secure file transfer for legacy systems and B2B integrations

​

2. Capture Storage Configuration on Installation

• Select or create a parent folder for all uploads
• Define naming conventions for uploaded files
• Set default sharing permissions

• Bucket name
• Folder prefix/path (Key prefix)
• Access control settings

​

3. Send File Upload Events to Your Alloy Instance

{
  "event": "New File Upload",
  "userId": "6877f0a8d3a743bca19fbbf9",
  "data": {
    "fileId": "FILE_12345",
    "fileName": "Q4_Financial_Report.pdf",
    "fileUrl": "https://yourplatform.com/files/FILE_12345/download",
    "fileType": "application/pdf",
    "fileSize": 2458392,
    "uploadedBy": "john.smith@company.com",
    "uploadedAt": "2025-10-14T10:30:00Z",
    "category": "financial_reports",
    "folderId": "parent_folder_id_123",
    "metadata": {
      "quarter": "Q4",
      "year": "2025",
      "department": "Finance"
    }
  }
}

{
  "event": "Document Ready for Backup",
  "userId": "68addfecf247e957c9f302f9",
  "data": {
    "documentId": "DOC_67890",
    "documentName": "customer_contract.pdf",
    "sourceUrl": "https://api.yourplatform.com/documents/DOC_67890",
    "s3Bucket": "customer-contracts",
    "s3Key": "contracts/2025/10/customer_contract.pdf",
    "createdAt": "2025-10-14T14:22:15Z"
  }
}

​

4. Build Workflows to Upload Files to Cloud Storage

1. Receiving the Custom Event with file information
2. Optionally transforming the file name or path based on your naming conventions
3. Using the storage provider’s upload action
4. Optionally storing the resulting file ID or URL back in your platform

​

5. Build Workflows to Download Files from Cloud Storage

• Bucket: The S3 bucket name
• Key: The file path/key

• Use “Get a File” action with the file ID
• Or use “List Files” to discover files in specific folders

• File Path: Remote file path
• File Name: Name of the file to read

​

6. Handle File Organization and Naming

• Google Drive uses folder hierarchies with folder IDs
• Amazon S3 / Google Cloud Storage use bucket and key-based organization with prefixes
• SFTP uses traditional directory path structures

• Dynamic folder or key creation based on metadata (e.g., organize by date, customer, or category)
• File naming conventions that prevent conflicts
• Deduplication strategies when files with the same name already exist

​

7. Deploy the Integration

​

Video Walkthrough Library

• Bucket (required): The S3 bucket name where the file will be stored
• Key (required): The object key (path) for the file in the bucket (e.g., “uploads/2025/10/document.pdf”)
• Block Output (required): The source URL or file content to upload

• Bucket (required): The S3 bucket name
• Key (required): The object key (path) of the file to read

• Use consistent key naming conventions with prefixes for organization (e.g., “customer-id/year/month/filename”)
• Leverage S3 bucket events for real-time file detection if available
• Set appropriate lifecycle policies for cost optimization
• Use separate buckets for different security classifications or environments
• Consider using pre-signed URLs for secure temporary access

• Upload Type (required): Select the type of upload operation
• Name (required): The name of the file to be created in Google Drive
• Source File URL: The URL of the file to upload from your platform
• Folder To Upload To: The folder ID where the file should be placed
• Mime Type (optional): The MIME type of the file (e.g., “application/pdf”)
• Description (optional): File description
• Starred (optional): Whether to star the file
• Shared Drive ID (optional): For shared/team drives
• App Properties / Properties (optional): Custom key-value metadata

• List Files: Returns the files in the user’s Drive
• Get a File: Get a file by ID
• Create a Folder: Create a folder or a simple file without upload
• Delete a File: Delete a file by ID

• Use service accounts for programmatic access in production environments
• Create dedicated parent folders for each customer or workflow during installation
• Leverage Google Workspace domain sharing when applicable for team access
• Use file descriptions and custom properties for searchability and metadata
• Store folder IDs during installation to avoid repeated folder lookups

• Bucket (required): The GCS bucket name where the file will be stored
• File Name (required): The object name (path) for the file in the bucket
• Block Output (required): The source URL or file content to upload

• Use consistent object naming with prefixes for logical organization
• Set appropriate storage classes based on access patterns (Standard, Nearline, Coldline)
• Enable versioning for critical data to protect against accidental deletions
• Use lifecycle policies to automatically transition or delete objects
• Consider regional vs multi-regional buckets based on latency requirements

• Block Output (required): The source URL or file content to upload
• File Path (required): The destination directory path on the remote server
• File Name (required): The name for the file on the remote server

• File Path: The directory path where the file is located
• File Name: The name of the file to read

• Use key-based authentication over passwords for enhanced security
• Implement consistent directory structures agreed upon with partners
• Set up monitoring and alerting for connection failures
• Implement file archiving strategies (move processed files to archive directories)
• Use file naming conventions that include timestamps to avoid collisions
• Consider using scheduled workflows to poll for new files regularly