Skip to content

Google Drive#

Google Drive is registered for OAuth-backed assigned-comment sync. An operator connects a Google account, selects up to five files in Google's OnePick flow, and creates a reviewable TeamBoost import session from live comments that have an explicit assignee.

Capability Method Status
CSV_IMPORT — Not built
SYNC Pull assigned comments from selected My Drive files ✅ Built
USER_IMPORT Comment assignees imported during sync ✅ Built
WEBHOOK — Not built

The endpoints below live under /api/v1/providers/google-drive/.... Authorization and sync require an organization-scoped user token. The OAuth redirect callback is unauthenticated; its signed state supplies the organization binding.

Google Cloud Setup#

Use one Google Cloud project for the connection:

  1. Enable the Google Drive API and Google Picker API.
  2. Configure the Google Auth consent screen and its test users or publishing status.
  3. Create an OAuth 2.0 web client.
  4. Register the service callback URI exactly.
  5. Provide the client values through environment configuration; never commit real secrets.
GOOGLE_DRIVE_CLIENT_ID=<google-oauth-client-id>
GOOGLE_DRIVE_CLIENT_SECRET=<google-oauth-client-secret>
GOOGLE_DRIVE_REDIRECT_URI=https://<host>/api/v1/providers/google-drive/oauth/callback
GOOGLE_DRIVE_SCOPES=https://www.googleapis.com/auth/drive.file

The scope is fixed to drive.file. Broader Drive scopes are rejected. Missing or invalid app configuration returns oauth_not_configured.

Connect And Select Files#

Start the connection:

GET /api/v1/providers/google-drive/oauth/authorize?organization_id=<id>

The returned Google authorization URL uses prompt=consent, offline access, trigger_onepick=true, and multi-select. Google handles both consent and file selection, then redirects to:

GET /api/v1/providers/google-drive/oauth/callback
    ?state=<signed-state>
    &code=<authorization-code>
    &scope=https://www.googleapis.com/auth/drive.file
    &picked_file_ids=<comma-separated-file-ids>

The callback accepts one to five unique, opaque file IDs. It rejects missing, duplicate, malformed, or over-limit selections and any scope other than drive.file. Successful exchange stores an encrypted, organization-scoped OAuth bundle containing the refresh token and selected-file boundary. Tokens and file IDs are never returned or logged.

The selected-file boundary changes only by reconnecting and choosing a new set.

Credential Operations#

GET /api/v1/providers/google-drive/credentials?organization_id=<id>
POST /api/v1/providers/google-drive/credentials/verify?organization_id=<id>
DELETE /api/v1/providers/google-drive/credentials?organization_id=<id>

Verification calls Drive about.get and checks that the live permission ID matches the connected account. Expiring access tokens refresh automatically; refresh preserves the exact account identity, scope, and selected-file set.

Sync Assigned Comments#

POST /api/v1/providers/google-drive/imports/sync?organization_id=<id>

Sync performs an atomic snapshot:

  • fetch metadata for every selected file;
  • reject trashed files, folders, shared-drive files, inaccessible files, and mismatched resource IDs;
  • follow comment pagination with bounded retry for Google quota and transient failures;
  • include only non-deleted comments with assigneeEmailAddress;
  • fail the whole snapshot if a selected file or included comment is malformed;
  • cap the snapshot at 1,000 comments across at most five files.

The adapter reads only fixed https://www.googleapis.com/drive/v3 endpoints. It does not download file bodies or modify files, comments, permissions, or assignees.

Projection#

Drive source TeamBoost draft Behavior
Comment text title, description Whitespace-normalized title; empty text is a blocking projection error.
Resolution state status Open → NOT_STARTED; resolved → COMPLETED.
Comment assignee ownerId Resolved through the editable user mapping; an unmatched assignee blocks confirmation.
Comment author creatorId Left unset with a review note because Drive omits usable author email and permission ID.
File name projectTitle Groups comment tasks by selected file.
Resource type type Defaults to OTHER.
Priority priority Drive comments have none; defaults to UNKNOWN.
File/comment context descriptionJson Preserves safe file link, MIME type, timestamps, assignee, author display context, mentions, quoted content, replies, and source IDs.

USER_IMPORT rides sync. Assignee emails are normalized and deduplicated before TeamBoost proposes member mappings. This is not a Google Workspace directory sync.

Not Built#

  • Arbitrary Drive files, folders, or document bodies as tasks.
  • Google Sheets task rows. They are implemented as the separate Google Sheets provider with their own credential and projection.
  • Shared-drive files.
  • Service accounts or domain-wide delegation.
  • Standalone Workspace directory import.
  • Drive push notifications or Google Workspace Events/Pub/Sub comment events.
  • Background or scheduled sync.
  • Execution of confirmed import sessions into TeamBoost; the current flow ends at review and confirmation.