Google Tasks ExecModule

Overview

GoogleTasksModule connects ValkyrAI workflows to Google Tasks API v1. It uses the native map I/O ExecModule ABI, appears in the annotation-backed Workflow Studio catalog as GoogleTasksModule, and resolves OAuth credentials only from an IntegrationAccount.

The connector implements the highest-value task and task-list behavior from n8n's Google Tasks node while adding governed placement and cleanup operations:

• list_task_lists
• get_task_list
• list_tasks
• get_task
• create_task
• update_task
• move_task
• clear_completed
• delete_task

The Google Tasks API origin and OAuth token cannot be overridden by workflow input.

Usage

1. Enable Google Tasks API in the Google Cloud project that owns the OAuth client.
2. Authorize the minimum Tasks OAuth scope required by the workflow.
3. Store the current OAuth access token in a Google IntegrationAccount SecureField.
4. Add GoogleTasksModule to a workflow and bind that account through ExecModuleConfig.authConfig.integrationAccount.
5. Set operation and the operation-specific fields in module configuration or map them from upstream workflow state.

Mapped workflow input can override non-secret task fields. Authentication, the Google API host, retry safety, response limits, and destructive confirmations remain trusted module behavior.

Inputs

Name	Type	Required for	Default	Constraints
operation	string	Every execution	None	One of the nine documented operations.
taskListId	string	Task-list read and every task operation	None	1–256 Google ID characters.
taskId	string	get_task, update_task, move_task, delete_task	None	1–256 Google ID characters.
title	string	create_task; optional for update_task	None	1–1,024 characters when supplied.
notes	string	Optional create/update field	None	Up to 8,192 characters; an empty update clears notes.
due	string	Optional create/update field	None	RFC 3339 timestamp; an empty update clears the field.
completed	string	Optional create/update field	None	RFC 3339 completion timestamp.
taskStatus	string	Optional create/update field	None	needsAction or completed.
parentId	string	Optional create/move placement	None	Parent task ID; move_task requires this or previousId.
previousId	string	Optional create/move placement	None	Previous sibling task ID.
completedMin / completedMax	string	Optional list_tasks filters	None	RFC 3339 timestamps.
dueMin / dueMax	string	Optional list_tasks filters	None	RFC 3339 timestamps.
updatedMin	string	Optional list_tasks filter	None	RFC 3339 timestamp.
showCompleted	boolean	Optional list_tasks filter	true	Google may require showHidden=true for some completed tasks.
showDeleted	boolean	Optional list_tasks filter	false	Includes deletion tombstones when authorized.
showHidden	boolean	Optional list_tasks filter	false	Includes tasks hidden by clear-completed behavior.
pageToken	string	Optional list resume point	None	Opaque; maximum 4,096 characters.
limit	integer	Optional list bound	100	1–10,000; provider pages are at most 100 items.
returnAll	boolean	Optional list behavior	false	Continues pagination, safety-capped at 10,000 items.
confirmClear	boolean	clear_completed	false	Must be true because completed tasks become hidden.
confirmDelete	boolean	delete_task	false	Must be true because deletion is permanent.

Outputs

Every execution returns stable status, operation, and attempts fields.

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation name.
attempts	integer	Always	Provider HTTP attempts.
httpStatus	integer	Provider response received	Last Google Tasks HTTP status.
data	object	Single-resource or mutation success	Normalized Google task-list/task response; empty for HTTP 204.
id	string	Provider resource contains an ID	Convenience task or task-list ID.
title	string	Provider resource contains a title	Convenience title.
taskStatus	string	Task resource contains a task status	Google task state; the top-level execution status remains authoritative.
due	string	Task resource contains a due date	Provider RFC 3339 due value.
updated	string	Provider resource contains update time	Provider RFC 3339 update value.
items	array	List success	Bounded task lists or tasks.
count	integer	List success	Number of returned items.
hasMore	boolean	List success	Whether Google returned another page token.
nextPageToken	string	Another page exists	Opaque token for a later execution.
requestId	string	Google supplies one	Provider request reference for support.
error	object	Failure	Safe {code, message, httpStatus?, retryable} details.

OAuth tokens are never returned. Provider errors are bounded and redacted through the shared workflow sensitive-data policy.

IntegrationAccount Requirements

Setting	Requirement
Provider	Google Tasks / Google Workspace
Auth mechanism	OAuth 2.0 bearer access token
accountName	Human-readable Google account or Workspace label
apiKey	Preferred encrypted SecureField containing the access token
password	Legacy token fallback only; prefer apiKey
status	ready or an unset legacy status; closed and error fail closed

Use the minimum applicable scope:

• Read-only task discovery: https://www.googleapis.com/auth/tasks.readonly (scope guidance)
• Create, update, move, clear, or delete: https://www.googleapis.com/auth/tasks (scope guidance)

Never place tokens in parameters, mapped workflow input, examples, logs, or outputs. Use the platform OAuth refresh flow to rotate expired access tokens.

Configuration

Module-specific fields belong in ExecModulePayloadConfig.parameters; retries and timeouts use existing normalized configuration groups.

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:google-tasks-primary"
  },
  "retryPolicy": {
    "maxAttempts": 3,
    "backoffStrategy": "EXPONENTIAL",
    "initialDelayMs": 1000,
    "maxDelayMs": 60000,
    "jitter": false
  },
  "executionConfig": {
    "timeoutMs": 30000
  },
  "payloadConfig": {
    "parameters": "{\"operation\":\"list_tasks\",\"taskListId\":\"launch-list-id\",\"showCompleted\":false,\"limit\":250}"
  }
}

The integrationAccount value is illustrative. Persisted workflows use the generated relationship, never a plaintext token.

Operations

Operation	Provider behavior	Side effect and retry behavior
list_task_lists	Lists task lists visible to the authorized principal.	Read-only; retries transient failures and paginates.
get_task_list	Reads one task list by ID.	Read-only; retries transient failures.
list_tasks	Lists bounded tasks with completion, due, update, deletion, and hidden filters.	Read-only; retries and follows nextPageToken.
get_task	Reads one task by list ID and task ID.	Read-only; retries transient failures.
create_task	Creates a task, optionally positioned below a parent or sibling.	Write; single attempt because an ambiguous response may have committed.
update_task	Patches supplied title, notes, due, completion, or status fields.	Write; single attempt; empty notes/due can clear fields.
move_task	Moves a task relative to a parent or previous sibling.	Write; single attempt; requires explicit placement.
clear_completed	Hides completed tasks from the selected task list.	Destructive visibility change; requires confirmClear=true; single attempt.
delete_task	Permanently deletes one task.	Irreversible; requires confirmDelete=true; single attempt.

Errors and Failure Modes

Code	Typical cause	Retryable	Resolution
VALIDATION_ERROR	Missing/invalid IDs, timestamp, operation field, placement, or confirmation.	No	Correct inputs; no unsafe request was sent.
UNSUPPORTED_OPERATION	Unknown operation name.	No	Select a documented operation.
INTEGRATION_ACCOUNT_REQUIRED	No account is bound.	No	Bind a Google Tasks IntegrationAccount.
INTEGRATION_ACCOUNT_NOT_READY	Account is closed or in error.	No	Reconnect or repair the account.
GOOGLE_TASKS_HTTP_401	OAuth token is expired or invalid.	No	Refresh the token.
GOOGLE_TASKS_HTTP_403	Scope/resource access is missing, or a quota was exceeded.	Depends on reason	Grant scope/access; rate-limit reasons retry only for reads.
GOOGLE_TASKS_HTTP_404	Task-list or task ID is wrong or invisible.	No	Verify the ID and authorized principal.
GOOGLE_TASKS_HTTP_429	Request quota exceeded.	Yes for reads	Honor provider guidance and retry later.
RESPONSE_TOO_LARGE	Response exceeded 5 MiB.	No	Narrow filters or lower limit.
NETWORK_ERROR	DNS, TLS, timeout, or connectivity failure.	Yes for reads	Verify connectivity and retry.
INVALID_PROVIDER_RESPONSE	Google returned a non-list items value.	No	Capture request ID and check API compatibility.

Example

Create an agent-owned release verification task:

{
  "operation": "create_task",
  "taskListId": "MTIzNDU2Nzg5",
  "title": "Verify public ExecModule launch evidence",
  "notes": "Confirm production docs, article, header image, and anonymous READ ACLs.",
  "due": "2026-08-15T00:00:00Z",
  "taskStatus": "needsAction"
}

Expected result shape:

{
  "status": "success",
  "operation": "create_task",
  "attempts": 1,
  "httpStatus": 200,
  "id": "QUJDREVGR0g",
  "title": "Verify public ExecModule launch evidence",
  "data": {
    "id": "QUJDREVGR0g",
    "title": "Verify public ExecModule launch evidence",
    "status": "needsAction"
  }
}

Notes

• Pagination: list operations request at most 100 items per Google page, preserve opaque nextPageToken values, stop at limit, and hard-cap returnAll at 10,000 items.
• Rate limits: read operations retry HTTP 408/429/5xx and Google rateLimitExceeded, userRateLimitExceeded, or backendError reasons. Integer and RFC 1123 Retry-After values are honored. Writes are never automatically retried.
• API limits: Google Tasks stores due values with date semantics and may discard the time component even though the wire format is RFC 3339. Recurring tasks, reminders, assigned tasks, attachments, and event synchronization are controlled by Google product APIs outside this module.
• Idempotency: create, update, move, clear, and delete use one provider attempt. After a network timeout, reconcile the task list by ID/title and immutable task IDs before replaying.
• Ordering: parentId and previousId are provider-relative placement hints. A caller should read back the returned task to confirm final ordering.
• Destructive behavior: clear_completed hides completed tasks and requires confirmClear=true; delete_task is permanent and requires confirmDelete=true.
• External verification: local tests use a deterministic mock provider. Live Google behavior remains unverified until an authorized Google Tasks credential is supplied.
• Functional reference: n8n's current Google Tasks node supports task create, delete, get, list, and update with task-list selection, pagination, timestamps, status, parent, and previous-sibling fields. ValkyrAI adds explicit move/clear operations and stricter destructive, retry, and credential boundaries.