> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runalloy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Docs

> Integration details and setup guide for the Google Docs connector in Alloy Automation.

## Pre-Built Tooling

| Category                            | Details                                                                                                                                                                                                                                                                                                                                                              |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authentication**                  | OAuth 2.0 (Authorization Code with refresh tokens)                                                                                                                                                                                                                                                                                                                   |
| **Two-Way Sync**                    | Yes                                                                                                                                                                                                                                                                                                                                                                  |
| **Events Supported**                | No                                                                                                                                                                                                                                                                                                                                                                   |
| **Realtime**                        | Polling                                                                                                                                                                                                                                                                                                                                                              |
| **Supports Rate Limiting**          | Yes (Google API quotas & 429 handling)                                                                                                                                                                                                                                                                                                                               |
| **Authentication Scopes Supported** | `https://www.googleapis.com/auth/documents` (read-write access), `https://www.googleapis.com/auth/documents.readonly`, `https://www.googleapis.com/auth/drive`, `https://www.googleapis.com/auth/drive.readonly`, `https://www.googleapis.com/auth/drive.file`, `https://www.googleapis.com/auth/userinfo.email`, `https://www.googleapis.com/auth/userinfo.profile` |

***

## Objects Supported

Alloy Automation supports syncing the following objects from **Google Docs**:

* **Documents**
* **Text Content**
* **Text Styles** (formatting)
* **Paragraphs**
* **Tables**
* **Images**
* **Lists**

***

## Set Up Guide

### Trial Access

| Question                                           | Answer                                                                                                                                                                                                                   |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Offers free trial?**                             | Yes. Create a free Google account at [https://accounts.google.com/signup](https://accounts.google.com/signup) and set up a Google Cloud project at [https://console.cloud.google.com](https://console.cloud.google.com). |
| **Requires paid sandbox**                          | No paid sandbox required.                                                                                                                                                                                                |
| **Requires partnership to obtain authentication?** | No. However, Google App Verification may be required in production for sensitive scopes, which can add review time.                                                                                                      |

***

### Authentication (OAuth 2.0)

For customers who want to completely whitelabel their OAuth experience, you can provide your own developer keys instead of using Alloy Automation's.

#### Create your OAuth app (Google Cloud Console)

1. Go to **Google Cloud Console** ([https://console.cloud.google.com](https://console.cloud.google.com)) → **APIs & Services** → **Credentials**.
2. Create an **OAuth client ID** (application type: *Web application*).
3. Add the redirect URI: [https://api.runalloy.com/api/strategy/connector/googleDocs/callback](https://api.runalloy.com/api/strategy/connector/googleDocs/callback)
4. Enable the **Google Docs API** for your project (APIs & Services → Library).
5. Configure the scopes you intend to request:
   * `https://www.googleapis.com/auth/documents` (full read-write access)
   * `https://www.googleapis.com/auth/documents.readonly` (read-only access)
   * `https://www.googleapis.com/auth/drive` or `https://www.googleapis.com/auth/drive.file` (required for listing documents)
   * `https://www.googleapis.com/auth/userinfo.email`
   * `https://www.googleapis.com/auth/userinfo.profile`
6. Copy your **Client ID** and **Client Secret** into Alloy Automation.

#### Consent screen & verification

* Set up the **OAuth consent screen** with your app details and domain.
* For production use or external users, complete **Google app verification** (may require demo video, privacy policy, and domain ownership).

***

## Use Cases

### 1) Automated document generation from templates

Generate personalized documents (contracts, reports, proposals) by duplicating templates and programmatically inserting dynamic content like customer names, dates, and transaction details.

### 2) Document content extraction and indexing

Extract text content from Google Docs for search indexing, compliance archiving, content migration, or feeding into analytics and machine learning pipelines.

### 3) Collaborative document workflows

Build approval workflows where documents are created, reviewed, and updated programmatically based on business logic, with automatic text insertions for comments, updates, or status changes.

### 4) Document formatting automation

Apply consistent formatting, styles, and branding to documents at scale by programmatically updating text styles, paragraph formatting, and document structure across multiple documents.

### 5) Cross-platform document synchronization

Sync document content between Google Docs and other systems (CMS, databases, project management tools) to maintain a single source of truth for documentation.

***

## API Gotchas

* ⚠️ **Index-based operations:** Google Docs API uses character-based indexes (UTF-16 code units) for all text operations. Inserting or deleting text shifts all subsequent indexes, so plan your batch operations carefully. Process operations from end-to-beginning to avoid index shifts.

* ⚠️ **Batch update request order:** When using `batchUpdate`, requests are processed sequentially in the order they appear in the array. Each request affects the document state for subsequent requests, so order matters significantly.

* ⚠️ **Read before write pattern:** Always read the document's current revision ID before making updates. Include the revision ID in your update request to detect conflicts if the document was modified by another client.

* ⚠️ **Listing documents requires Drive API:** The Docs API doesn't have a "list documents" endpoint. You must use the Google Drive API with the MIME type `application/vnd.google-apps.document` to discover documents.

* ⚠️ **Complex formatting limitations:** While you can apply basic text formatting (bold, italic, fonts, colors), more complex formatting like comments, suggestions, and track changes have limited API support. Some visual elements must be managed through the UI.

* ⚠️ **Segment IDs for headers/footers:** Documents are divided into segments (body, headers, footers). When inserting content into headers or footers, you must specify the correct `segmentId`. An empty or missing segment ID defaults to the document body.

> For questions or troubleshooting, contact **[support@runalloy.com](mailto:support@runalloy.com)**.