Dropbox Integration Guide

Overview

The Dropbox integration allows your NINA workflows to connect with Dropbox for comprehensive file and folder management. This integration enables you to upload and download files, manage folders, search for content, and perform various file operations directly from your workflows.

Status

The integration currently supports comprehensive Dropbox operations:

File Management: Upload, download, copy, move, and delete files
Folder Operations: Create, list, copy, move, and delete folders
Search Functionality: Search for files and folders with advanced filtering
Flexible Authentication: Support for both Access Token and OAuth2 authentication
Binary Data Handling: Upload both binary and text content
Advanced Options: Support for autorename, file modes, recursive listing, and more

Some advanced features include:

Conditional Parameters: Dynamic parameter display based on selections
Access Control: Support for both App Folder and Full Dropbox access
Rich Metadata: Include media info, sharing details, and file status
Batch Operations: Efficient handling of multiple files and folders
Search Filtering: Filter by file types, categories, status, and paths

Credential Configuration

Before using the Dropbox integration in your workflows, you need to configure credentials for authentication. The integration supports two authentication methods.

Authentication Methods

1. Access Token Authentication (Recommended for Simple Use Cases)

Direct authentication using a Dropbox access token:

Field	Description	Example
Access Token	Access token from your Dropbox app	`sl.ABC123DEF456...`
Access Type	Type of access for your app	`Full Dropbox`

How to obtain your Access Token:

Visit the Dropbox App Console
Create a new app or select an existing one
Go to the Settings tab
Generate an Access Token
Copy the generated token for use in your credential configuration
Choose the appropriate access type (App Folder or Full Dropbox)

2. OAuth2 Authentication (Recommended for Production)

OAuth2 authentication for secure, refreshable access:

Field	Description	Example
Client ID	Client ID from your Dropbox app	`abc123def456`
Client Secret	Client Secret from your Dropbox app	`xyz789ghi012`
Access Token URL	Token endpoint URL	`https://api.dropboxapi.com/oauth2/token`
Authorization URL	Authorization endpoint URL	`https://www.dropbox.com/oauth2/authorize`
Scope	OAuth2 permissions scope	`files.content.write files.content.read sharing.read account_info.read`
Access Type	Type of access for your app	`Full Dropbox`

How to set up OAuth2:

Visit the Dropbox App Console
Create a new app or select an existing one
Note the App Key (Client ID) and App Secret (Client Secret)
Configure redirect URLs:
- For POC environment: https://poc.zynap.com/api/v1/oauth2/callback
- For Production environment: https://platform.zynap.com/api/v1/oauth2/callback
Choose the appropriate permissions and access type

Access Types

App Folder: Restricts access to a specific folder within the user's Dropbox
Full Dropbox: Provides access to the user's entire Dropbox

Creating a Dropbox Credential

Navigate to the Credentials section in NINA
Click Add New Credential
Fill in the credential details:
- Name: A descriptive name (e.g., "Dropbox Production")
- Description: Optional details about the credential's purpose
- Integration Service: Select "Dropbox"
- Authentication Method: Choose "Access Token" or "OAuth2"
- Fill in the authentication fields based on your selected method
Click Test Connection to verify credentials
Click Save to store the credential

Supported Resources and Operations

The Dropbox integration supports the following resources and operations:

File

Operation	Description
Upload	Upload a file to Dropbox
Download	Download a file from Dropbox
Copy	Copy a file within Dropbox
Move	Move a file to a different location
Delete	Delete a file from Dropbox

Folder

Operation	Description
Create	Create a new folder
List	List folder contents
Copy	Copy a folder within Dropbox
Move	Move a folder to a different location
Delete	Delete a folder from Dropbox

Search

Operation	Description
Query	Search for files and folders

Parameter Merging

The Dropbox integration takes full advantage of NINA's parameter merging capabilities:

Parameter Sources (in order of precedence)

Node Parameters: Parameters configured directly in the Dropbox Integration Node
Extracted Parameters: Parameters automatically extracted from the input data
Input Data: The complete input data from upstream nodes

When a Dropbox Integration Node executes:

It combines parameters from all sources
Node parameters take precedence over extracted parameters
The combined parameters are used to execute the Dropbox operation

Examples

File Operations

Uploading Files

Upload Binary File

{
  "resource": "file",
  "operation": "upload",
  "parameters": {
    "path": "/documents/report.pdf",
    "binaryData": true,
    "binaryPropertyName": "data",
    "additionalFields": {
      "mode": "overwrite",
      "autorename": false,
      "mute": true
    }
  }
}

This uploads a binary file from the data property of previous node output, overwriting any existing file.

Upload Text File

{
  "resource": "file",
  "operation": "upload",
  "parameters": {
    "path": "/notes/meeting-notes.txt",
    "binaryData": false,
    "fileContent": "Meeting Notes\n\n1. Project updates\n2. Next steps\n3. Action items",
    "additionalFields": {
      "mode": "add",
      "autorename": true
    }
  }
}

This uploads text content directly, with autorename enabled to avoid conflicts.

Downloading Files

{
  "resource": "file",
  "operation": "download",
  "parameters": {
    "path": "/documents/report.pdf"
  }
}

This downloads the specified file and returns its content.

File Management Operations

Copy File

{
  "resource": "file",
  "operation": "copy",
  "parameters": {
    "fromPath": "/original/document.docx",
    "toPath": "/backup/document-backup.docx",
    "additionalFields": {
      "autorename": true,
      "allowSharedFolder": false
    }
  }
}

Move File

{
  "resource": "file",
  "operation": "move",
  "parameters": {
    "fromPath": "/temp/draft.txt",
    "toPath": "/final/published.txt",
    "additionalFields": {
      "autorename": false
    }
  }
}

Delete File

{
  "resource": "file",
  "operation": "delete",
  "parameters": {
    "path": "/temp/old-file.txt"
  }
}

Folder Operations

Creating Folders

{
  "resource": "folder",
  "operation": "create",
  "parameters": {
    "path": "/projects/new-project",
    "additionalFields": {
      "autorename": true
    }
  }
}

Listing Folder Contents

Basic Folder Listing

{
  "resource": "folder",
  "operation": "list",
  "parameters": {
    "path": "/documents",
    "returnAll": false,
    "limit": 50
  }
}

Advanced Folder Listing

{
  "resource": "folder",
  "operation": "list",
  "parameters": {
    "path": "/media",
    "returnAll": true,
    "additionalFields": {
      "recursive": true,
      "includeMediaInfo": true,
      "includeDeleted": false,
      "includeHasExplicitSharedMembers": true,
      "includeMountedFolders": true,
      "includeNonDownloadableFiles": false
    }
  }
}

This performs a recursive listing with media information and sharing details.

Folder Management Operations

Copy Folder

{
  "resource": "folder",
  "operation": "copy",
  "parameters": {
    "fromPath": "/templates/project-template",
    "toPath": "/projects/new-project",
    "additionalFields": {
      "autorename": true
    }
  }
}

Move Folder

{
  "resource": "folder",
  "operation": "move",
  "parameters": {
    "fromPath": "/drafts/project-draft",
    "toPath": "/completed/project-final"
  }
}

Delete Folder

{
  "resource": "folder",
  "operation": "delete",
  "parameters": {
    "path": "/temp/old-folder"
  }
}

Search Operations

Basic Search

{
  "resource": "search",
  "operation": "query",
  "parameters": {
    "query": "meeting notes",
    "returnAll": false,
    "limit": 25
  }
}

Advanced Search

{
  "resource": "search",
  "operation": "query",
  "parameters": {
    "query": "project report",
    "returnAll": true,
    "additionalFields": {
      "path": "/projects",
      "fileStatus": "active",
      "fileCategories": ["document", "presentation"],
      "fileExtensions": "pdf,docx,pptx",
      "simplifyResult": false
    }
  }
}

This searches for "project report" within the /projects folder, filtering by specific file types and categories.

Response Structure

File Upload Response

{
  "success": true,
  "result": {
    "name": "report.pdf",
    "path_lower": "/documents/report.pdf",
    "path_display": "/Documents/report.pdf",
    "id": "id:abc123def456",
    "client_modified": "2024-01-15T10:30:00Z",
    "server_modified": "2024-01-15T10:30:05Z",
    "rev": "abc123def456",
    "size": 1024576,
    "is_downloadable": true,
    "content_hash": "abc123def456789"
  }
}

File Download Response

{
  "success": true,
  "result": {
    "name": "report.pdf",
    "path_display": "/Documents/report.pdf",
    "content": "base64-encoded-file-content",
    "metadata": {
      "size": 1024576,
      "client_modified": "2024-01-15T10:30:00Z",
      "server_modified": "2024-01-15T10:30:05Z",
      "content_hash": "abc123def456789"
    }
  }
}

Folder List Response

{
  "success": true,
  "result": {
    "entries": [
      {
        ".tag": "file",
        "name": "document.pdf",
        "path_lower": "/documents/document.pdf",
        "path_display": "/Documents/document.pdf",
        "id": "id:file123",
        "size": 2048576,
        "is_downloadable": true,
        "client_modified": "2024-01-15T09:00:00Z",
        "server_modified": "2024-01-15T09:00:02Z"
      },
      {
        ".tag": "folder",
        "name": "Subfolder",
        "path_lower": "/documents/subfolder",
        "path_display": "/Documents/Subfolder",
        "id": "id:folder456"
      }
    ],
    "cursor": "cursor_token_for_pagination",
    "has_more": false
  }
}

Search Response

{
  "success": true,
  "result": {
    "matches": [
      {
        "match_type": {
          ".tag": "filename"
        },
        "metadata": {
          ".tag": "file",
          "name": "meeting-notes.txt",
          "path_display": "/Notes/meeting-notes.txt",
          "size": 4096,
          "client_modified": "2024-01-15T14:30:00Z"
        }
      }
    ],
    "more": false,
    "start": 0
  }
}

Integration in Workflow Context

The Dropbox integration is particularly effective for document management and file processing workflows:

Common Workflow Patterns:

Document Processing Pipeline:
- Email Node (receive attachments) → Dropbox Node (upload) → OCR Service Node → Dropbox Node (upload processed)
Backup and Archival:
- Database Export Node → Script Node (format) → Dropbox Node (upload) → Email Node (confirmation)
Content Distribution:
- CMS Node (export content) → Dropbox Node (upload) → Dropbox Node (copy to distribution folder) → Webhook Node (notify)
File Synchronization:
- FTP Node (download) → Dropbox Node (upload) → Dropbox Node (organize into folders) → Log Node
Search and Processing:
- Schedule Node → Dropbox Node (search) → Filter Node (by criteria) → Processing Node → Dropbox Node (upload results)
Collaborative Workflows:
- Form Node (collect data) → Script Node (generate report) → Dropbox Node (upload) → Slack Node (share link)

Advanced Features

Conditional Parameters

The integration uses display options to show relevant parameters based on selections:

Binary Data Toggle: When binaryData is true, shows binaryPropertyName; when false, shows fileContent
Return All Toggle: When returnAll is false, shows limit parameter for pagination

File Mode Options

Add: Creates a new file, fails if file already exists
Overwrite: Replaces existing file or creates new one

Access Type Configuration

App Folder: Limits access to a specific app folder (/Apps/YourApp/)
Full Dropbox: Provides access to the entire Dropbox account

Search Categories

Supported file categories for search filtering:

image - Image files
document - Document files
pdf - PDF files
spreadsheet - Spreadsheet files
presentation - Presentation files
audio - Audio files
video - Video files
folder - Folders
paper - Dropbox Paper documents
others - Other file types

Best Practices

Use OAuth2 for Production: OAuth2 provides better security and token refresh capabilities compared to access tokens.
Handle Path Formatting: Ensure paths start with "/" and use forward slashes for consistency.
Implement Autorename: Enable autorename for uploads to avoid conflicts with existing files.
Use Appropriate Access Types: Choose App Folder for restricted access or Full Dropbox for comprehensive access.
Optimize Search Queries: Use specific search terms and filters to improve performance and relevance.
Handle Large Files: For large file uploads, consider implementing progress monitoring and error handling.
Leverage Metadata: Use additional fields like includeMediaInfo for rich file information.
Implement Error Handling: Add comprehensive error handling for network issues, permission problems, and API limits.
Use Batch Operations: When possible, batch multiple file operations to improve efficiency.
Monitor API Usage: Be aware of Dropbox API rate limits and implement appropriate throttling.
Validate Paths: Always validate file and folder paths before operations to prevent errors.
Use Recursive Listing Carefully: Recursive folder listing can return large amounts of data; use with appropriate limits.

Security Considerations

Credential Management: Store Dropbox credentials securely and rotate them regularly.
Access Control: Use the most restrictive access type that meets your needs.
File Permissions: Be aware of file sharing and permission implications when uploading to shared folders.
Data Encryption: Sensitive data should be encrypted before uploading to Dropbox.
Audit Logging: Implement logging for all Dropbox operations for security auditing.

Troubleshooting

Common Issues and Solutions

Issue	Possible Solution
Authentication failed	Verify access token/OAuth credentials are correct and haven't expired
File not found	Check file path format and ensure the file exists
Permission denied	Verify app permissions and access type configuration
Upload failed	Check file size limits and available storage space
Path conflict	Enable autorename or choose overwrite mode for uploads
Rate limit exceeded	Implement delays between operations or reduce request frequency
Invalid path format	Ensure paths start with "/" and use proper formatting
Shared folder access denied	Check `allowSharedFolder` setting for move/copy operations

Error Response Format

The integration returns standardized error responses:

{
  "success": false,
  "error": {
    "code": "path/not_found",
    "message": "The file or folder at the specified path was not found",
    "operation": "download",
    "path": "/nonexistent/file.txt"
  }
}

Common Dropbox Error Codes

Error Code	Description
`auth/invalid_access_token`	Access token is invalid or expired
`path/not_found`	File or folder path doesn't exist
`path/conflict`	Path conflict (file already exists)
`insufficient_space`	Not enough storage space available
`too_many_requests`	Rate limit exceeded
`invalid_path_root`	Invalid path root for app folder access

Support

If you encounter issues with the Dropbox integration, please contact our support team with:

The operation you were attempting
Your access type configuration (without sensitive credentials)
Any error messages received
The file paths and sizes you were working with
The workflow context where the issue occurred

This information will help us provide faster and more accurate assistance.

Overview​

Status​

Credential Configuration​

Authentication Methods​

1. Access Token Authentication (Recommended for Simple Use Cases)​

2. OAuth2 Authentication (Recommended for Production)​

Access Types​

Creating a Dropbox Credential​

Supported Resources and Operations​

File​

Folder​

Search​

Parameter Merging​

Parameter Sources (in order of precedence)​

Examples​

File Operations​

Uploading Files​

Upload Binary File​

Upload Text File​

Downloading Files​

File Management Operations​

Copy File​

Move File​

Delete File​

Folder Operations​

Creating Folders​

Listing Folder Contents​

Basic Folder Listing​

Advanced Folder Listing​

Folder Management Operations​

Copy Folder​

Move Folder​

Delete Folder​

Search Operations​

Basic Search​

Advanced Search​

Response Structure​

File Upload Response​

File Download Response​

Folder List Response​

Search Response​

Integration in Workflow Context​

Common Workflow Patterns:​

Advanced Features​

Conditional Parameters​

File Mode Options​

Access Type Configuration​

Search Categories​

Best Practices​

Security Considerations​

Troubleshooting​

Common Issues and Solutions​

Error Response Format​

Common Dropbox Error Codes​

Support​