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
• 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
• 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

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¶

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¶

Example 1: PDF Invoice Download and Organization¶

Scenario: Generate invoice PDF, download, and organize by year/month

Workflow:

1. CRM Trigger - Invoice finalized
2. PDF - Generate invoice PDF
3. Files - Save to organized folder
4. Email - Send invoice with link
5. MySQL Query - Log file storage

Save Invoice:

Action: save_to_directory
File URL: {{task_36001_pdf_url}}
Client ID: {{task_47001_client_id}}
Directory: Invoices/{{task_47001_year}}/{{task_47001_month}}
Custom Filename: INV-{{task_47001_invoice_number}}

Example Directory:

/Invoices/2024/January/INV-00123.pdf
/Invoices/2024/January/INV-00124.pdf
/Invoices/2024/February/INV-00125.pdf

Email Invoice:

To: {{task_47001_email}}
Subject: Invoice {{task_47001_invoice_number}}

Your invoice is ready.

Invoice Number: {{task_47001_invoice_number}}
Amount Due: ${{task_47001_total}}
Due Date: {{task_47001_due_date}}

[Download Invoice: {{task_39001_file_url}}]

Or view in your client portal:
https://portal.company.com/invoices/{{task_39001_file_id}}

Log Storage:

INSERT INTO invoice_files
(invoice_id, file_id, file_url, stored_at)
VALUES ({{task_47001_invoice_id}},
        {{task_39001_file_id}},
        '{{task_39001_file_url}}',
        NOW())

Example 2: Client Onboarding File System¶

Scenario: Create standardized folder structure for new clients

Workflow:

1. CRM Trigger - New client created
2. Files - Create folder structure
3. Email - Welcome email with portal access
4. Workflow Note - Onboarding task

Create Folder Structure:

Action: create_empty_folder
Client ID: {{task_47001_client_id}}
Directories: Documents, Documents/Contracts, Documents/Proposals, Documents/Agreements, Invoices, Invoices/2024, Reports, Reports/Monthly, Reports/Quarterly, Communications, Communications/Emails, Communications/Meetings, Projects

Created Structure:

/Documents
  /Contracts
  /Proposals
  /Agreements
/Invoices
  /2024
/Reports
  /Monthly
  /Quarterly
/Communications
  /Emails
  /Meetings
/Projects

Welcome Email:

To: {{task_47001_email}}
Subject: Welcome to {{company_name}}!

Hi {{task_47001_first_name}},

Your account is ready! We've set up your document portal with organized folders:

✓ {{task_39001_success_count}} folders created
✓ Document management system ready
✓ Secure file storage enabled

Access your portal:
https://portal.company.com/login

Folder Structure:
{{task_39001_directory_paths}}

[Login to Portal]

Example 3: Email Attachment Archiving¶

Scenario: Download and archive email attachments systematically

Workflow:

1. Email Trigger - Email with attachments
2. Match to Client - Find sender
3. Loop - For each attachment
4. Files - Download and organize
5. MySQL Query - Log attachments

Download Attachments:

Loop through: {{task_2001_attachments}}

Action: save_to_directory
File URL: {{task_29001_item.url}}
Client ID: {{task_15001_client_id}}
Directory: Emails/{{task_2001_year}}/{{task_2001_month}}/Attachments
Custom Filename: {{task_2001_email_id}}-{{task_29001_item.name}}

Example:

/Emails/2024/February/Attachments/
  email-12345-proposal.pdf
  email-12345-pricing.xlsx
  email-12346-contract.pdf

Log Attachments:

INSERT INTO email_attachments
(email_id, client_id, attachment_name, file_id, file_url, archived_at)
VALUES ({{task_2001_email_id}},
        {{task_15001_client_id}},
        '{{task_29001_item.name}}',
        {{task_39001_file_id}},
        '{{task_39001_file_url}}',
        NOW())

Example 4: API-Generated Report Storage¶

Scenario: Download reports from external API and organize by client

Workflow:

1. Timer Trigger - Monthly report generation
2. MySQL Query - Get active clients
3. Loop - For each client
4. Webhook Out - Request report from API
5. Files - Download and save report
6. Email - Notify client

Request Report:

URL: https://api.reporting-service.com/generate
Method: POST

Body:
{
  "client_id": "{{task_29001_row.client_id}}",
  "report_type": "monthly_summary",
  "period": "{{current_month}}",
  "format": "pdf"
}

Response includes: report_url

Download Report:

Action: save_to_directory
File URL: {{task_18001_response.report_url}}
Client ID: {{task_29001_row.client_id}}
Directory: Reports/{{task_48001_year}}/Monthly
Custom Filename: Monthly-Report-{{task_48001_month}}

Notify Client:

To: {{task_29001_row.email}}
Subject: Your {{task_48001_month}} Report is Ready

Hi {{task_29001_row.first_name}},

Your monthly report for {{task_48001_month}} is now available.

Report Details:
- Period: {{task_48001_month}} {{task_48001_year}}
- Generated: {{current_timestamp}}
- File Size: {{task_39001_file_size / 1024}} KB

[Download Report: {{task_39001_file_url}}]

Or view in your dashboard:
https://portal.company.com/reports/{{task_39001_file_id}}

Best regards,
{{company_name}}

Example 5: Contract Document Workflow¶

Scenario: Download signed contract from e-signature platform and archive

Workflow:

1. Webhook In - DocuSign/HelloSign webhook
2. Match to Client - Find client
3. Files - Create Contracts folder if needed
4. Files - Download signed contract
5. Edit Client - Update contract status
6. Workflow Note - Create follow-up task
7. Email - Confirmation to client

Create Contract Folder:

Action: create_empty_folder
Client ID: {{task_15001_client_id}}
Directories: Contracts/{{task_46001_contract_year}}, Contracts/Signed, Contracts/Pending

Download Contract:

Action: save_to_directory
File URL: {{task_46001_signed_document_url}}
Client ID: {{task_15001_client_id}}
Directory: Contracts/{{task_46001_contract_year}}
Custom Filename: {{task_46001_contract_type}}-Signed-{{task_46001_signed_date}}

Update Client:

Client ID: {{task_15001_client_id}}
Custom Field - contract_status: Signed
Custom Field - contract_file_id: {{task_39002_file_id}}
Custom Field - contract_signed_date: {{task_46001_signed_date}}

Follow-Up Task:

Type: To-Do
Client ID: {{task_15001_client_id}}
Due: tomorrow
Priority: High
User Tags: contracts-team@company.com

Note: Contract Signed - Process Next Steps

Client: {{task_15001_company_name}}
Contract Type: {{task_46001_contract_type}}
Signed Date: {{task_46001_signed_date}}

Contract stored: {{task_39002_file_url}}
File ID: {{task_39002_file_id}}

Next steps:
1. Review signed contract
2. Activate account
3. Send welcome package
4. Schedule kickoff call

[View Contract]

Confirmation Email:

To: {{task_15001_email}}
Subject: Contract Signed - Welcome to {{company_name}}!

Hi {{task_15001_first_name}},

Thank you for signing the contract!

Contract Details:
- Type: {{task_46001_contract_type}}
- Signed: {{task_46001_signed_date}}
- File: {{task_39002_file_name}}

Your signed contract is securely stored and accessible anytime in your client portal.

[View Contract: {{task_39002_file_url}}]

What's next:
- Account activation (24-48 hours)
- Welcome package sent
- Kickoff call scheduled

Welcome aboard!

Best Practices¶

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

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
• MySQL Query - Track file metadata