HELIOS DOCS

Google Drive

Connect Google Drive to let Helios agents read, upload, and organize files within the permissions you grant, and to start agents when files, folders or shared drives change.

What your agents can do

Agents use your connected Google account to work with files and folders, within the permissions you grant.

  • Search and list files and folders across your Drive
  • Read file metadata and the content of text files
  • Export Google Docs, Sheets and Slides as text or CSV
  • Create folders, and upload text files such as reports or CSV exports
  • Organize, copy, and update files the agent created or you opened with Helios
  • Find Google Meet recordings and photos (read-only)
  • Manage the hidden app-data folder

Agents can also download and upload binary files through the API tool.

Authentication

MethodTypeDescription
Helios Google Drive AppOAuth 2.0Sign in with Google through the Helios app (recommended)
BYO Google Drive AppOAuth 2.0Paste tokens that you create with your own Google OAuth client

Helios Google Drive App

Helios runs the Google OAuth redirect flow and asks each user for consent (access_type=offline, prompt=consent) so agents can act on your behalf, including when you're offline.

The Helios Google Drive App requests scopes to:

  • Read files and file metadata (drive.readonly, drive.metadata, drive.metadata.readonly)
  • Create and manage files it opens with Helios (drive.file)
  • Read Google Meet recordings and photos, read-only (drive.meet.readonly, drive.photos.readonly)
  • Manage the hidden app-data folder and read installed-app metadata (drive.appdata, drive.apps.readonly)

BYO Google Drive App

Use this method when you need your own OAuth client, for example for your own branding. Helios doesn't redirect to Google for this method. You create the tokens yourself and paste them in.

  1. In the Google Cloud console, create a project or pick one. Under APIs & Services → Library, enable the Google Drive API.
  2. Open Google Auth Platform. On Branding, set the app name and the user support email. On Audience, choose Internal, or External with your account under Test users.
  3. On Data Access, click Add or Remove Scopes and add the Drive scopes listed above. Each one is https://www.googleapis.com/auth/ plus its name, such as https://www.googleapis.com/auth/drive.readonly.
  4. On Clients, click Create client and choose Web application. Under Authorized redirect URIs, add https://developers.google.com/oauthplayground, then click Create.
  5. Open the OAuth 2.0 Playground. Click the gear icon, tick Use your own OAuth credentials, enter the client ID and secret, and keep Access type set to Offline.
  6. In Step 1, enter the Drive scopes, click Authorize APIs, and approve access with the Google account the agent should use. In Step 2, click Exchange authorization code for tokens.
  7. In Helios, choose BYO Google Drive App. Fill in Client Id and Client Secret from your client, Access Token and Refresh Token from the Playground, and Email with the Google account you approved with.

Helios renews the access token with the refresh token. Google expires the refresh token of an External app in Testing 7 days after you approve it, so publish the app on the Audience page to keep the connection working. If the refresh token stops working, create new tokens in the Playground and enter them through Manage.

Learn more in the Google Drive API documentation.

Triggers

Google Drive can start a Workflow when files, folders or shared drives change. Helios sets up notifications with the Drive API when you save the connection, so there is nothing to set up in Google.

Google keeps a change log for each account and one for each shared drive. Helios watches the connected account's log, which covers My Drive and the files shared with you, and the log of every shared drive the account is a member of. When the account joins or leaves a shared drive, Helios starts or stops watching that drive within a few minutes.

EventDescriptionFilters
file.createdA file or folder was created, uploaded or copiedname (pattern), MIME type (pattern), folder, shared drive
file.updatedA file or folder changed, such as its content, its name, its folder or its sharingname (pattern), MIME type (pattern), folder, shared drive
file.trashedA file or folder was moved to the trashname (pattern), MIME type (pattern), folder, shared drive
file.untrashedA file or folder was restored from the trashname (pattern), MIME type (pattern), folder, shared drive
file.removedA file or folder was deleted permanently, or the account lost access to itshared drive
shared_drive.addedYou were added to a shared drive, or you created oneshared drive, shared drive name (pattern)
shared_drive.updatedA shared drive changed, such as its name, its settings or its membersshared drive, shared drive name (pattern)
shared_drive.removedA shared drive was deleted, or you were removed from itshared drive

All filters are optional.

  • Name matches the name of the file or folder. Case doesn't matter, so *.pdf also matches SCAN.PDF.
  • MIME type matches the file's type, such as application/pdf or image/*. Google's own files have their own types: application/vnd.google-apps.document for Docs, application/vnd.google-apps.spreadsheet for Sheets, application/vnd.google-apps.presentation for Slides and application/vnd.google-apps.folder for folders.
  • Folder is chosen from a list of your folders. It matches files and folders directly inside the folder, not in its subfolders.
  • Shared drive is chosen from the shared drives the account is a member of. Changes in My Drive don't match when it's set.
  • Shared drive name matches the name of the shared drive. Case doesn't matter.

How Helios reads the changes:

  • An event has the current state of the file, not what changed.
  • A file counts as created when it was created after the last change Helios read. A file that someone created earlier and then shared with you, or moved into a shared drive, arrives as file.updated.
  • Google also records changes that only affect your own view, such as starring a file or opening it for the first time. They arrive as file.updated.
  • For file.removed, Google sends only the file's ID. The name, MIME type and folder filters can't match it, and Google doesn't say whether the file was deleted or the account lost access.

Listing shared drives needs read access to your whole Drive (drive.readonly). Without it, Helios watches only the account's own change log. A connection that only has drive.file receives file events only for files that Helios created or that you opened with Helios.

An agent's own changes can start new runs. An agent that uploads a file to a watched folder starts another file.created run. Filter on the folder or the name, or say in the prompt which files to ignore. See Guarding against events you don't want.

Check that it works

  1. Add file.created to a workflow with no filters.
  2. Upload a test file to My Drive.
  3. Check that a run starts. Then open the connection in Helios and click Webhook events to see the event.
What you seeCauseFix
Every Drive event shows as unavailableThe connection has no access to Google DriveClick Re-connect and allow every permission Google asks for
Shared drive events show as unavailableThe connection can't list your shared drivesClick Re-connect and allow every permission Google asks for. For BYO Google Drive App, create tokens with drive.readonly
No run starts after a changeThe filters don't match, the file is in a subfolder of the chosen folder, or the refresh token stopped workingTest with no filters, and click Re-connect if the connection shows Error

Notes

Helios requests read access to your Drive plus write access to files it creates or you explicitly open with it (drive.file). It doesn't request the full drive or drive.scripts scopes, so content and sharing changes are limited to files created or opened with Helios. The drive.metadata scope also allows metadata changes, such as renaming and moving files, where the connected account has permission.

Last updated on