List Files

Lists all files and folders in a specified Dropbox directory.

Common Properties

• Name - The custom name of the node.
• Color - The custom color of the node.
• Delay Before (sec) - Waits in seconds before executing the node.
• Delay After (sec) - Waits in seconds after executing node.
• Continue On Error - Automation will continue regardless of any error. The default value is false.

info

If the ContinueOnError property is true, no error is caught when the project is executed, even if a Catch node is used.

Inputs

• Client ID - The client identifier returned from the Connect node.
• Dropbox Path - Path to the directory to list (without leading slash, empty for root).

Output

• Files - An array of file and folder objects, each containing:
  • is_dir (boolean): Whether the item is a directory
  • name (string): Name of the file or folder
  • size (integer): Size in bytes (0 for folders)
  • mod_time (timestamp): Last modification time

How It Works

The List Files node retrieves a listing of all files and folders in a specified Dropbox directory. When executed, the node:

1. Validates the required inputs (Client ID and Dropbox Path)
2. Retrieves the access token using the provided Client ID
3. If the path is empty, uses "/" for the root directory
4. Otherwise, prepends "/" to the provided path
5. Queries the Dropbox API for the directory listing
6. Returns an array of file and folder information objects

Path Format

• Paths should be provided without a leading slash
• Empty path lists the root directory
• The node automatically adds the leading "/" for Dropbox API compatibility
• Examples:
  • Input: `` (empty) → API uses: / (root)
  • Input: documents → API uses: /documents
  • Input: projects/2024 → API uses: /projects/2024

Requirements

• A valid Dropbox connection (using the Connect node)
• The directory must exist in Dropbox
• Read permissions for the specified directory

Error Handling

The node will return specific errors in the following cases:

• Empty or invalid Client ID
• Directory does not exist
• Insufficient permissions to access the directory
• Path points to a file instead of a directory
• Dropbox API errors

Usage Notes

• Returns an array of objects, even if the directory is empty
• Both files and folders are included in the results
• Use the is_dir property to distinguish between files and folders
• The listing is not recursive - only direct children are returned
• Results are returned in the order provided by Dropbox API
• Large directories are fully loaded (no pagination in current implementation)

Output Structure

The files output is an array of objects:

[
  {
    "is_dir": false,
    "name": "report.pdf",
    "size": 2457600,
    "mod_time": "2024-03-15T14:30:00Z"
  },
  {
    "is_dir": true,
    "name": "subfolder",
    "size": 0,
    "mod_time": "2024-03-10T09:00:00Z"
  },
  {
    "is_dir": false,
    "name": "data.csv",
    "size": 153600,
    "mod_time": "2024-03-14T11:20:00Z"
  }
]

Example 1: List Root Directory

List all files and folders in the root of your Dropbox:

Inputs:

• Client ID: (from Connect node)
• Dropbox Path: `` (empty)

Output (files): Array of all files and folders in the root directory

Example 2: List Specific Folder

List contents of a specific folder:

Inputs:

• Client ID: (from Connect node)
• Dropbox Path: documents/2024

Output (files): Array of all files and folders in /documents/2024

Example 3: Filter Files Only

Get only files (not folders) from a directory:

ListFiles
  ↓
Loop through files array
  ├─ If item.is_dir is false
  │   └─ Add to files_only array
  └─ Continue
  ↓
Process files_only array

Example 4: Find Files by Extension

Find all PDF files in a directory:

ListFiles (path: documents)
  ↓
Loop through files array
  ├─ If item.name ends with ".pdf"
  │   └─ Add to pdf_files array
  └─ Continue
  ↓
Process pdf_files array

Example 5: Sort by Size

Sort files by size (largest first):

ListFiles
  ↓
Sort files array by size (descending)
  ↓
Loop through sorted files
  └─ Process each file

Example 6: Process Files Modified Recently

Find and process files modified in the last 7 days:

Set cutoff_date = current_date - 7 days
  ↓
ListFiles
  ↓
Loop through files array
  ├─ If item.mod_time > cutoff_date
  │   └─ Process recent file
  └─ Continue

Common Use Cases

• Inventorying files in a directory
• Finding files matching specific criteria
• Batch processing files in a folder
• Monitoring folder contents for changes
• Creating file indexes or catalogs
• Implementing file search functionality
• Auditing folder structures
• Generating reports on folder contents
• Synchronization workflows
• Automated file organization

Best Practices

• Check if the directory exists before listing (use FileStat)
• Handle empty directories gracefully
• Use the is_dir property to separate files from folders
• Implement filtering logic to process only relevant files
• Consider pagination for very large directories
• Log the number of files found for monitoring
• Use error handling for permission issues
• Cache results if listing the same directory multiple times

Working with the Files Array

Access individual files in the array:

ListFiles → files
  ↓
Set first_file = files[0]
  ↓
Log "First file: {first_file.name}"

Loop through all files:

ListFiles → files
  ↓
For each file in files
  ├─ Log "Name: {file.name}, Size: {file.size}"
  └─ Process file

Count files:

ListFiles → files
  ↓
Set file_count = files.length
  ↓
Log "Found {file_count} items"

Filtering Examples

Files only:

files.filter(item => !item.is_dir)

Folders only:

files.filter(item => item.is_dir)

Large files (over 1MB):

files.filter(item => item.size > 1048576)

PDF files:

files.filter(item => item.name.endsWith('.pdf'))

Files modified this year:

files.filter(item => new Date(item.mod_time).getFullYear() === 2024)

Pattern: Batch Download

Download all files from a folder:

ListFiles
  ↓
Loop through files array
  ├─ If item.is_dir is false
  │   ├─ Set remote_path = folder_path + "/" + item.name
  │   ├─ Set local_path = "./downloads/" + item.name
  │   └─ DownloadFile (remote_path, local_path)
  └─ Continue

Pattern: Recursive Listing

List files in subdirectories recursively:

Function ListRecursive(path)
  ├─ ListFiles (path)
  ├─ For each item in files
  │   ├─ If item.is_dir is true
  │   │   └─ ListRecursive(path + "/" + item.name)
  │   └─ Else
  │       └─ Process file
  └─ Return

Pattern: Clean Old Files

Delete files older than 90 days:

Set cutoff_date = current_date - 90 days
  ↓
ListFiles
  ↓
Loop through files array
  ├─ If item.is_dir is false AND item.mod_time < cutoff_date
  │   ├─ Set file_path = folder_path + "/" + item.name
  │   └─ DeleteFile (file_path)
  └─ Continue

Pattern: Generate File Report

Create a CSV report of all files:

ListFiles
  ↓
Set report = "Name,Size,Modified,Type\n"
  ↓
Loop through files array
  ├─ Set type = item.is_dir ? "Folder" : "File"
  ├─ Set line = item.name + "," + item.size + "," + item.mod_time + "," + type
  ├─ Append line to report
  └─ Continue
  ↓
Save report to CSV file

Tips

• Use ListFiles as the starting point for batch operations
• Combine with FileStat for detailed information on specific files
• Implement sorting and filtering to process files in the right order
• Consider rate limits when processing large numbers of files
• Use descriptive variable names when looping through results
• Log progress when processing many files
• Implement error handling for individual file operations in loops

Performance Considerations

• Large directories may take time to list
• Consider filtering on the client side after receiving results
• For very large directories, consider implementing pagination logic
• Network latency affects listing speed
• Caching results can improve performance for repeated operations

Error Recovery

If listing fails:

• Verify the directory exists using FileStat
• Check path spelling and format
• Ensure you have read permissions
• Verify the path points to a directory, not a file
• Check Dropbox API status and rate limits

Integration with Other Nodes

ListFiles works well with:

• Loop nodes: Process each file in the list
• Filter nodes: Select specific files based on criteria
• DownloadFile: Batch download files
• DeleteFile: Clean up old or unwanted files
• FileStat: Get detailed info on specific files
• CopyFile/MoveFile: Organize files based on properties