Skip to main content

Import from cloud folders

Jiandu can watch an operator-configured Google Drive, Dropbox, or OneDrive folder and ingest its ordinary files. It checks subfolders periodically, remembers imported revisions across restarts, and leaves cloud files untouched. Changed content becomes a new immutable document. Deleting a cloud file does not delete the document already imported into Jiandu.

Connect a configured folder​

  1. Sign in as a household Owner or Administrator and open Settings → Document capture.
  2. Under Cloud folders, choose a configured provider folder and enter a display name.
  3. Leave Start watching immediately selected, or clear it to save a paused connection.
  4. Connect the folder. Its status shows whether watching is enabled and when a complete scan last succeeded. Use Pause, Resume, or Remove on the connection when needed.

The first scan includes files already in the folder. Supported inputs follow the same PDF, JPEG, PNG, and UTF-8 text validation as browser uploads. Google Workspace editor files, cloud-native Dropbox documents, and shortcuts are skipped; export these as ordinary supported files first. Duplicate content follows Jiandu's normal duplicate handling.

If no folders are available, the installation operator must configure them first. The browser cannot provide arbitrary cloud URLs or account credentials.

Operator setup​

Add capture.cloud_roots in the server configuration. Each entry names the provider, a stable root ID, a display name, the provider folder ID or Dropbox path, an absolute credential-file reference, and a polling interval between 60 and 86,400 seconds. OneDrive optionally accepts drive_id. Provider values are google_drive, dropbox, and one_drive.

{
  "capture": {
    "cloud_roots": [{
      "id": "household-drive",
      "display_name": "Household Drive inbox",
      "provider": "google_drive",
      "folder_id": "YOUR_FOLDER_ID",
      "credential_file": "/srv/jiandu/secrets/google-drive.json",
      "poll_interval_seconds": 300
    }]
  }
}

Provision an OAuth refresh grant through the provider's authorization flow with read-only content permissions. The private JSON credential file contains client_id, refresh_token, and client_secret when required by the application. Microsoft may also specify tenant, which otherwise defaults to common. Initial provider consent happens outside Jiandu.

On Unix the credential must be a regular, single-link file with mode 0600. Jiandu needs write access to its private parent directory to atomically persist rotated refresh tokens. Mount that directory writable for container deployments. Access tokens are cached in memory only, and neither tokens nor credential paths are returned to the browser.

The repository's operator runbook contains provider scope details and a three-provider example. Check the configuration reference for the full registry contract. Run jiandu --check-config and restart after changing the registry.

Recover from a failure​

A provider outage or rejected credential produces a connector error and retries after backoff. Reauthorize an expired or revoked grant and replace the private credential file. Verify the account still has access when a source is missing. Correct an unsupported or invalid source document to produce a new revision for ingestion. Other documents can continue through the connector.

Pausing or removing a connector stops new work once observed. Already accepted uploads continue finalizing, and imported documents remain available. Removing and recreating a connection clears its discovery history and scans the folder again; checksum duplicate handling still applies.

The control ledger supports 32 configured roots, 8,192 folders per traversal, and 100,000 remembered remote file identities across the installation. Individual file contents are streamed with bounded buffers; enough local staging and archive capacity is required. Live Google, Dropbox, and Microsoft account interoperability remains a release-verification gate.

Last updated on