Dropbox

1. Overview

Dropbox is a leading cloud storage service that offers file synchronization, personal cloud, and client software. It allows users to store files on remote servers and access them from various devices.

The GoInsight Dropbox node enables you to seamlessly integrate file and folder management into your automated workflows. It provides a comprehensive set of operations to interact with your Dropbox account, including:

• Folder Management: Create new folders at specific locations within your Dropbox.
• Content Listing: List the contents of any folder, with options for recursive searches and including deleted items.
• File and Folder Operations: Perform essential management tasks such as copying, moving, and deleting items in batches.
• Querying: Search for files within a specified folder.

2. Prerequisites

Before using this node, you need to have a valid Dropbox account. Depending on the operations you wish to perform, you may also need appropriate permissions for the files and folders you intend to access or modify.

3. Credentials

For a detailed guide on how to obtain and configure credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This node primarily operates on resources such as Folder and Item within Dropbox.

Operation Details

Create Folder

Creates a new folder in Dropbox at the specified path. If the folder already exists, the behavior depends on the AutoRename parameter: when false (default), an error is returned; when true, the folder is automatically renamed (e.g., '/MyFolder' becomes '/MyFolder (1)'). This action is idempotent when AutoRename is false - you can safely retry failed requests without creating duplicates.

Input Parameters:

• Path: The full path where the folder will be created in Dropbox. Must start with "/" and cannot end with "/". Maximum length: 260 characters. Example: "/Projects/2024/Q1" or "/Team Shared/Marketing"

Options:

• AutoRename: If true, Dropbox will automatically rename the folder if a conflict occurs (e.g., '/MyFolder' becomes '/MyFolder (1)'). If false, returns an error when the folder already exists. Set to false for idempotent operations where you want to know if the folder was newly created or already existed. Default: false.

Output:

• FolderMetadata (object): Complete folder metadata object returned by Dropbox API. Empty object {} if creation failed. Contains the following fields: Core Fields: name (string), id (string), path_lower (string), path_display (string). Sharing Fields: shared_folder_id (string), sharing_info (object).
• OriginalStatusCode (number): The original HTTP status code returned by the Dropbox API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

List a Folder

Lists files/folders in a Dropbox folder with optional recursive traversal. Basic Usage: Provide folder path (empty string for root); set Recursive=true for all subfolders. Pagination: Check HasMore; if true, use Cursor with list_folder/continue API for next page. Output: Entries array contains file/folder metadata (name, path, size, timestamps). Limit: 1-2000 items per request (default 100).

Input Parameters:

• Path: Folder path to list contents from. Must start with '/' or be empty for root. Format: Root folder: "" (empty string) or /, Subfolder: /Work/Projects.

Options:

• Recursive: Whether to list the contents of all subfolders recursively. The default value is false.
• IncludeDeleted: Whether the results will include entries for files and folders that used to exist but were deleted. The default for this field is False.
• IncludeHasExplicitSharedMembers: Whether the results will include a flag for each file indicating whether or not that file has any explicit members. The default for this field is False.
• IncludeMountedFolders: Whether the results will include entries under mounted folders which includes app folder, shared folder and team folder. The default for this field is True.
• IncludeNonDownloadableFiles: Whether to include files that are not downloadable, i.e. Google Docs. The default for this field is True.
• Limit: Maximum number of entries to return per request (1-2000). Default: 1000. Use pagination (Cursor + HasMore) for folders with more items.

Output:

• Entries (object-array): Array of file/folder metadata objects. Each entry contains: .tag (file/folder/deleted), name, path_display, id, size (files only), and timestamps. Empty array if folder is empty or error occurred.
• Cursor (string): Pagination cursor for fetching the next page of results. Use this with list_folder/continue API when HasMore=true. Empty string if no more results or error occurred.
• HasMore (bool): Boolean indicating whether more entries exist beyond the current page. true=use Cursor to fetch next page, false=all entries returned.
• OriginalStatusCode (number): The original HTTP status code from Dropbox API. Default 0 means request did not reach upstream (e.g., parameter validation failed). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors like path not found), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if operation succeeded. Common errors: 'path/not_found', 'path/malformed', 'insufficient_permissions'.

Copy Item

Batch copy files in Dropbox. Usage: Provide source file paths (newline-separated) in FromItems; specify destination file path in ToItem. When copying multiple files, they will all be copied to the same destination path. Options: AutoRename=true handles naming conflicts; AllowSharedFolder=true enables copying files from shared folders. Requirements: Destination parent folder must exist (use Create_Folder first if needed). Output: Check AllCopied (bool) for success; review FailedItems array for failures.

Input Parameters:

• FromItems: Source file paths to copy, separated by newlines. Each path must start with '/' and should be the complete file path you want to copy. ⚠️ Important: Only file paths are supported. Using folder paths will result in an error.
• ToItem: Destination file path where the source file will be copied to. Must start with '/' and must include the target filename. Important: This is a complete file path (folder + filename), not just a folder path.

Options:

• AutoRename: If true, Dropbox will automatically rename files if conflicts occur at the destination (e.g., 'file.txt' becomes 'file (1).txt'). If false, returns an error when a file with the same name already exists at the destination. Default: false.
• AllowSharedFolder: If true, allows copying items in shared folders. If false, returns an error when trying to copy files from shared folders. Most users should keep this false unless specifically copying files from shared folders. Default: false.

Output:

• AllCopied (bool): Boolean indicating whether all items were successfully copied. true = all succeeded, false = at least one failed (check FailedItems for details).
• FailedItems (object-array): Array of objects containing details about failed copy operations. Each object includes: FromItem, ToItem, OriginalStatusCode, ErrorMessage. Empty array if all items copied successfully.
• OriginalStatusCode (number): The original HTTP status code from the first API call. Default 0 means the request did not reach upstream (e.g., parameter validation failed). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded. For batch operations, this contains general errors; individual item errors are in FailedItems.

Delete Item

⚠️ CRITICAL: PERMANENT DELETION - NO RECOVERY Permanently deletes files/folders. Items do NOT go to trash and CANNOT be recovered. USE WITH EXTREME CAUTION. Behavior: Files deleted immediately; folders deleted with ALL contents. Best Practices: ✅ Verify paths ✅ Maintain backups ❌ Never use untrusted input. Output: AllDeleted (bool) for success; FailedItems for failures.

Input Parameters:

• DeleteItems: ⚠️ CAUTION: File/folder paths to PERMANENTLY delete, separated by newlines. Each path must start with '/'. Deleted items CANNOT be recovered. Double-check paths before executing.

Output:

• AllDeleted (bool): Boolean indicating whether all items were successfully deleted. true = all deleted, false = at least one failed (check FailedItems for details).
• FailedItems (object-array): Array of objects containing details about failed delete operations. Each object includes: FileItem, OriginalStatusCode, ErrorMessage. Empty array if all items deleted successfully.
• OriginalStatusCode (number): The original HTTP status code from the first API call. Default 0 means the request did not reach upstream (e.g., parameter validation failed). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded. For batch operations, this contains general errors; individual item errors are in FailedItems.

Move Item

Batch move files to a destination file path in Dropbox. Usage: Provide source file paths (newline-separated) in FromItems; specify destination file path in ToItem. When moving multiple files, they will all be moved to the same destination path. Options: AutoRename=true handles naming conflicts; AllowSharedFolder=true enables moving files from shared folders; AllowOwnershipTransfer=true allows cross-team moves. Output: Check AllMoved (bool) for success; review FailedItems array for failures.

Input Parameters:

• FromItems: Source file paths to move, separated by newlines. Each path must start with '/' and should be the complete file path you want to move. ⚠️ Important: Only file paths are supported. Using folder paths will result in an error.
• ToItem: Destination file path where the source file will be moved to. Must start with '/' and must include the target filename. Important: This is a complete file path (folder + filename), not just a folder path.

Options:

• AutoRename: If true, automatically rename the file if a file with the same name already exists at the destination (e.g., 'file.txt' becomes 'file (1).txt'). If false (default), the operation fails with a conflict error when a name collision occurs.
• AllowSharedFolder: If true, allows moving items in shared folders. If false (default), the operation may fail for files in shared folders. Keep this false unless you need to move files from shared folders.
• AllowOwnershipTransfer: If true, allows transferring ownership when moving files across different team folders. If false (default), such moves will fail. Only relevant for team accounts with shared folders.

Output:

• AllMoved (bool): Boolean indicating whether all items were successfully moved. true = all moved, false = at least one failed (check FailedItems for details).
• FailedItems (object-array): Array of objects containing details about failed move operations. Each object includes: FromItem, ToItem, OriginalStatusCode, ErrorMessage. Empty array if all items moved successfully.
• OriginalStatusCode (number): The original HTTP status code from the first API call. Default 0 means the request did not reach upstream (e.g., parameter validation failed). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded. For batch operations, this contains general errors; individual item errors are in FailedItems.

Query

Query files/folders in Dropbox with flexible pagination control. Pagination: AutoPagination=true (default) fetches all items automatically (best for <10k items). Set false for manual pagination with cursor (recommended for >10k items). Safety limit: 100k entries max. Paths: Root: "" or /, Subfolder: /Work/Projects, By ID: id:xxxxx, By cursor: cursor:xxxxx. Output: Check HasMore and Cursor for manual pagination; QueryResult contains file/folder metadata.

Input Parameters:

• FolderItem: Dropbox folder path to query. Must start with / (e.g., /Documents/Reports). Root folder: Use empty string "" or /. Alternative: Use folder ID format id:xxxxx.

Options:

• Limit: Maximum number of entries to return per page. Default: 500, Max: 2000. Important: When AutoPagination=true (default), this workflow automatically fetches ALL pages.
• AutoPagination: If true (default), automatically fetches all pages and returns complete results. If false, returns only the first page and provides a Cursor for manual pagination. Limit: Auto-pagination stops at 100,000 entries for safety.
• Recursive: Whether to recursively list files in all subfolders. Default: false (only list items in the specified folder).
• IncludeDeleted: If true, the results will include entries for files and folders that were deleted. Default: false.

Output:

• QueryResult (object-array): Array of file/folder metadata objects returned by Dropbox. Each object contains Core Fields (.tag, name, path_lower, path_display, id), File-Specific Fields (when .tag = "file"), and Folder-Specific Fields (when .tag = "folder").
• TotalCount (number): Total number of files/folders returned across all pages. Use this to verify if all results were fetched.
• HasMore (bool): Indicates if there are more results available. When AutoPagination=true, should be false (all pages fetched) unless interrupted at 100k limit. When AutoPagination=false, use this with Cursor to fetch next page.
• Cursor (string): Pagination cursor for fetching the next page. Only populated when AutoPagination=false and HasMore=true. Pass this value back to FolderItem parameter (with 'cursor:' prefix) to get the next page. Empty string if no more pages.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

5. Example Usage

This section will guide you through creating a simple workflow to create a new folder in your Dropbox account.

The workflow will consist of three nodes: Start -> Dropbox: Create Folder -> Answer.

1. Add the Dropbox Node

• On the workflow canvas, click the "+" icon to add a new node.
• In the panel that appears, select the "Tools" tab.
• Find and select "Dropbox" from the list of tools.
• From the list of supported operations for Dropbox, click on "Create Folder" to add the node to your canvas.

2. Configure the Node

• Click on the newly added "Create Folder" node to open its configuration panel on the right.
• Credentials: In the "Credentials" field, click the dropdown menu and select your pre-configured Dropbox credential.
• Parameters: Fill in the required input parameters for the operation.
  • Path: Enter the full path for the new folder you want to create. The path must start with a forward slash (/). For this example, enter /My Automated Reports.

3. Run and Validate

• Once all required parameters are correctly filled, any error indicators on the workflow canvas should disappear.
• Click the "Test Run" button in the top-right corner of the canvas to execute the workflow.
• After a successful execution, you can click the logs icon (also in the top-right) to view the detailed inputs and outputs of the node. You should see the FolderId in the output, confirming that the folder was created. You can also check your Dropbox account to see the new "My Automated Reports" folder.

After completing these steps, your workflow is fully configured. When run, it will automatically create the specified folder in your Dropbox account.

6. FAQs

Q: My "Create Folder" operation failed with a conflict error. Why?

A: This typically means a folder or file with the same name already exists at the specified path. Dropbox paths are unique, and you cannot have two items with the same name in the same location. Please choose a different name or path.

Q: What is the correct format for the Path parameter in operations like "Create Folder" or "List a Folder"?

A: All paths must be absolute and start with a forward slash (/), representing the root of your Dropbox. For example, /Apps/MyData is a valid path. The only exception is the Path parameter for "List a Folder," which can be an empty string ("") to list the contents of the root directory itself.

Q: How do I use the "Delete Item" or "Move Item" operations for multiple files at once?

A: The DeleteItems, FromItems, and MoveItems input fields are designed to handle multiple paths. You should enter one full path per line. For example:

/folder1/file_a.txt
/folder2/file_b.jpg
/archive/old_report.docx

7. Official Documentation

For more in-depth information about the Dropbox API and its capabilities, please refer to the official developer documentation:

Dropbox API Documentation