Introduction

The Dropbox connector allows Simpplr Enterprise Search to index your Dropbox Business content, making it easily discoverable and searchable directly within Simpplr.

With this connector, you can:

• Unify search across systems — Search Dropbox files and folders alongside other enterprise content within Simpplr, eliminating the need to switch between applications.

• Surface relevant answers faster — Leverage semantic search, keyword matching, and Smart Answers powered by indexed Dropbox content, including full-text extraction from supported document types.

• Maintain permission-aware results — When Document Level Security (DLS) is enabled, search results respect Dropbox's access control model, ensuring users only see content they have access to.

Indexed content from Dropbox is available in:

• Main search listing

• Smart Answers

Capabilities at a Glance

Objects and Content Supported

Objects

The Dropbox connector indexes two object types:

• Files (File) — All regular files stored in Dropbox Business, including:

• Documents (PDF, DOCX, PPTX, XLSX, TXT, etc.)

• Dropbox Paper documents (exported as Markdown)

• Shared files received from external sources

• Folders (Folder) — Directory containers that organise files, indexed for hierarchy resolution and path-based filtering.

Not Indexed

• Dropbox Personal accounts (non-Business)

• Dropbox Replay, Dropbox Sign, and Dropbox Transfer content

• File comments and annotations

• Binary and media files (content extraction skipped; metadata still indexed)

• Files owned by users outside the Dropbox Business team (only files shared into the team are captured)

Metadata

For each indexed item, the Dropbox connector captures:

Permissions Model

The Dropbox connector implements Document Level Security (DLS) that maps Dropbox's layered permission model into Elastic search access control.

Versions and Editions Supported

Minimum Requirements

• Dropbox Business account with a Team Admin who can authorise the OAuth app

• OAuth app created in the Dropbox App Console with Scoped access and Full Dropbox access type

• All required OAuth scopes enabled (see Authentication section)

Prerequisites

Before you begin, ensure the following:

Source System Permissions

• You have Dropbox Business Team Admin access.

• You can create and manage OAuth applications in the Dropbox App Console.

• The team has active content (team folders, shared folders, or member folders) to index.

OAuth Application

• Ability to create an OAuth app in the Dropbox App Console with Scoped access.

• The app must have Full Dropbox API access (not App Folder).

• The following scopes must be enabled:

Authentication and Security

Authentication Mechanism

The Dropbox connector uses OAuth 2.0 with offline access (refresh token flow) to connect to the Dropbox API.

Required Credentials

Data Security

• Data storage and residency: Indexed content from Dropbox is stored within your Simpplr Enterprise Search environment, in the same region as your Simpplr tenant.

• Encryption in transit: Server-side encryption with Amazon S3 managed keys (SSE-S3), TLS encryption in Kafka.

• Encryption at rest: SSL (TLS 1.2 or higher), Auth: OAuth 2.0 Bearer tokens (client-credential).

• Permission enforcement: When DLS is enabled, search results are filtered at query time using the user's identity (email) matched against indexed access control tokens.

Setup and Configuration

Step 1 — Create a Dropbox OAuth App

1. Navigate to the Dropbox App Console (https://www.dropbox.com/developers/apps) and sign in with Team Admin credentials.

   

2. Click Create App.

3. Select Scoped access as the API type.

4. Select Full Dropbox as the access type.

5. Name the app (e.g., Simpplr-ES-Connector).

6. Choose your Dropbox business account (not the personal account) and click Create App.

Step 2 — Configure Permissions

1. Navigate to the Permissions tab of the newly created app.

2. Enable all scopes listed in the Prerequisites > OAuth Application table above.

3. Click Submit to save.

   

Step 3 — Obtain App Key, App Secret, and Refresh Token

1. Navigate to the Settings tab of the app.

2. Copy the App key and App secret values.

   

3. Construct the authorization URL (replace <APP_KEY>):

   https://www.dropbox.com/oauth2/authorize?client_id=<APP_KEY>&response_type=code&token_access_type=offline

4. Open this URL in a browser, sign in as a Team Admin, and click Allow.

5. Copy the authorization code from the resulting page.

6. Take that authorization code and pass it in below curl 

7. Hit the below curl in Postman to get refresh token using authorization code, app_key and app_secret fetched from above.

   curl -X POST "
   https://api.dropboxapi.com/oauth2/token
   " \
     -d "code=<AUTHORIZATION_CODE>" \
     -d "grant_type=authorization_code" \
     -d "client_id=<APP_KEY>" \
     -d "client_secret=<APP_SECRET>"

8. Store the refresh_token from the JSON response securely. This token does not expire unless manually revoked.

Step 4 — Create the Connector in Simpplr

1. In Simpplr, go to: Enterprise Search > Connectors > Add connector.

   

2. Select "Dropbox" from the connector list.

   

3. Enter the connection name (e.g., "Dropbox - Production").

4. Provide authentication details: App Key, App Secret, Refresh Token.

   

5. Configure optional settings:

   1. Path: Root path to fetch files/folders from (default: / for all content)

      

6. Click Save to store the configuration.

Step 5 — Filters (Optional)

Configure folder-based filtering using include/exclude rules:

• Include folders: Restrict sync to specific team folders or namespace IDs

• Exclude folders: Skip specific team folders or subtrees

• Query-based filtering by file name

• Filter by file extensions (e.g., ["pdf", "docx"])

• Filter by file categories (e.g., document, spreadsheet)

Default filters applied automatically:

• Content-age cutoff: Configurable timestamp-based filter to exclude older content

• File size limit: Content extraction skipped for files exceeding the configured max_file_size_mb (default 10 MB); metadata still indexed

• Media file exclusion: Common media types (.jpg, .png, .mp4, .wav, etc.) excluded from content extraction; metadata still indexed

Step 6 — Monitor

After saving the connector configuration, the initial sync starts automatically.

Monitor sync status at: Enterprise Search > Connectors > Dropbox > Health.

If the initial sync fails, check the error details in the dashboard and refer to the Monitoring and Troubleshooting section.

Crawling and Sync Behavior

Initial Full Crawl

Incremental Updates

Mechanism: Cursor-based delta using stored folder cursors per namespace, supplemented by team event log polling for permission-only changes.

Frequency: Hourly.

User Sync

Deletion and Permission Changes

Expected Latency

Search Experience

Search results from the Dropbox connector appear with:

• Icon: Dropbox source icon

• Source label: "Dropbox Connector Name"

• Title: File or folder name as a clickable link to the original item in Dropbox

• Snippet: Excerpt from the extracted file content

• Author: Author name (resolved from sharing permissions)

• Last modified date: When the item was last updated

• Document Icon and File Type

Available Filters and Facets

Advanced Search Features

• Smart Answers / Q&A: Yes

• Autocomplete: Yes — built from title and name fields

• Semantic / hybrid ranking: Yes

Known Limitations

Cursor Expiry

Dropbox folder cursors are opaque and can expire without a documented TTL. If a cursor expires, the connector falls back to a fresh full enumeration for that namespace. Hourly incremental syncs minimize the chance of expiry.

Permission-Only Changes Not in Folder Cursors

Changes to folder membership or file sharing that do not modify file content are not reflected in folder cursors. The connector supplements with team_log/get_events for sharing events. For teams without event log access, the weekly full-with-delta sync catches permission drift.

Team Event Log Plan Restriction

team_log/get_events may not be available on all Dropbox Business plans. The connector detects unavailability at runtime and degrades gracefully to cursor-only incremental sync with a logged warning.

Paper File Metadata Delays

Dropbox Paper documents may have a delay between content creation and server_modified timestamp stabilisation. The connector uses client_modified as fallback for Paper files (detected by .paper extension).

Rate Limits

Dropbox uses per-authorization rate limiting. The connector respects HTTP 429 Retry-After headers and applies exponential backoff. Exact rate limits are not published by Dropbox.

Other Known Limitations

• External collaborator content: Files owned by users outside the Dropbox Business team are not enumerated. Only files shared into the team via sharing/list_received_files are captured.

• Group nesting: The connector resolves direct group membership only. Nested groups (groups within groups) are not recursively resolved.

• No real-time sync: The connector uses scheduled polling. Dropbox webhooks are not integrated in the current version.

Monitoring and Troubleshooting

Connector Health and Monitoring

Navigate to: Enterprise Search > Connectors > Dropbox

Common Issues and Resolutions

Authentication failed (invalid credentials)

Possible causes:

• Incorrect App Key or App Secret

• Refresh token has been manually revoked by a user or admin at Dropbox Connected Apps settings

• OAuth app was deleted from the Dropbox App Console

Resolution:

• Verify App Key and App Secret match the values in the Dropbox App Console.

• Confirm the refresh token is still valid (test by exchanging it for an access token manually).

• If the refresh token was revoked, re-run the OAuth authorization flow to generate a new one.

• Re-enter the credentials in the connector configuration and test the connection.

Rate limit or quota exceeded

Possible causes:

• Too many API requests to Dropbox in a short period

• Other integrations or services consuming API quota on the same Dropbox Business team

Resolution:

• The connector automatically respects Retry-After headers and applies exponential backoff.

• Narrow the sync scope using folder include/exclude filters or reduce concurrent downloads.

• If persistent, check whether other applications are consuming Dropbox API quota.

Configured path not found (InvalidPathException)

Possible causes:

• The configured root path (e.g., /Engineering) no longer exists in Dropbox

• The path was renamed or moved

Resolution:

• Log in to Dropbox and verify the configured path exists.

• Update the connector configuration with the correct path.

• Re-run sync after correcting the path.

Cursor expired (HTTP 409 reset)

Possible causes:

• The stored folder cursor for a namespace has expired (Dropbox does not document a specific cursor TTL)

• Extended periods of inactivity between syncs

Resolution:

• The connector handles this automatically — it falls back to a fresh files/list_folder enumeration for the affected namespace and obtains a new cursor.

• If this occurs frequently, ensure incremental syncs are running hourly to prevent cursor staleness.

Incremental sync fails with "sync cursor empty" error

Possible causes:

• No full sync has been completed successfully prior to running incremental sync

• The sync cursor was corrupted or lost

Resolution:

• Run a full sync first to establish the initial sync cursor with folder cursors, processed IDs, and folder hashes.

• Once the full sync completes successfully, incremental syncs will work automatically.

Connection errors (ServerDisconnectedError / ClientConnectionError)

Possible causes:

• Network instability between the connector runtime and Dropbox APIs

• Dropbox service restart or transient infrastructure issue

Resolution:

• The connector automatically closes the stale session, creates a new one, and retries with exponential backoff.

• If persistent, verify network connectivity to api.dropboxapi.com and content.dropboxapi.com.

Team event log unavailable

Possible causes:

• The Dropbox Business team's plan does not include team_log/get_events access

• API returns HTTP 400, 403, or 404

Resolution:

• The connector detects this automatically and disables event log polling for subsequent syncs.

• Permission-only changes will not be detected until the next weekly full-with-delta sync or unless the file is modified.

• No action required unless permission-only change detection is critical, in which case upgrade to a Dropbox plan that includes the team event log.

When to Contact Support

Contact Simpplr Support if:

• Authentication errors persist even after verifying credentials and re-generating the refresh token

• Sync is stuck and has not progressed for several hours

• Sync fails repeatedly despite following the troubleshooting steps

• Incomplete or partial sync — only some team folders are indexed when more are expected

• DLS permissions appear incorrect after multiple sync cycles

When contacting Support, include:

• Connector name and instance ID (if available)

• Organization URL

• Approximate time and date of the issue

• Error messages or screenshots from the connector health dashboard

• Steps you have already tried

Frequently Asked Questions

Q: Can I connect multiple Dropbox Business teams?

Ans: Yes. Each Dropbox Business team is configured as a separate connector in Simpplr. Go to Enterprise Search > Connectors > Add connector, and create a new Dropbox connector for each team with its own App Key, App Secret, and Refresh Token.

Q: How often does the Dropbox connector sync data?

Ans: The connector runs a full crawl on first setup and then once per week. Incremental sync runs every hour.

Q: Are comments, revisions, or version history indexed?

Ans: No. The connector indexes only the current version of each file. File comments, annotations, and revision history are not indexed.

Q: Does the connector index content from external guests or shared links?

Ans: The connector indexes files shared into the Dropbox Business team. Files owned by users outside the team are only captured if they are shared into the team. Public shared links are not indexed as separate documents.

Q: Can I exclude certain team folders or content from being indexed?

Ans: Yes. The connector supports folder-based filtering:

• Include rules: Restrict sync to specific team folders by namespace ID, with optional sub-path scoping.

• Exclude rules: Skip specific team folders or subtrees.

Q: What happens if the Dropbox admin who authorized the connector is deactivated?

Ans: Team-linked OAuth tokens survive individual admin changes — if API calls continue to work, no action is needed. If the admin's removal triggers app de-authorization, the refresh token becomes invalid, and the connector must be re-authorized by another Team Admin. It is recommended to use a service admin account that is unlikely to be deactivated.