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 → Integrations → 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

Configuration¶

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. Creates blank document via Docs API
2. Sets title
3. If document_content provided:
4. Inserts text at beginning (index 1)
5. If folder_id provided:
6. Moves document from root to specified folder via Drive API
7. Returns document ID and edit URL

API Endpoints:

POST https://docs.googleapis.com/v1/documents
POST https://docs.googleapis.com/v1/documents/{documentId}:batchUpdate
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¶

Example 1: Automated Proposal Generation¶

Scenario: When deal reaches proposal stage, generate customized proposal document from template.

Workflow:

1. Trigger: CRM Event - Deal Stage Changed

   Condition: New stage = "Proposal"
   

2. Task: Variable - Build Proposal Content

   Variable: proposal_content
   Value:
   PROPOSAL FOR {{client_company_name}}
   
   Prepared for: {{client_contact_name}}
   Date: {{current_date}}
   Valid until: {{proposal_expiry_date}}
   
   EXECUTIVE SUMMARY
   {{deal_description}}
   
   SCOPE OF WORK
   {{deal_scope}}
   
   INVESTMENT
   Total: ${{deal_value}}
   Payment Terms: {{payment_terms}}
   
   NEXT STEPS
   1. Review proposal
   2. Schedule kickoff call
   3. Sign agreement
   
   Thank you for considering {{company_name}}.
   
   {{sales_rep_name}}
   {{sales_rep_email}}
   {{sales_rep_phone}}
   

3. Task: Google Docs - Create Document

   action: create_document
   app_connection_id: [Select connection]
   document_title: Proposal - {{client_company_name}} - {{current_date}}
   document_content: {{proposal_content}}
   folder_id: [Proposals folder ID]
   

4. Task: Edit Client - Add Custom Field

   Field: proposal_document_url
   Value: {{task_45001_document_url}}
   

5. Task: Email - Send Proposal Link

   To: {{client_contact_email}}
   CC: {{sales_rep_email}}
   Subject: Proposal for {{client_company_name}}
   Body:
   Hi {{client_contact_name}},
   
   Thank you for the opportunity to work with {{client_company_name}}.
   
   I've prepared a customized proposal for your review:
   {{task_45001_document_url}}
   
   The proposal includes:
   - Executive summary
   - Detailed scope of work
   - Investment breakdown
   - Next steps
   
   Please review and let me know if you have any questions.
   
   Looking forward to working together!
   
   Best regards,
   {{sales_rep_name}}
   

6. Task: Workflow Note

   Note: Proposal document created and sent to {{client_contact_name}}
   Type: Sales
   

Result: Automated proposal generation reduces manual work from hours to seconds.

Example 2: Daily Report Compilation¶

Scenario: Compile daily activity summary from CRM into running document.

Workflow:

1. Trigger: Timer - Daily at 5:00 PM

2. Task: Variable - Document ID

   Variable: daily_report_doc_id
   Value: 1a2b3c4d5e6f7g8h9i0j
   (Store in database or use permanent variable)
   

3. Task: MySQL Query - Get Today's Activities

   SELECT 
     COUNT(DISTINCT client_id) as clients_contacted,
     COUNT(DISTINCT CASE WHEN type='Call' THEN wfn_id END) as calls_made,
     COUNT(DISTINCT CASE WHEN type='Email' THEN wfn_id END) as emails_sent,
     COUNT(DISTINCT CASE WHEN type='Meeting' THEN wfn_id END) as meetings_held
   FROM workflow_notes
   WHERE DATE(created_date) = CURDATE()
     AND owner_id = {{user_id}}
   

4. Task: MySQL Query - Get Deals Won Today

   SELECT 
     COUNT(*) as deals_won,
     SUM(deal_value) as total_value
   FROM deals
   WHERE DATE(close_date) = CURDATE()
     AND status = 'Won'
     AND owner_id = {{user_id}}
   

5. Task: Variable - Build Daily Summary

   Variable: daily_summary
   Value:
   
   === {{current_date}} ===
   
   Activity Summary:
   - Clients Contacted: {{clients_contacted}}
   - Calls Made: {{calls_made}}
   - Emails Sent: {{emails_sent}}
   - Meetings Held: {{meetings_held}}
   
   Sales Results:
   - Deals Won: {{deals_won}}
   - Total Value: ${{total_value}}
   
   ---
   

6. Task: Google Docs - Update Document

   action: update_document
   document_id: {{daily_report_doc_id}}
   document_content: {{daily_summary}}
   update_mode: append
   

7. Task: Workflow Note

   Note: Daily report updated with {{current_date}} activities
   Type: Internal
   

Result: Automated daily activity log maintained in single living document.

Example 3: Contract Generation with Template¶

Scenario: Generate service contract when deal is won, using document template.

Workflow:

1. Trigger: CRM Event - Deal Won

2. Task: Variable - Template Document ID

   Variable: template_doc_id
   Value: [Your template document ID]
   

3. Task: Google Docs - Get Template

   action: get_document
   document_id: {{template_doc_id}}
   

4. Task: Variable - Process Template

   Variable: contract_content
   Value: {{task_45001_plain_text}}
   Replace: {{CLIENT_NAME}} with {{client_company_name}}
   Replace: {{CLIENT_ADDRESS}} with {{client_address}}
   Replace: {{CONTRACT_VALUE}} with ${{deal_value}}
   Replace: {{START_DATE}} with {{project_start_date}}
   Replace: {{DURATION}} with {{project_duration}}
   Replace: {{PAYMENT_TERMS}} with {{payment_terms}}
   

5. Task: Google Docs - Create Contract

   action: create_document
   document_title: Service Agreement - {{client_company_name}} - {{current_date}}
   document_content: {{contract_content}}
   folder_id: [Contracts folder ID]
   

6. Task: Edit Client - Store Contract URL

   Field: contract_document_url
   Value: {{task_45001_document_url}}
   

7. Task: Email - Send for Review

   To: legal@company.com
   CC: {{sales_rep_email}}
   Subject: Contract Review - {{client_company_name}}
   Body:
   New contract generated for {{client_company_name}}:
   {{task_45001_document_url}}
   
   Deal Value: ${{deal_value}}
   
   Please review for approval.
   

Result: Automated contract generation from template with dynamic data insertion.

Example 4: Meeting Notes Automation¶

Scenario: Pre-populate meeting notes document before scheduled meeting.

Workflow:

1. Trigger: Timer - 1 hour before meeting

   Triggered by calendar event
   

2. Task: Variable - Build Meeting Agenda

   Variable: meeting_notes
   Value:
   MEETING: {{meeting_subject}}
   Date: {{meeting_date}}
   Time: {{meeting_time}}
   
   ATTENDEES:
   - {{attendee_list}}
   
   AGENDA:
   1. Welcome and introductions
   2. Review previous action items
   3. {{meeting_agenda_item_1}}
   4. {{meeting_agenda_item_2}}
   5. {{meeting_agenda_item_3}}
   6. Next steps and action items
   
   NOTES:
   [To be filled during meeting]
   
   ACTION ITEMS:
   [ ] 
   [ ] 
   [ ] 
   
   NEXT MEETING:
   Date: 
   Time: 
   

3. Task: Google Docs - Create Meeting Notes

   action: create_document
   document_title: Meeting Notes - {{meeting_subject}} - {{meeting_date}}
   document_content: {{meeting_notes}}
   folder_id: [Meeting Notes folder ID]
   

4. Task: Edit Client - Store Notes URL

   Field: last_meeting_notes_url
   Value: {{task_45001_document_url}}
   

5. Task: Email - Send to Attendees

   To: {{attendee_emails}}
   Subject: Meeting Prep - {{meeting_subject}}
   Body:
   Hi team,
   
   Our meeting is scheduled for {{meeting_date}} at {{meeting_time}}.
   
   I've prepared the meeting notes document:
   {{task_45001_document_url}}
   
   Please review the agenda and add any topics you'd like to discuss.
   
   See you there!
   

6. Task: Workflow Note

   Note: Meeting notes created for {{meeting_subject}}
   Type: Meeting
   

Result: Pre-populated meeting notes ready before meeting starts.

Example 5: Weekly Report Aggregation¶

Scenario: Compile weekly sales metrics into executive summary document.

Workflow:

1. Trigger: Timer - Monday 8:00 AM

2. Task: MySQL Query - Last Week's Metrics

   SELECT 
     COUNT(DISTINCT CASE WHEN status='Won' THEN deal_id END) as deals_won,
     COUNT(DISTINCT CASE WHEN status='Lost' THEN deal_id END) as deals_lost,
     SUM(CASE WHEN status='Won' THEN deal_value ELSE 0 END) as revenue,
     COUNT(DISTINCT client_id) as new_clients,
     COUNT(DISTINCT wfn_id) as activities
   FROM (
     SELECT * FROM deals WHERE WEEK(close_date) = WEEK(CURDATE()) - 1
     UNION ALL
     SELECT * FROM clients WHERE WEEK(created_date) = WEEK(CURDATE()) - 1
     UNION ALL
     SELECT * FROM workflow_notes WHERE WEEK(created_date) = WEEK(CURDATE()) - 1
   ) AS weekly_data
   

3. Task: Variable - Calculate Win Rate

   Variable: win_rate
   Value: {{deals_won}} / ({{deals_won}} + {{deals_lost}}) * 100
   

4. Task: Variable - Build Report Content

   Variable: weekly_report
   Value:
   
   === WEEKLY REPORT: {{last_week_start}} - {{last_week_end}} ===
   
   📊 SALES PERFORMANCE
   
   Deals Won: {{deals_won}}
   Deals Lost: {{deals_lost}}
   Win Rate: {{win_rate}}%
   
   Revenue: ${{revenue}}
   Average Deal Size: ${{revenue / deals_won}}
   
   📈 GROWTH
   
   New Clients: {{new_clients}}
   Total Activities: {{activities}}
   
   🎯 KEY WINS
   {{top_deals_summary}}
   
   🔍 INSIGHTS
   {{analysis_notes}}
   
   📅 NEXT WEEK FOCUS
   {{next_week_priorities}}
   
   ---
   

5. Task: Variable - Year Report Doc ID

   Variable: year_report_doc_id
   Value: [Document ID for 2024 Weekly Reports]
   

6. Task: Google Docs - Append to Year Report

   action: update_document
   document_id: {{year_report_doc_id}}
   document_content: {{weekly_report}}
   update_mode: append
   

7. Task: Google Docs - Create Individual Report

   action: create_document
   document_title: Weekly Report - Week {{week_number}} - {{year}}
   document_content: {{weekly_report}}
   folder_id: [Weekly Reports folder ID]
   

8. Task: Email - Send to Executives

   To: executives@company.com
   Subject: 📊 Weekly Sales Report - Week {{week_number}}
   Body:
   Weekly report is ready for review:
   {{task_45001_document_url}}
   
   Quick Summary:
   - Deals Won: {{deals_won}}
   - Revenue: ${{revenue}}
   - Win Rate: {{win_rate}}%
   
   Full details in the document.
   

Result: Automated weekly reporting with both individual and aggregate documents.

Troubleshooting¶

Error: "No app connection selected"¶

Cause: OAuth connection not configured

Solutions:

1. Go to Settings → Integrations → 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. Store backup content in MySQL if 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
• MySQL Query - Aggregate data for reports

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