Files Task¶

Overview¶

The Files Task downloads files from URLs, organizes them into folders, and creates directory structures in your CRM's file system. Download attachments from APIs, organize client documents, archive files, or set up folder structures automatically.

When to use this task:

• Download files from external URLs
• Store files delivered as base64 content (API responses, webhook payloads, email attachments)
• Organize files into client folders
• Create directory structures automatically
• Archive documents systematically
• Save API-generated files (PDFs, reports)
• Initialize client file systems
• Manage project document organization
• Retrieve all files (and their URLs) stored for a client

Key Features:

• Four actions: download_file, save_to_directory, create_empty_folder, fetch_files
• Two file sources: a remote URL, or inline base64 content
• Azure Blob Storage integration
• Automatic folder creation
• Client association
• Custom filenames
• Nested directory support
• Bulk folder creation
• File metadata tracking
• List/fetch a client's stored files and URLs

Quick Start¶

Download File:

1. Add Files task
2. Select Action: download_file
3. Enter file URL
4. Optional: Custom filename
5. Save

Save to Directory:

1. Add Files task
2. Select Action: save_to_directory
3. Enter file URL
4. Enter client ID
5. Enter directory path
6. Save

Save Base64 Content:

1. Add Files task
2. Select Action: download_file or save_to_directory
3. Set File Source: Base64 Content
4. Paste or map the base64 into Base64 Content
5. Enter a File Name (recommended - base64 carries no filename)
6. Save

Create Folders:

1. Add Files task
2. Select Action: create_empty_folder
3. Enter client ID
4. Enter directory paths (comma-separated)
5. Save

Fetch Files from Client:

1. Add Files task
2. Select Action: fetch_files
3. Enter client ID
4. Optional: directory path (blank = client root)
5. Optional: Include Subfolders (Yes/No)
6. Save

Configuration¶

Builder fields¶

The Field column is the label as it appears in the task builder; Key is the name the value is stored under and referenced by.

File Source: URL or Base64¶

Both storing actions (download_file and save_to_directory) read the file from one of two sources, chosen with the File Source dropdown:

Tasks created before base64 support keep working unchanged - they default to File URL.

Base64 Content accepts:

• A bare base64 string: JVBERi0xLjQKJc...
• A data URI: data:application/pdf;base64,JVBERi0xLjQKJc...
• Base64url (- and _ in place of + and /)
• Wrapped base64 - line breaks and whitespace are ignored
• Base64 with the trailing = padding stripped

Maximum decoded size is 50MB, the same limit that applies to URL downloads. Content that is not valid base64 fails the task with an explicit error rather than storing a corrupt file.

File type and name:

• A data URI's MIME type is used when present.
• Otherwise the type is detected from the content's magic bytes (PDF, PNG, JPEG, GIF, ZIP/DOCX/XLSX, MP3, OGG), falling back to application/octet-stream.
• Base64 carries no filename, so set File Name. Without one the file is stored as file-<timestamp>.<detected extension>.

Action: save_to_directory
File Source: Base64 Content
Base64 Content: {{task_18001_response.document_base64}}
File Name: invoice-{{task_15001_company_name}}.pdf
Client ID: {{task_15001_client_id}}
Directory: Invoices/2024

Action: download_file¶

Download file to storage without folder organization:

Action: download_file
File URL: https://example.com/document.pdf
Custom Filename: contract-2024 (optional, preserves extension)

Output:

• File uploaded to Azure Blob Storage
• Returns URL, name, size, content type, database ID
• No client association or folder structure

Action: save_to_directory¶

Download and organize into client folder:

Action: save_to_directory
File URL: {{task_36001_pdf_url}}
Client ID: {{task_15001_client_id}}
Directory: Contracts/2024/Q1
Custom Filename: agreement-{{task_15001_company_name}}

How it works:

1. Validates client ID belongs to account
2. Creates nested folders if they don't exist
3. Downloads file from URL
4. Uploads to Azure in specified directory
5. Links file to client record

Directory Format:

• Use forward slashes: Folder/Subfolder/File
• Leading/trailing slashes removed automatically
• Creates full path recursively

Action: create_empty_folder¶

Create folder structure without files:

Action: create_empty_folder
Client ID: {{task_13001_client_id}}
Directories: Documents, Invoices, Reports, Contracts/2024, Contracts/2025

Features:

• Comma-separated list
• Creates nested paths
• Bulk creation
• Returns folder IDs and paths
• Reports success/failure counts

Action: fetch_files¶

Retrieve the files (and URLs) stored for a client:

Action: fetch_files
Client ID: {{task_15001_client_id}}
Directory: Contracts/2024        (optional — blank = client root)
Include Subfolders: Yes          (default Yes)

How it works:

1. Validates client ID belongs to account
2. Resolves the directory path to an existing folder (nothing is created)
3. Collects matching files from client_uploads
4. Returns a files array of metadata (each entry includes the file URL)

Scope rules (a blank directory is treated as the client's root):

• Blank directory + Include Subfolders = Yes → every file for the client (root + all nested folders)
• Blank directory + Include Subfolders = No → only files at the client's root
• Directory + Include Subfolders = Yes → files in that folder and all nested subfolders
• Directory + Include Subfolders = No → files directly in that folder only
• Directory not found → succeeds with an empty result (file_count = 0), not an error

Email attachment files are excluded, matching the client portal file listing.

Output Fields¶

download_file Output¶

save_to_directory Output¶

Same as download_file, plus implicit folder linking.

create_empty_folder Output¶

fetch_files Output¶

Reference individual files with dot/index notation, e.g. {{task_39001_files.0.file_url}}, or loop over {{task_39001_files}} with a Loop task and use {{...item.file_url}}.

Real-World Examples¶

Store an attachment against the client who sent it¶

Email Trigger
  └─ Match to Client   contact_email: {{task_54001_from_email}}
      └─ Files         download {{task_54001_attachment_urls}} into the client's folder

Keep a generated document¶

Webhook In
  └─ PDF        generate the document
      └─ Files  save {{task_36001_document_url}} into a folder

Set up a folder structure for a new client¶

CRM Trigger  (client created)
  └─ Files   create the standard folders

Best Practices¶

Base64 Content¶

1. Always set File Name - base64 has no filename of its own, and the extension drives the stored content type
2. Map, don't paste - reference the producing task ({{task_18001_response.file_base64}}) rather than pasting a large literal into the config
3. Strip any JSON escaping - the value must be the raw base64 string, not a quoted/escaped one
4. Watch the 50MB decoded limit - base64 is ~33% larger than the file it encodes
5. Prefer a URL when you have one - it avoids carrying the whole payload through the workflow

File URLs¶

1. Use https only - http not supported
2. Validate URL format - Must be proper URL
3. Check file availability - Ensure URL is accessible
4. Handle timeouts - Use webhook retries if needed
5. Secure URLs - Use signed/expiring URLs when possible

Directory Structure¶

# Good structure
/Invoices/2024/Q1
/Documents/Contracts/Active
/Reports/Monthly/2024

# Avoid
//Invoices//2024  (double slashes)
Invoices/2024/    (trailing slash - auto-removed)
/Invoices/../2024 (relative paths)

Filename Conventions¶

1. No special characters - Automatically sanitized
2. Include dates - For sorting: 2024-02-08-report.pdf
3. Use descriptive names - client-proposal.pdf not doc.pdf
4. Preserve extensions - Custom name inherits extension
5. Avoid spaces - Use hyphens or underscores

Performance¶

1. Batch folder creation - Use comma-separated list
2. Check existing folders - Avoid recreating
3. Monitor storage limits - Azure quotas apply
4. Archive old files - Regular cleanup
5. Use async webhooks - For large files

Troubleshooting¶

File Download Failed¶

Issue: Cannot download from URL

Causes:

• Invalid URL format
• URL not accessible (404, 403)
• Non-http/https protocol
• Network timeout
• File too large

Solution:

# Verify URL
Code Task: return {url_debug: input.task_X001_url};

# Check URL is accessible
Test in browser first

# Ensure https
URL must be https://example.com/file.pdf

Base64 Decode Failed¶

Issue: Task fails with "Content is not valid base64." or "No base64 content provided."

Causes:

• The mapped variable resolved to empty (upstream task returned nothing)
• The value still carries JSON escaping or surrounding quotes
• The value is a data URI that is not base64 encoded (e.g. data:text/plain,hello)
• Decoded content exceeds 50MB

Solution:

# Confirm what the variable actually resolves to
Code Task: return {len: (input.task_18001_file_base64 || '').length};

# Strip quotes/escaping upstream if the producer returned a JSON string

# For very large files, have the producing system return a URL instead

Invalid Client ID¶

Issue: Client ID not found or access denied

Cause: Client doesn't exist or belongs to different account

Solution:

• Verify client ID exists
• Check belongs to same owner_id as workflow
• Use Match to Client task first

Directory Creation Failed¶

Issue: Folders not created

Causes:

• Invalid client ID
• Permission issues
• Database errors
• Path format issues

Solution:

# Verify client
If Task: {{task_15001_client_id}} is not empty

# Check path format
Remove leading/trailing slashes
Use forward slashes only

Filename Issues¶

Issue: File saved with wrong name

Causes:

• Extension not preserved
• Special characters removed
• Sanitization changed name

Solution:

• Custom filename inherits original extension automatically
• Avoid special characters
• Check task_39001_file_name output

Frequently Asked Questions¶

What file types are supported?¶

All file types. Common: PDF, DOCX, XLSX, PNG, JPG, CSV, TXT, etc.

What's the maximum file size?¶

Limited by Azure Blob Storage and timeout settings. Test with large files (>100MB) carefully.

Can I upload from local filesystem?¶

No, must be accessible via http/https URL. Use other methods for local uploads.

Are folders shared across clients?¶

No, each client has isolated folder structure.

Can I move files between folders?¶

Not directly. Would need to download and re-upload via Code task or manual process.

Can I delete files?¶

Not via this task. Deletion requires manual process or custom API integration.

Can I list files in a folder?¶

Yes. Use the fetch_files action with a Client ID and (optionally) a Directory. It returns a files metadata array (each entry includes the file URL). Leave the Directory blank to target the client's root — with Include Subfolders = Yes that returns every file for the client.

How do I handle duplicate filenames?¶

Azure may overwrite or version automatically depending on configuration. Use unique filenames.

Related Tasks¶

• PDF - Generate PDFs to download
• Webhook Out - Fetch file URLs from APIs
• Match to Client - Get client ID for organization
• Loop - Process multiple files
• Variable - Store file IDs and URLs
• Email - Send file links to users