Google Docs¶

Overview¶

The Google Docs task integrates BaseCloud CRM with Google Docs API v1, enabling automated document creation, content retrieval, and dynamic updates for proposal generation, contract management, and report automation.

Key Features:

• 3 Actions: Create documents, retrieve content, update documents
• OAuth 2.0 Authentication: Secure Google integration with automatic token refresh
• Folder Organization: Create documents in specific Google Drive folders
• Content Modes: Append, prepend, or replace document content
• Plain Text Extraction: Extract readable text from structured Docs format
• Template System: Dynamic document generation with variable replacement

Use Cases:

• Automated proposal generation from CRM data
• Contract creation with client information
• Daily/weekly report compilation
• Meeting notes automation
• Document template processing
• Content aggregation from multiple sources

Prerequisites¶

1. Google Cloud Project¶

Setup Google Cloud:

1. Go to https://console.cloud.google.com
2. Create new project or select existing
3. Enable Google Docs API
4. Enable Google Drive API (required for folder management)
5. Create OAuth 2.0 credentials:
6. Application type: Web application
7. Authorized redirect URIs: https://yourapp.basecloudglobal.com/oauth/callback
8. Note Client ID and Client Secret

2. OAuth Configuration in BaseCloud¶

Create App Connection:

1. Navigate to BaseCloud CRM → Settings → App Connections
2. Click + New App Connection
3. Select Google Docs from dropdown
4. Enter credentials:
5. Client ID: From Google Cloud Console
6. Client Secret: From Google Cloud Console
7. Click Authorize with Google
8. Authorize scopes:
9. https://www.googleapis.com/auth/documents - Read/write documents
10. https://www.googleapis.com/auth/drive.file - Manage created files
11. Grant access to Google account
12. Save connection

OAuth Scopes Required:

https://www.googleapis.com/auth/documents
https://www.googleapis.com/auth/drive.file

Note: drive.file scope only accesses files created/opened by the app, not entire Drive.

3. Google Drive Folder IDs (Optional)¶

Get Folder ID:

1. Open Google Drive: https://drive.google.com
2. Navigate to folder
3. Check URL: https://drive.google.com/drive/folders/{FOLDER_ID}
4. Copy folder ID after /folders/
5. Or right-click folder → Share → Copy link → Extract ID

Example Folder ID:

1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p

Connections live in Settings → App Connections, not on the task. Connect the app once and every task that needs it can use it. The badge on each tile says how it authenticates — OAuth2 sends you to the provider to sign in, API Key expects a key you paste in.

Outputs¶

Which fields appear depends on the action.

Reference fields as {{task_<ID>_<field>}}.

Always emitted¶

Configuration¶

Builder fields¶

The Field column is the label as it appears in the task builder; Key is the name the value is stored under and referenced by.

Action 1: create_document¶

Create new Google Document with optional initial content and folder placement.

Output Variables:

task_45001_run; // true/false
task_45001_run_text; // "Document \"Q1 Sales Proposal\" created successfully."
task_45001_document_id; // Google Docs document ID
task_45001_document_url; // Direct edit URL
task_45001_title; // Document title
task_45001_folder_id; // Parent folder ID (if specified)

How It Works:

1. Decides how to treat document_content (see Content Format below)
2. HTML content — uploads the markup to Drive as a converted document, so headings, tables, bold text, colours and inline styles become real formatting
3. Plain text content — creates a blank document via the Docs API, sets the title and inserts the text at index 1
4. If folder_id provided:
5. Moves document from root to specified folder via Drive API
6. Returns document ID and edit URL

The Document Content field is a rich-text editor in the automation builder — headings, tables, colours and variable chips are edited visually and saved as HTML. Pasting raw HTML still works; it renders in the editor rather than staying as visible tags.

Content Format:

The Docs API insertText request has no markup support — it writes the string exactly as given. HTML therefore goes through Drive's importer instead, which converts <h1>, <table>, <strong>, inline style attributes, colours and font sizes into document formatting. Script tags, external CSS files and JavaScript are dropped by the converter.

API Endpoints:

POST https://docs.googleapis.com/v1/documents
POST https://docs.googleapis.com/v1/documents/{documentId}:batchUpdate
POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart  (HTML content)
PATCH https://www.googleapis.com/drive/v3/files/{documentId}

Document URL Format:

https://docs.google.com/document/d/{documentId}/edit

Use Cases:

• Create proposal from template text
• Generate contract with client details
• Initialize daily report document
• Create meeting notes with agenda

Action 2: get_document¶

Retrieve document content and metadata, with plain text extraction.

Output Variables:

task_45001_run; // true/false
task_45001_run_text; // "Document retrieved successfully."
task_45001_document_id; // Document ID
task_45001_document_url; // Edit URL
task_45001_title; // Document title
task_45001_plain_text; // Extracted plain text content
task_45001_content; // Raw Google Docs structure array

Plain Text Extraction:

• Recursively extracts text from document structure
• Handles paragraphs, headings, lists
• Extracts text from tables (preserves table structure with newlines)
• Removes formatting (bold, italic, links)
• Preserves paragraph breaks
• Suitable for AI analysis or text processing

How It Works:

1. Fetches complete document via Docs API
2. Extracts title and document ID
3. Recursively processes content structure:
4. Paragraphs → Extract text from elements
5. Tables → Extract from rows/cells
6. Nested structures → Recursive extraction
7. Returns both plain text and raw structure

API Endpoint:

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

Use Cases:

• Extract document for AI analysis
• Parse document for workflow decisions
• Copy content to other systems
• Archive document text
• Search document content

Action 3: update_document¶

Modify document content with three update modes: append, prepend, or replace.

Update Modes:

Output Variables:

task_45001_run; // true/false
task_45001_run_text; // "Document updated successfully (append)."
task_45001_document_id; // Document ID
task_45001_document_url; // Edit URL

How It Works:

Append Mode:

1. Fetches current document to get end index
2. Inserts text at end index
3. Prepends newline for separation

Prepend Mode:

1. Inserts text at index 1 (beginning)
2. Appends newline after inserted text

Replace Mode:

1. Fetches current document for indices
2. Deletes all content (index 1 to end-1)
3. Inserts new content at index 1
4. Completely overwrites document

API Endpoint:

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

Batch Update Request (Replace Example):

{
  requests: [
    {
      deleteContentRange: {
        range: {
          startIndex: 1,
          endIndex: 1249, // Current document end - 1
        },
      },
    },
    {
      insertText: {
        location: { index: 1 },
        text: 'Completely new content...',
      },
    },
  ];
}

Document Index Structure:

• Index 0: Reserved (document start)
• Index 1: First insertable position (mandatory newline)
• Index N-1: Last character
• Index N: End of document (mandatory trailing newline)

Use Cases:

• Append: Daily logs, incremental reports, adding sections
• Prepend: Executive summaries, document headers, priority updates
• Replace: Template processing, report regeneration, complete refresh

Real-World Examples¶

Generate a proposal from a template¶

CRM Trigger  (status changed to "Proposal")
  └─ Match to Client   look the client up
      └─ Google Docs   create the document from a template
          └─ Email     send the link

Keep a shared document up to date¶

Schedule
  └─ Google Docs   update the document's content

Capture meeting notes against a client¶

Form Submission
  └─ Match to Client   look the client up
      └─ Google Docs   append the notes to the client's document

Troubleshooting¶

Error: "No app connection selected"¶

Cause: OAuth connection not configured

Solutions:

1. Go to Settings → App Connections
2. Create Google Docs connection
3. Enter Client ID and Client Secret
4. Complete OAuth authorization
5. Grant both Docs and Drive scopes

Error: "Invalid OAuth 2.0 Access Token"¶

Cause: Access token expired (refresh failed)

Solutions:

1. BaseCloud automatically refreshes tokens
2. If error persists, re-authorize connection:
3. Settings → App Connections → Edit
4. Click Re-authorize with Google
5. Verify OAuth scopes are correct:
6. https://www.googleapis.com/auth/documents
7. https://www.googleapis.com/auth/drive.file

Error: "Document not found" (404)¶

Cause: Invalid document ID or no access

Solutions:

1. Verify document ID format (no spaces, special chars)
2. Check document hasn't been deleted
3. Ensure OAuth account has access to document
4. Only works with documents created by app or explicitly shared
5. Test with known working document ID

Error: "Insufficient permissions"¶

Cause: Missing OAuth scopes or Drive permissions

Solutions:

1. Verify OAuth scopes granted:
2. Documents scope for read/write
3. Drive scope for folder management
4. Re-authorize with all scopes
5. Check document sharing settings
6. Ensure account has edit access to document

Folder Move Failed¶

Cause: Invalid folder ID or permission issue

Solutions:

1. Verify folder ID format (long alphanumeric string)
2. Check folder exists in Google Drive
3. Ensure OAuth account has access to folder
4. Test folder ID in Drive URL: drive.google.com/drive/folders/{ID}
5. Omit folder_id to keep in root Drive

Document Content Empty or Malformed¶

Cause: Content formatting or structure issue

Solutions:

1. Content must be plain text (no HTML)
2. Use \n for line breaks (double backslash in JSON)
3. Escape special characters in variables
4. Check variable substitution completed
5. Test with simple static text first

Update Mode Not Working as Expected¶

Cause: Misunderstanding mode behavior

Solutions:

1. Append: Adds to end (doesn't create new paragraph automatically - add \n\n)
2. Prepend: Adds to beginning (add \n\n after for spacing)
3. Replace: Deletes everything and inserts new content
4. Document always has mandatory newlines at start/end
5. Test with simple document first

Rate Limiting / Quota Exceeded¶

Cause: Exceeded Google API quotas

Solutions:

1. Default Quotas:
2. 300 requests per minute per user

3. 60 requests per minute per project

4. Immediate Actions:

5. Add delays in document creation loops (1-2 seconds)
6. Reduce frequency of updates

7. Batch content updates instead of multiple small updates

8. Long-term:

9. Request quota increase in Google Cloud Console
10. Implement exponential backoff
11. Cache document content locally
12. Use batch update requests

Plain Text Extraction Incomplete¶

Cause: Complex document structure

Solutions:

1. Extraction handles paragraphs and tables
2. Some elements may not extract (images, drawings)
3. Tables preserve basic structure with newlines
4. Formatting removed (bold, italic, colors)
5. For rich content, use raw content structure instead

Best Practices¶

Document Organization¶

1. Folder Structure:
2. Create dedicated folders per document type
3. Store folder IDs in variables for reuse
4. Use client-specific folders: /Clients/{{client_name}}/

5. Maintain folder ID mapping in database

6. Naming Conventions:

7. Include date: Report - 2024-02-08
8. Include client: Proposal - ABC Corp
9. Be descriptive: Q1 Sales Report - EMEA Region

10. Use consistent formatting across documents

11. Access Management:

12. Documents created by app connection
13. Share documents via Drive API or manually
14. Store document URLs in CRM for easy access
15. Use service account for organization-wide access

Content Strategy¶

1. Template Design:
2. Create master templates in Drive
3. Use clear placeholder names: {{CLIENT_NAME}}
4. Test templates with sample data

5. Store template IDs in configuration

6. Variable Replacement:

7. Validate variables exist before using
8. Provide default values for optional fields
9. Format dates/currency consistently

10. Escape special characters if needed

11. Content Updates:

12. Use append for logs and incremental content
13. Use prepend for summaries and headers
14. Use replace for complete refreshes
15. Include separators (newlines) for readability

Automation Patterns¶

1. Document Generation:
2. Build content in Variable task first
3. Test content formatting before creation
4. Store document URL in CRM record

5. Send notification with document link

6. Scheduled Reports:

7. Use Timer triggers for regular reports
8. Compile data from multiple sources
9. Append to running document or create new

10. Email stakeholders with document link

11. Template Processing:

12. Get template content
13. Replace placeholders with CRM data
14. Create new document with processed content
15. Original template remains unchanged

Performance Optimization¶

1. API Calls:
2. Minimize get_document calls (cache if possible)
3. Batch content updates (don't update line by line)
4. Use variables to build complete content before inserting

5. Avoid unnecessary document fetches

6. Content Size:

7. Keep individual updates reasonable (<10KB)
8. For large content, split into logical sections
9. Consider using multiple documents for very long reports

10. Monitor document file sizes

11. Error Handling:

12. Wrap document operations in If Conditions
13. Log document IDs for troubleshooting
14. Provide fallback workflows for failures
15. Keep a copy with the Files task if the content is critical

Compliance and Security¶

1. Data Protection:
2. Be aware of data sensitivity in documents
3. Use appropriate Drive sharing settings
4. Consider encryption for highly sensitive data

5. Follow data retention policies

6. Access Control:

7. Limit OAuth connection to specific accounts
8. Use service accounts for organization documents
9. Regular audit of created documents

10. Remove access when no longer needed

11. Audit Trail:

12. Log all document operations in workflow notes
13. Store document IDs in database
14. Track document creation dates
15. Maintain history of content updates

FAQ¶

Q: Can I format text (bold, italic, colors)?

A: Not with current actions. API supports formatting via insertText requests with textStyle, but requires additional implementation. Use Google Docs UI for formatting after creation.

Q: How do I add images to documents?

A: Images require additional API calls not currently implemented. Create document, then manually add images, or implement custom insertInlineImage request.

Q: Can I create documents from existing templates?

A: Yes, use Example 3 pattern: Get template content, replace placeholders, create new document. Original template remains unchanged.

Q: What's the maximum document size?

A: Google Docs supports up to 1.02 million characters. For larger content, split into multiple documents.

Q: Can I collaborate with others on created documents?

A: Yes, share documents via Google Drive. Documents created by app can be shared normally through Drive sharing settings.

Q: How do I handle tables in content?

A: Plain text extraction preserves table content with newlines. For complex tables, work with raw content structure or create tables via API (requires additional implementation).

Q: Can I export documents to PDF?

A: Use Google Drive export API (separate implementation) or use Drive export URL: https://docs.google.com/document/d/{docId}/export?format=pdf

Q: How often can I update a document?

A: Respect API quotas (300 requests/min). For frequent updates (e.g., every minute), consider batching updates or increasing interval.

Q: Can I search document content?

A: Use get_document to retrieve plain text, then search with If Condition or Code task. Drive API also supports content search.

Q: What happens if two automations update same document simultaneously?

A: Google Docs handles concurrent edits. Last write wins for conflicts. Use queue mechanisms for critical documents.

Q: Can I restore deleted documents?

A: Documents moved to Drive trash can be restored via Drive UI. Permanently deleted documents cannot be recovered.

Q: How do I share documents with specific people?

A: Use Google Drive API permissions (separate implementation) or share manually via Drive UI after creation.

Related Tasks¶

• Variable - Build document content
• Google Sheets - Spreadsheet automation
• PDF - PDF generation
• Email - Send document links
• If Statement - Conditional document creation
• Loop - Batch document generation

Technical Details¶

• Type ID: 45
• Function: taskGoogleDocs() in automationService.js (lines 9571-9670)
• Service: googleDocsService.js (384 lines)
• API Version: Google Docs API v1, Google Drive API v3
• Authentication: OAuth 2.0 with automatic token refresh
• Scopes: https://www.googleapis.com/auth/documents, https://www.googleapis.com/auth/drive.file
• Output Prefix: task_45001_*
• Rate Limits: 300 requests/minute/user, 60 requests/minute/project
• Timeout: 30 seconds per request
• Docs API Documentation: https://developers.google.com/docs/api
• Drive API Documentation: https://developers.google.com/drive/api/v3