​
Overview

This guide demonstrates how to create an execution action that enables Glean Assistant to update Google Documents. You’ll learn how to configure the OpenAPI specification, set up OAuth authentication, and deploy the action for use within your organization.

Before proceeding, ensure you have:

  • Admin or app developer access to Glean
  • Access to Google Cloud Console
  • Familiarity with OAuth 2.0 authentication flows

​
Implementation Steps

1

Preparing the OpenAPI Specification

The first step involves creating a properly formatted OpenAPI specification that defines how Glean Assistant will interact with the Google Docs API. We’ll use the following endpoint:

POST https://docs.googleapis.com/v1/documents/{documentId}:batchUpdate

While Google doesn’t typically provide OpenAPI specs publicly, you can construct one using their documentation or reference third-party sources.

Here’s the complete OpenAPI specification:

openapi: 3.0.0
servers:
  - url: 'https://docs.googleapis.com/'
info:
  description: Writes Google Docs documents.
  title: Google Docs API
  version: v1
paths:
  '/v1/documents/{documentId}:batchUpdate':
    post:
      description: >-
        Applies one or more updates to the document. Each request is validated
        before being applied. If any request is not valid, then the entire
        request will fail and nothing will be applied. The updates in your request
        are guaranteed to be applied together atomically.
      operationId: docs.documents.batchUpdate
      parameters:
        - description: >-
            The ID of the document to update. Use glean search to find
            the relevant document. The documentId usually exists in the
            url of the doc. The syntax of URL (with documentId) is like:
            https://docs.google.com/document/d/<documentId>/edit
            Extract out the documentId from the URL.
          in: path
          name: documentId
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                requests:
                  type: array
                  maxItems: 2
                  items:
                    type: object
                    properties:
                      insertText:
                        description: >-
                          Inserts text at the specified location. Always use this
                          operation except when text deletion or text replacement
                          is required.
                        type: object
                        properties:
                          location:
                            type: object
                            properties:
                              index:
                                description: >-
                                  The zero-based index, in UTF-16 code units.
                                  Strictly use a value of 1 and nothing else.
                                format: int32
                                type: integer
                          text:
                            description: >-
                              The text to be inserted. This is the most important field
                              for this text inserting operation. Insert a neatly
                              formatted text consisting of multiple paragraphs. Whenever
                              required, always start with a new line for paragraphs,
                              tables, lists for neatness.
                            type: string
                      replaceAllText:
                        description: >-
                          Replaces all instances of the specified text.
                          Always use this operation when text deletion
                          or text replacement is required.
                        type: object
                        properties:
                          containsText:
                            type: object
                            properties:
                              matchCase:
                                description: >-
                                  Indicates whether the search should respect
                                  case: - `True`: the search is case sensitive.
                                  - `False`: the search is case insensitive.
                                type: boolean
                                title: Do you want to match case
                              text:
                                description: The text to search for in the document.
                                type: string
                          replaceText:
                            description: >-
                              The text that will replace the
                              matched text. Keep empty for deletion.
                            type: string
      responses:
        '200':
          description: Successful response
2

Creating the Action

Navigate to Admin console > Platform > Actions and create a new action from scratch.

​
Basic Information Configuration

Configure the following settings:

  • Display name: Choose a descriptive name (e.g., “Google Docs Updater”)
  • Description: Explain the action’s functionality
  • Unique identifier: Set a unique ID (e.g., “googleDocsUpdate”)
  • Action type: Select “Action” since this will modify documents

​
Trigger Condition Setup

In the trigger condition, provide comprehensive guidance for when Glean Assistant should use this action. Include:

  • Specific use cases that should trigger the action
  • Examples of appropriate user queries
  • Cases where the action should not be used

​
Functionality Configuration

Paste the OpenAPI specification you prepared in Step 1. Since we’re using Google’s API directly, leave the “Use existing on-premise server” option unchecked.

3

Setting Up Authorization

The action requires OAuth 2.0 authentication to interact with Google Docs securely.

​
Google Cloud Console Configuration

  1. Visit the Google Cloud Console Credentials page
  2. Create new OAuth 2.0 credentials:

  3. Select “Web Application” as the application type:

​
Redirect URI Configuration

Add the following redirect URI to your OAuth client configuration:

https://{your-glean-domain-name}-be.glean.com/tools/oauth/verify_code/{your-action-unique-identifier-name}

The unique identifier in the redirect URI must match exactly with the identifier you set when creating the action, including case sensitivity.

​
OAuth Settings in Glean

Configure these OAuth settings in the Authentication section:

Client URL: https://accounts.google.com/o/oauth2/auth?prompt=consent&access_type=offline
Authorization URL: https://accounts.google.com/o/oauth2/token
Scopes: https://www.googleapis.com/auth/documents

​
Enable Google Docs API

  1. Navigate to the Google Cloud Console
  2. Enable the Google Docs API for your project:

4

Testing and Deployment

After configuration, thoroughly test the action before deployment.

​
Testing Process

  1. Click the testing URL provided after saving the action
  2. Issue test queries to verify proper triggering
  3. Use the “Review and confirm” interface:

  4. Verify document changes:

    Before changes:

    After changes:

​
Deployment Configuration

Deploy the action through the deploy tab:

You can:

  • Enable the action for all teammates
  • Restrict access to specific teammates
  • Configure deployment settings for Chat or AI Apps integration

​
Implementation Guidelines

​
OpenAPI Specification Best Practices

When preparing your OpenAPI specification for Google Docs integration:

Field Descriptions

The quality of field descriptions significantly impacts Glean Assistant’s ability to populate them correctly. Consider these guidelines:

  • Make descriptions actionable and specific
  • Include examples of valid values
  • Explain the business context of each field
  • Clarify relationships between fields

Schema Structure

Your schema structure affects how Glean Assistant interprets the API:

  • Keep the schema as flat as possible
  • Use meaningful field names that reflect their purpose
  • Leverage built-in formats (like date-time) where applicable
  • Include proper type constraints and validations

​
Google Docs API Considerations

When working with the Google Docs API:

Document Operations

Choose the right operation type for your use case:

  • Use insertText for adding new content without affecting existing text
  • Use replaceAllText when you need to modify existing content
  • Consider using index: 1 for insertions to maintain consistent behavior
  • Handle formatting through plain text markers (like asterisks for bullets)

Error Handling

Common issues to watch for:

  • Document permissions mismatches
  • Rate limiting constraints
  • Invalid document IDs
  • Concurrent modification conflicts

​
Authentication Setup Tips

OAuth Configuration

Important considerations for OAuth setup:

  • Always use access_type=offline to enable refresh tokens
  • Include appropriate error handling for token expiration
  • Consider implementing token rotation for security
  • Monitor token usage and implement proper logging

​
Integration Best Practices

User Experience

Optimize the action for user interaction:

  • Provide clear feedback when the action is processing
  • Include meaningful error messages
  • Allow users to preview changes before applying them
  • Maintain consistent behavior across different document types

Performance Optimization

Ensure efficient operation:

  • Batch related operations when possible
  • Implement appropriate timeouts
  • Cache frequently used document metadata
  • Monitor action execution times

​
Common Pitfalls to Avoid

Watch out for these common implementation mistakes:

  1. Document ID Handling

    • Not properly extracting IDs from URLs
    • Failing to validate ID format
    • Not handling shared drive documents correctly

  2. Permission Issues

    • Insufficient OAuth scopes
    • Missing document-level permissions
    • Incorrect service account configuration

  3. Content Formatting

    • Ignoring existing document structure
    • Not handling special characters properly
    • Incorrect handling of line breaks and paragraphs

​
Testing Recommendations

Comprehensive Testing

Implement thorough testing across these scenarios:

  • Different document types and sizes
  • Various content modification patterns
  • Edge cases in text replacement
  • Multiple user permission levels
  • Concurrent access situations

​
Maintenance and Monitoring

Ongoing Operations

Establish these operational practices:

  • Regular OAuth credential rotation
  • Usage pattern monitoring
  • Error rate tracking
  • User feedback collection
  • Performance metric monitoring

​
Troubleshooting

If you encounter issues during setup or execution:

  1. Verify OAuth credentials are correctly configured
  2. Ensure the Google Docs API is enabled
  3. Check that the redirect URI exactly matches your action’s configuration
  4. Verify the user has appropriate permissions in both Glean and Google Docs

​
Next Steps

After successful implementation, consider:

  • Creating documentation for end users
  • Setting up monitoring for action usage
  • Establishing a process for maintaining OAuth credentials
  • Planning for periodic reviews of API specifications as the Google Docs API evolves

Was this page helpful?

Suggest editsRaise issue