Google Drive Module

List, read, and write Google Drive files from your Processes — authenticated with a Google Cloud service account.

The Google Drive Module adds three Tasks for working with Drive content: list the files in a folder, read a file's content into a Session variable, and upload new files. It authenticates with a Google Cloud service account, optionally impersonating a Workspace user via domain-wide delegation. Each Environment supplies its own service-account JSON credential in the Module's Environment configuration.

What you can build

• Document ingestion — GoogleDriveListFilesTask to discover files in a folder, then GoogleDriveReadFileTask to pull each one's text into a Session variable for downstream parsing.
• AI summarization — GoogleDriveReadFileTask → OpenAIChatCompletionTask → GoogleDriveUploadFileTask writes the summary back next to the source file.
• Knowledge-base sync — list a folder on a schedule, embed each file with OpenAIEmbeddingTask, store the vectors in your own index.
• Transcript archival — at the end of a voice-call Session, GoogleDriveUploadFileTask writes the transcript into a per-customer folder.
• Daily exports — a Process started by the Scheduler Module's ScheduleRecurring event that builds a CSV and uploads it with MIME Type text/csv.

Quick start

1. In Google Cloud Console → IAM & Admin → Service Accounts, create a service account. Note the email (name@project.iam.gserviceaccount.com).
2. Open the service account → Keys → Add Key → Create new key → JSON. A JSON file downloads — keep it.
3. Enable the Google Drive API for the project under APIs & Services → Library.
4. Decide which Drive content the Process should reach:
   • Personal / shared folders — open the folder in Drive, click Share, and grant the service-account email Editor (or Viewer if read-only).
   • Whole Workspace domain — on the service account, open Details → Show Domain-wide Delegation → Enable. Copy the Client ID. In Google Workspace Admin Console → Security → Access and data control → API controls → Domain-wide Delegation, add the Client ID with scope https://www.googleapis.com/auth/drive.
5. Open the Google Drive Module's Environment configuration for the Environment you deploy to. Paste the entire JSON file contents into Service Account JSON Key. For domain-wide delegation, fill in Impersonate User Email with the Workspace user the Module should act as.
6. In the Process Editor, drop a Task and convert it to one of the Google Drive Tasks below.
7. Wire the Task's templated fields ({var} placeholders) to Session variables produced earlier in the Process.
8. Deploy. The Module checks the Drive credentials at deploy time and reports the result in the deploy log — you'll see "Service-account credentials valid" or a specific error before the Process ever runs.

Done.

How it works

Authentication model

This Module uses service-account auth: a long-lived JSON key presented to Google with every request. There is no per-user OAuth consent step — the Module acts on behalf of the project, not a logged-in user.

Two access patterns:

• Direct sharing — leave Impersonate User Email blank. The Module acts as the service account itself. It sees only files explicitly shared with the service-account email (or files it created). Files uploaded by the Module live in the service account's own Drive quota (15 GB) and are owned by the service account. This works for any Drive (personal Gmail, Workspace, mixed).
• Domain-wide delegation — fill in Impersonate User Email. The Module acts as that user: it sees exactly what the user sees, uploads land in the user's My Drive, and count against the user's quota. Works only for Google Workspace domains where an admin has granted the service account the drive scope under Domain-wide Delegation.

Pick direct sharing when one or two folders are involved and the cleanup story matters (revoke = unshare). Pick domain-wide delegation when the Process needs to behave as a real Workspace user (notifications, quotas, ownership audit trail).

Configuration

Configuration is per Environment — each Environment supplies its own service-account JSON credential. Credentials live on the Environment, never on the Module itself, so your Development and Production Environments can use different service accounts (and different Drive folders).

Field	Type	Required	Description
Service Account JSON Key	string	Yes	The full JSON key file for the service account, pasted verbatim.
Impersonate User Email	string	No	Workspace user to impersonate via domain-wide delegation. Default: empty (act as the service account itself).
Application Name	string	No	Label sent to Google with every request. Default: WorkflowEngine.

Service Account JSON Key

Required. The full JSON file generated under Google Cloud Console → IAM & Admin → Service Accounts → <your SA> → Keys → Add Key → Create new key → JSON. Paste the file's contents verbatim into the Module's Environment configuration — do not strip or rename fields.

Impersonate User Email

Optional. The Workspace user email to impersonate via domain-wide delegation. Leave blank to act as the service account itself. Requires that the service account's Domain-wide Delegation is enabled in Google Cloud and that an admin has authorized its Client ID with the https://www.googleapis.com/auth/drive scope under Workspace Admin → Security → API controls → Domain-wide Delegation.

Application Name

Free-text label sent to Google with each request. Useful for filtering this Module's requests in Google Cloud Console → APIs & Services → Metrics. Default: WorkflowEngine.

Limits

• Reads are capped at 10 MB per file — the platform enforces this ceiling regardless of the Max Bytes value on the Task.
• Uploads are capped at 10 MB per file — larger payloads are rejected before contacting Drive.
• Listings return at most 10,000 files per run (the Max Results upper bound).

Tasks

All Google Drive Tasks are generic — they run identically on every Channel.

GoogleDriveListFilesTask (Generic)

Lists files visible to the service account (or impersonated user). Optionally restrict to a single folder and / or apply a Google Drive query string.

Properties

Property	Type	Required	Example	Description
Folder ID	string	No	1A2b3CdEfGhIjKlMnOpQrStUvWxYz	Restrict listing to children of this folder. Find it in the Drive URL after /folders/. Supports {variable} — interpolated values are quote-escaped automatically. Default: empty (list everything visible).
Query	string	No	mimeType='application/pdf' and modifiedTime > '2026-01-01'	Google Drive query syntax. Supports {variable}. If your query already constrains trashed, the Task does not add its own trashed = false clause. Power-user input — substituted {variable} values are not individually escaped. Default: empty.
Max Results	int	No	500	Total maximum number of files to return across all pages (1–10000). Default: 100.
Include Trashed	boolean	No	false	If on, files in the Drive trash are included. Default: off. Skipped when your Query already mentions trashed.
Include Shared Drives	boolean	No	false	If on, files from shared drives are included. Default: off — listing returns only My Drive files. Turning this on can return very large result sets if the service account has access to many shared drives.
Output Variable	string	Yes	driveFiles	Variable name (type: object). Receives an array of file records, each with Id, Name, MimeType, ModifiedTime, Size, Parents, WebViewLink.

Behavior

1. The Task resolves {variable} placeholders in Folder ID and Query from the Session data.
2. It queries Drive page by page until Max Results files are collected or no more files match.
3. It writes the result array to Output Variable; downstream Tasks can reference fields like {driveFiles[0].Id}.
4. When more files match than Max Results, the Task writes an informational audit row and the Process continues — increase Max Results or narrow the Query to recover the full set.

Failure modes: ModuleMissingConfiguration (no JSON key for this Environment), TaskInvalidData (Output Variable missing or malformed), ModuleException (Drive rejected the request — e.g. folder not shared with the service account).

Example

1. Configure Folder ID = 1A2b3CdEfGhIjKlMnOpQrStUvWxYz, Query = mimeType='application/pdf', Max Results = 100, Output Variable = pdfs.
2. When the Token reaches the Task, it lists the folder and finds 12 PDFs.
3. The Session now holds pdfs as an array of 12 records; a downstream Task reads {pdfs[0].Id} to fetch the first file.

GoogleDriveReadFileTask (Generic)

Reads a single file's content and writes it to a Session variable. Native Google Workspace files (Docs, Sheets, Slides) are exported via the chosen MIME type; everything else is downloaded raw.

Properties

Property	Type	Required	Example	Description
File ID	string	Yes	{pdfs[0].Id}	The Drive file ID. Find it in the Drive URL after /file/d/. Supports {variable}.
Read Mode	Text | Base64	No	Text	Text decodes the bytes as UTF-8 (use for text files). Base64 encodes raw bytes as base64 (use for binary files like PDFs / images). Default: Text.
Export MIME Type	string	No	text/csv	MIME type used when exporting native Google Workspace files. Default: text/plain. Other useful values: text/csv (Sheets), text/html, application/pdf, application/rtf. Ignored for non-native files.
Max Bytes	int	No	1048576	Cap on bytes read (1 byte to 10 MB). The download stops at this many bytes — larger files are truncated, not downloaded fully then trimmed. Default: 1048576 (1 MB). The platform enforces the 10 MB ceiling regardless of this value.
Output Variable	string	Yes	fileText	Variable name (type: string). Receives the content — a UTF-8 string in Text mode, a base64 string in Base64 mode.

Behavior

1. The Task resolves File ID from the Session data.
2. Native Google Workspace files are exported using Export MIME Type; all other files are downloaded as-is.
3. The content is written to Output Variable in the chosen Read Mode.
4. If the file is larger than Max Bytes, the content is truncated and the Task writes an informational audit row — the Process continues.

Failure modes: ModuleMissingConfiguration, TaskInvalidData (missing File ID or Output Variable, File ID resolves to a folder, or File ID resolves to a Drive shortcut — resolve to the target file ID first), ModuleException (file not found, no permission, export not supported for that MIME type).

Example

1. Configure File ID = {pdfs[0].Id}, Read Mode = Text, Max Bytes = 1048576, Output Variable = pdfText.
2. When the Token reaches the Task, it downloads the file's first 1 MB and UTF-8-decodes it.
3. The Session now holds pdfText; a downstream OpenAI Task can use Summarize: {pdfText} in its prompt.

GoogleDriveUploadFileTask (Generic)

Uploads content as a new Drive file and returns a record describing it. Supports both UTF-8 text uploads and binary uploads (via base64-encoded Content).

Properties

Property	Type	Required	Example	Description
File Name	string	Yes	transcript-{Id}.txt	Name to give the new file. Control characters and slashes are stripped automatically. Supports {variable}.
Folder ID	string	No	1A2b3CdEfGhIjKlMnOpQrStUvWxYz	Parent folder ID. Default: empty — uploads to the service account's root (or the impersonated user's root). Supports {variable}.
MIME Type	string	No	text/csv	MIME type stored on the file. Default: text/plain.
Write Mode	Text | Base64	No	Text	Text: Content is uploaded as UTF-8 bytes. Base64: Content is decoded from base64 before upload (use for binary files like PDFs / images). Default: Text.
Max Bytes	int	No	10485760	Cap on the decoded payload size (1 byte to 10 MB). Uploads exceeding this are rejected before contacting Drive. Default: 10485760 (10 MB — also the platform-enforced ceiling).
Content	string	Yes	{csv}	The content to upload — UTF-8 text in Text mode, base64-encoded in Base64 mode. Supports {variable}.
Output Variable	string	Yes	uploadedFile	Variable name (type: object). Receives a record for the new file with Id, Name, MimeType, ModifiedTime, Size, Parents, WebViewLink.

Behavior

1. The Task resolves {variable} placeholders in File Name, Folder ID, and Content.
2. In Base64 mode, Content is decoded to raw bytes first; malformed base64 fails the Task.
3. The file is created in Drive and a record describing it is written to Output Variable — downstream Tasks can use {uploadedFile.WebViewLink} to share a link.

Without Impersonate User Email, uploaded files are owned by the service account and consume its 15 GB quota. Enable domain-wide delegation so uploads land in a real user's Drive.

Failure modes: ModuleMissingConfiguration, TaskInvalidData (File Name empty after sanitization, missing Output Variable, payload exceeds Max Bytes, or Write Mode = Base64 with malformed input), ModuleInputEmpty (Content resolved empty), ModuleException (upload rejected by Drive — common cause: target folder not shared with the service account).

Example

1. Configure File Name = report-{Id}.csv, Folder ID = 1A2b3CdEfGhIjKlMnOpQrStUvWxYz, MIME Type = text/csv, Content = {csv}, Output Variable = uploadedFile.
2. When the Token reaches the Task with csv = "date,total\n2026-04-27,86.73", it creates report-7f3a….csv in the folder.
3. The Session now holds uploadedFile; an OutputTask can send Report ready: {uploadedFile.WebViewLink}.

warning

Not idempotent. A Process that retries this Task creates a duplicate file — Drive accepts duplicate names freely. If your Process retries, build idempotency around the upload (e.g. list the folder first by name and skip if already present).

Common recipes

Summarize every new PDF in a folder, daily

A scheduled Process lists a Drive folder each morning, reads a PDF, asks an AI model for a summary, and writes the summary back to Drive.

1. ScheduleRecurring (Scheduler Module) — Preset Daily, TimeOfDayUtc 06:00. Fires a fresh Session every morning.
2. GoogleDriveListFilesTask — Folder ID 1A2b3CdEfGhIjKlMnOpQrStUvWxYz, Query mimeType='application/pdf' and modifiedTime > '2026-01-01', Max Results 50, Output Variable pdfs.
3. GoogleDriveReadFileTask — File ID {pdfs[0].Id}, Read Mode Text, Output Variable pdfText.
4. OpenAIChatCompletionTask (OpenAI Module) — User Message Summarize this document in 5 bullet points: {pdfText}, output stored in summary.
5. GoogleDriveUploadFileTask — File Name {pdfs[0].Name}.summary.txt, Folder ID = your summaries folder, Content {summary}, Output Variable summaryFile.

Export a daily CSV report to Drive

A scheduled Process builds a CSV string with a script and uploads it as a dated file.

1. ScheduleRecurring (Scheduler Module) — Preset Daily, TimeOfDayUtc 03:00.

2. JSTask (JavaScript Module) — builds the CSV and a date stamp:

   context.today = new Date().toISOString().slice(0, 10);
   context.csv = 'date,total\n' + context.today + ',' + (context.total || 0);

3. GoogleDriveUploadFileTask — File Name report-{today}.csv, MIME Type text/csv, Content {csv}, Folder ID = your reports folder, Output Variable reportFile.

Best practices

1. Share the narrowest folder, not the whole Drive — grant the service-account email access to exactly the folders the Process needs; revoking access is then a one-click unshare.
2. Use domain-wide delegation for user-owned output — without it, uploads consume the service account's own 15 GB quota and are owned by the service account.
3. Constrain listings with a Query — mimeType='application/pdf' and modifiedTime > '2026-01-01' returns far fewer files than an unfiltered listing, and keeps you under Max Results.
4. Pick the right Read / Write Mode — Text for text files, Base64 for binary (PDFs, images); reading binary in Text mode produces garbled characters.
5. Plan for retries on upload — GoogleDriveUploadFileTask is not idempotent; list-then-skip if the Process may run twice.
6. Rotate keys deliberately — when you rotate the service-account key in Google Cloud, update the Service Account JSON Key in every Environment that uses it.

Troubleshooting

"Service Account JSON Key is not configured for this environment"

The Service Account JSON Key field is empty in the Module's Environment configuration for the Environment you deployed to. Paste the full JSON file (curly braces and all).

Deploy log: "Could not build Google Drive client from the saved Service Account JSON Key"

The pasted value is not valid service-account JSON. Open the file you downloaded from Google Cloud Console and verify the contents — the JSON must include type: "service_account", client_email, and private_key. Common cause: pasted only the private key block, or pasted an OAuth client config by mistake.

Google Drive rejected the request (404): File not found

The file or folder ID is correct as a string, but the credentials cannot see it.

• Direct sharing mode (no impersonation) — the file's owner has not shared it with the service-account email. Open the file in Drive, Share, paste the service-account email (...@project.iam.gserviceaccount.com), grant Viewer (read) or Editor (read + write).
• Domain-wide delegation mode — the impersonated user genuinely doesn't have access to that file. Verify by opening the file as that user in a browser.

Google Drive rejected the request (403): The user does not have sufficient permissions for this file

Read access is fine but the operation needs write access (e.g. upload into a folder shared as Viewer). Re-share with Editor.

Google Drive rejected the request (403): Request had insufficient authentication scopes

Domain-wide delegation is configured, but the admin authorized a smaller scope than https://www.googleapis.com/auth/drive. Re-add the scope in Workspace Admin → Security → API controls → Domain-wide Delegation.

GoogleDriveReadFileTask: File ID '...' refers to a folder, not a file

The File ID points at a Drive folder — folders have no content to read. Use GoogleDriveListFilesTask with Folder ID = that ID to enumerate the folder's children, then read a specific file from the result.

Google Drive rejected the request (400): Bad Request: Export only supports Google Docs

You set Export MIME Type but the target file is not a native Google Workspace file. Export MIME Type is ignored for non-native files, so this normally cannot happen — if you see it, contact support with the file's MIME type.

Result is truncated / "result truncated to N files"

GoogleDriveListFilesTask capped the result at Max Results. Increase Max Results (max 10000) or narrow the Query.

List returns nothing for shared-drive files

Include Shared Drives is off by default — listing returns only My Drive files. Turn it on to enumerate shared drives the service account has access to.

Read returns "File ID '...' is a Drive shortcut"

Drive shortcuts are pointers, not files; reading them returns no content. The error message includes the target file ID — pass that ID instead.

Read returns garbled characters

You're reading a binary file (PDF, image, archive) in Text mode. UTF-8 decoding mangles non-text bytes. Switch Read Mode to Base64 for binary files; the output is a base64 string that downstream Tasks can hand to an HTTP body, an upload, etc.

Uploaded file disappears or "you've used up your storage"

Service-account Drive storage is 15 GB by default and not pooled with your Workspace plan. Set Impersonate User Email so uploads land in a real user's Drive instead of the service account's quota.

Google Drive rejected the request (401): Invalid Credentials

The JSON key has been deleted or rotated in Google Cloud Console. Generate a new key on the service account and replace the Service Account JSON Key in the Module's Environment configuration.

Error codes

Code	Name	Description
3005	TaskInvalidData	A required field is empty, the Output Variable is malformed, or the File ID points at a folder or shortcut. See full details
4001	ModuleException	Google Drive rejected the request — the audit message contains the HTTP status code and Google's error text. See full details
4008	ModuleMissingConfiguration	The Service Account JSON Key is empty for this Environment, or the JSON is malformed. See full details
4009	ModuleInputEmpty	GoogleDriveUploadFileTask's Content resolved to an empty string. See full details
4013	ModuleLog	Informational entry written when a listing or read result is truncated — the Process continues. See full details

Required Google Cloud setup

• Project with Google Drive API enabled (APIs & Services → Library).
• Service account with a JSON key (IAM & Admin → Service Accounts → Keys).
• For domain-wide delegation: Domain-wide Delegation enabled on the service account, and the service account's Client ID authorized for https://www.googleapis.com/auth/drive in Workspace Admin → Security → API controls.