> For the complete documentation index, see [llms.txt](https://docs.kognitos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kognitos.com/legacy/legacy-experience/books/reference/googledocs.md).

# Google Docs

Procedures and concepts for the Google Docs integration.

{% hint style="info" %}
The following documentation is for **Google Docs v2.11.0** *(BDK)*.
{% endhint %}

## Overview

Google Docs provides collaborative document creation and editing with real-time synchronization across teams. This integration enables automated document generation, content management, and collaborative writing workflows. Enhance documentation processes and improve team collaboration on shared documents.

## Prerequisites

### 1. Required Books

The following Book(s) need to be added to your agent so it can learn and understand the automation procedures defined within them:

* **Google Docs**

#### How to Add the Book(s)

1. Go to **Books** → **All Books**.
2. Search for the name of the book and click on it.
3. Click on <kbd>**Install**</kbd> or <kbd>**Add Connection**</kbd> to add the book to your agent.
4. If adding a connection, you'll be prompted for [**connectivity**](#connectivity) details.

## Connectivity

This section outlines the available methods for connecting to the Book, along with the required configuration details for each.

### Connect using Client Email, Token URI and Private Key

Gets the credentials from the service account keys.

| Label        | Description                                                                     | Type        |
| ------------ | ------------------------------------------------------------------------------- | ----------- |
| Client Email | The client email of the service account registered in the Google Cloud Console. | `text`      |
| Token URI    | The token URI of the Google Cloud Console.                                      | `text`      |
| Private Key  | The private key of the service account registered in the Google Cloud Console.  | `sensitive` |

## Procedures

### to add a paragraph to a (document)

Add a new paragraph to the end of a document.

**Input Concepts**

| Concept                                    | Description                          | Type                                                                  | Required | Default Value |
| ------------------------------------------ | ------------------------------------ | --------------------------------------------------------------------- | -------- | ------------- |
| [`document`](#google-drive-file-reference) | The file to add the paragraph to.    | `google drive file reference`                                         | Yes      | (no default)  |
| `text`                                     | The new paragraph text.              | `text`                                                                | Yes      | (no default)  |
| `style`                                    | Optional. The new paragraph's style. | `enum[HEADING_1, HEADING_2, HEADING_3, NORMAL_TEXT, SUBTITLE, TITLE]` | No       | (no default)  |

**Output Concepts**

| Concept                                    | Description                    | Type                          |
| ------------------------------------------ | ------------------------------ | ----------------------------- |
| [`document`](#google-drive-file-reference) | The document's file reference. | `google drive file reference` |

**Examples**

Add a heading to a document

```generic
add a paragraph to the document where
    the text is "New paragraph"
    the style is "HEADING_1"
```

### to batch update document

Apply raw Google Docs batch update requests to a document.

**Input Concepts**

| Concept                                    | Description                                                     | Type                          | Required | Default Value |
| ------------------------------------------ | --------------------------------------------------------------- | ----------------------------- | -------- | ------------- |
| [`document`](#google-drive-file-reference) | The Google Docs document to update.                             | `google drive file reference` | Yes      | (no default)  |
| `requests json`                            | A JSON array of Google Docs batchUpdate requests.               | `text`                        | Yes      | (no default)  |
| `write control json`                       | Optional. A JSON object with Google Docs writeControl settings. | `text`                        | No       | (no default)  |

**Output Concepts**

| Concept                                  | Description                     | Type                          |
| ---------------------------------------- | ------------------------------- | ----------------------------- |
| [`answer`](#google-drive-file-reference) | The updated document reference. | `google drive file reference` |

**Examples**

Apply a raw batch update request

```generic
batch update the document where
    the requests json is "[{"replaceAllText": {"containsText": {"text": "old", "matchCase": true}, "replaceText": "new"}}]"
```

### to create a google document in a (folder)

Creates a new Google Docs document.

**Input Concepts**

| Concept                                    | Description                                       | Type                            | Required | Default Value |
| ------------------------------------------ | ------------------------------------------------- | ------------------------------- | -------- | ------------- |
| `name`                                     | The name for the new Google Docs document.        | `text`                          | Yes      | (no default)  |
| [`folder`](#google-drive-folder-reference) | The folder to create the Google Docs document in. | `google drive folder reference` | No       | (no default)  |

**Output Concepts**

| Concept                                  | Description                        | Type                          |
| ---------------------------------------- | ---------------------------------- | ----------------------------- |
| [`folder`](#google-drive-file-reference) | the new document's file reference. | `google drive file reference` |

**Examples**

Create a Google Docs document called "Hello World" in a folder

```generic
create a google document in the folder where
    the name is "Hello World"
```

### to find a (document text range) in a document

Find the index range of exact text in a document.

**Input Concepts**

| Concept                                    | Description                                                                         | Type                          | Required | Default Value |
| ------------------------------------------ | ----------------------------------------------------------------------------------- | ----------------------------- | -------- | ------------- |
| [`document`](#google-drive-file-reference) | The Google Docs document to inspect.                                                | `google drive file reference` | Yes      | (no default)  |
| `text`                                     | The exact text to find.                                                             | `text`                        | Yes      | (no default)  |
| `occurrence index`                         | Optional. The zero-based occurrence to return when the text appears multiple times. | `number`                      | No       | 0             |
| `match case`                               | Optional. Whether the match should be case sensitive.                               | `boolean`                     | No       | True          |

**Output Concepts**

| Concept                                     | Description                               | Type                |
| ------------------------------------------- | ----------------------------------------- | ------------------- |
| [`document text range`](#google-docs-range) | The index range where the text was found. | `google docs range` |

**Examples**

Find text in a document

```generic
find a document text range in the document where
    the text is "Customer Name"
```

### to get a (document paragraph) from a document

Resolve the paragraph containing a document index.

**Input Concepts**

| Concept                                    | Description                                    | Type                          | Required | Default Value |
| ------------------------------------------ | ---------------------------------------------- | ----------------------------- | -------- | ------------- |
| [`document`](#google-drive-file-reference) | The Google Docs document to inspect.           | `google drive file reference` | Yes      | (no default)  |
| `index`                                    | The document index contained in the paragraph. | `number`                      | Yes      | (no default)  |

**Output Concepts**

| Concept                                        | Description                          | Type                    |
| ---------------------------------------------- | ------------------------------------ | ----------------------- |
| [`document paragraph`](#google-docs-paragraph) | The paragraph containing that index. | `google docs paragraph` |

**Examples**

Get the paragraph containing an index

```generic
get a document paragraph from the document where
    the index is 10
```

### to get a (document) from *docs*

Get the full Google Docs document.

**Input Concepts**

| Concept                                    | Description                           | Type                          | Required | Default Value |
| ------------------------------------------ | ------------------------------------- | ----------------------------- | -------- | ------------- |
| [`document`](#google-drive-file-reference) | The Google Docs document to retrieve. | `google drive file reference` | Yes      | (no default)  |

**Output Concepts**

| Concept                             | Description                   | Type                   |
| ----------------------------------- | ----------------------------- | ---------------------- |
| [`document`](#google-docs-document) | The full normalized document. | `google docs document` |

**Examples**

Get the full document

```generic
get a document from docs where
    the document is the document
```

### to get some (document comments) from a document

Get comments and replies for a Google Docs document.

**Input Concepts**

| Concept                                    | Description                                                  | Type                          | Required | Default Value |
| ------------------------------------------ | ------------------------------------------------------------ | ----------------------------- | -------- | ------------- |
| [`document`](#google-drive-file-reference) | The Google Docs document whose comments should be retrieved. | `google drive file reference` | Yes      | (no default)  |

**Output Concepts**

| Concept                                     | Description            | Type                  |
| ------------------------------------------- | ---------------------- | --------------------- |
| [`document comments`](#google-docs-comment) | The document comments. | `google docs comment` |

**Examples**

Get the document comments

```generic
get some document comments from the document
```

### to get some (document tables) from a document

Extract the table structures and cell text from a document.

**Input Concepts**

| Concept                                    | Description                          | Type                          | Required | Default Value |
| ------------------------------------------ | ------------------------------------ | ----------------------------- | -------- | ------------- |
| [`document`](#google-drive-file-reference) | The Google Docs document to inspect. | `google drive file reference` | Yes      | (no default)  |

**Output Concepts**

| Concept                                 | Description                       | Type                |
| --------------------------------------- | --------------------------------- | ------------------- |
| [`document tables`](#google-docs-table) | The tables found in the document. | `google docs table` |

**Examples**

Get the document tables

```generic
get some document tables from the document
```

### to get some (document text blocks) from a document

Get the document paragraph text with document indexes.

**Input Concepts**

| Concept                                    | Description                          | Type                          | Required | Default Value |
| ------------------------------------------ | ------------------------------------ | ----------------------------- | -------- | ------------- |
| [`document`](#google-drive-file-reference) | The Google Docs document to inspect. | `google drive file reference` | Yes      | (no default)  |

**Output Concepts**

| Concept                                           | Description                                          | Type                     |
| ------------------------------------------------- | ---------------------------------------------------- | ------------------------ |
| [`document text blocks`](#google-docs-text-block) | The document text blocks with start and end indexes. | `google docs text block` |

**Examples**

Get the document text blocks

```generic
get some document text blocks from the document
```

### to insert a heading in a document

Insert a heading at the end of a document.

**Input Concepts**

| Concept                                    | Description                           | Type                                                                  | Required | Default Value                                                                  |
| ------------------------------------------ | ------------------------------------- | --------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------ |
| [`document`](#google-drive-file-reference) | The Google Docs document to update.   | `google drive file reference`                                         | Yes      | (no default)                                                                   |
| `text`                                     | The heading text.                     | `text`                                                                | Yes      | (no default)                                                                   |
| `style`                                    | Optional. The heading style to apply. | `enum[HEADING_1, HEADING_2, HEADING_3, NORMAL_TEXT, SUBTITLE, TITLE]` | No       | {'class\_name': 'ParagraphStyle', 'name': 'HEADING\_1', 'value': 'HEADING\_1'} |

**Output Concepts**

| Concept                                  | Description                     | Type                          |
| ---------------------------------------- | ------------------------------- | ----------------------------- |
| [`answer`](#google-drive-file-reference) | The updated document reference. | `google drive file reference` |

**Examples**

Insert a heading in a document

```generic
insert a heading in the document where
    the text is "Executive Summary"
    the style is "HEADING_1"
```

### to overwrite a document

Replace the main body content of a document.

**Input Concepts**

| Concept                                    | Description                            | Type                          | Required | Default Value |
| ------------------------------------------ | -------------------------------------- | ----------------------------- | -------- | ------------- |
| [`document`](#google-drive-file-reference) | The Google Docs document to overwrite. | `google drive file reference` | Yes      | (no default)  |
| `content`                                  | The new document body text.            | `text`                        | Yes      | (no default)  |

**Output Concepts**

| Concept                                  | Description                     | Type                          |
| ---------------------------------------- | ------------------------------- | ----------------------------- |
| [`answer`](#google-drive-file-reference) | The updated document reference. | `google drive file reference` |

**Examples**

Overwrite a document

```generic
overwrite the document where
    the content is "Hello world"
```

### to replace text in a document

Replace exact text everywhere it appears in a document.

**Input Concepts**

| Concept                                    | Description                                | Type                          | Required | Default Value |
| ------------------------------------------ | ------------------------------------------ | ----------------------------- | -------- | ------------- |
| [`document`](#google-drive-file-reference) | The Google Docs document to update.        | `google drive file reference` | Yes      | (no default)  |
| `old text`                                 | The exact text to replace.                 | `text`                        | Yes      | (no default)  |
| `replacement text`                         | The text that should replace the old text. | `text`                        | Yes      | (no default)  |

**Output Concepts**

| Concept                                  | Description                     | Type                          |
| ---------------------------------------- | ------------------------------- | ----------------------------- |
| [`answer`](#google-drive-file-reference) | The updated document reference. | `google drive file reference` |

**Examples**

Replace placeholder text in a document

```generic
replace text in the document where
    the old text is "{{customer_name}}"
    the replacement text is "Acme"
```

## Concepts

### Google drive file reference

Contains all information required to identify a file in Google Drive.

| Field Name                 | Description                   | Type           |
| -------------------------- | ----------------------------- | -------------- |
| `id`                       | The id of the file            | `text`         |
| `file_name`                | The name of the file          | `text`         |
| [`parents`](#list-of-text) | The ids of the parent folders | `list of text` |

### Google drive folder reference

Contains all information required to identify a folder in Google Drive.

| Field Name                 | Description                   | Type           |
| -------------------------- | ----------------------------- | -------------- |
| `id`                       | The id of the folder          | `text`         |
| `folder_name`              | The name of the folder        | `text`         |
| [`parents`](#list-of-text) | The ids of the parent folders | `list of text` |

### Google docs range

A range inside a Google document.

| Field Name    | Description                                | Type             |
| ------------- | ------------------------------------------ | ---------------- |
| `start_index` | The inclusive start index in the document. | `number`         |
| `end_index`   | The exclusive end index in the document.   | `number`         |
| `text`        | Optional text contained in the range.      | `optional[text]` |

### Google docs document

A normalized Google document.

| Field Name                             | Description                            | Type                                      |
| -------------------------------------- | -------------------------------------- | ----------------------------------------- |
| `id`                                   | The document identifier.               | `text`                                    |
| `title`                                | The document title.                    | `text`                                    |
| `revision_id`                          | Optional document revision identifier. | `optional[text]`                          |
| `text`                                 | The flattened document text.           | `optional[text]`                          |
| [`paragraphs`](#google-docs-paragraph) | The document paragraphs.               | `optional[list of google docs paragraph]` |
| [`tables`](#google-docs-table)         | The document tables.                   | `optional[list of google docs table]`     |

### Google docs paragraph

A paragraph extracted from a Google document.

| Field Name        | Description                                | Type             |
| ----------------- | ------------------------------------------ | ---------------- |
| `text`            | The paragraph text.                        | `text`           |
| `start_index`     | The inclusive start index in the document. | `number`         |
| `end_index`       | The exclusive end index in the document.   | `number`         |
| `paragraph_style` | Optional paragraph style name.             | `optional[text]` |

### Google docs table

A table extracted from a Google document.

| Field Name                       | Description            | Type                                      |
| -------------------------------- | ---------------------- | ----------------------------------------- |
| `start_index`                    | The table start index. | `number`                                  |
| `end_index`                      | The table end index.   | `number`                                  |
| [`rows`](#google-docs-table-row) | The table rows.        | `optional[list of google docs table row]` |

### Google docs comment

A Google document comment.

| Field Name                              | Description                             | Type                                          |
| --------------------------------------- | --------------------------------------- | --------------------------------------------- |
| `id`                                    | The comment identifier.                 | `text`                                        |
| `author`                                | The display name of the comment author. | `optional[text]`                              |
| `content`                               | The comment content.                    | `optional[text]`                              |
| `created_time`                          | When the comment was created.           | `optional[text]`                              |
| `modified_time`                         | When the comment was last modified.     | `optional[text]`                              |
| `resolved`                              | Whether the comment is resolved.        | `optional[boolean]`                           |
| [`replies`](#google-docs-comment-reply) | The replies to the comment.             | `optional[list of google docs comment reply]` |

### Google docs comment reply

A reply to a Google document comment.

| Field Name      | Description                           | Type             |
| --------------- | ------------------------------------- | ---------------- |
| `id`            | The reply identifier.                 | `text`           |
| `author`        | The display name of the reply author. | `optional[text]` |
| `content`       | The reply content.                    | `optional[text]` |
| `created_time`  | When the reply was created.           | `optional[text]` |
| `modified_time` | When the reply was last modified.     | `optional[text]` |

### Google docs text block

A text block extracted from a Google document.

| Field Name        | Description                                | Type             |
| ----------------- | ------------------------------------------ | ---------------- |
| `text`            | The text content.                          | `text`           |
| `start_index`     | The inclusive start index in the document. | `number`         |
| `end_index`       | The exclusive end index in the document.   | `number`         |
| `paragraph_style` | Optional paragraph style name.             | `optional[text]` |