Overview

This guide walks through creating a retrieval action that allows Glean Assistant to access and display Google Calendar events. This integration enables users to query their calendar events directly through Glean’s interface.

Before beginning this implementation, ensure you have:

  • Administrator access to your Glean instance
  • Access to Google Cloud Console with appropriate permissions
  • Understanding of OAuth 2.0 authentication flows

Implementation Steps

1

Creating the Base Action

Begin by navigating to Admin console > Platform > Actions and selecting “New Action”.

Choose “start from scratch” since the Google Calendar action isn’t available in the templates.

Basic Information Configuration

Configure these essential details:

  • Display Name: Choose a clear, descriptive name (e.g., “Calendar Events Retrieval”)
  • Description: Explain the action’s purpose and capabilities
  • Unique Identifier: Set a unique ID (e.g., “retrieveCalendarEvents”)
  • Action Type: Select “Retrieval” since this action reads calendar data

Trigger Condition Setup

Your trigger condition should clearly specify:

  • When Glean Assistant should use this action
  • Expected user query patterns
  • Scenarios where the action shouldn’t be used
2

Configuring the API Specification

Add this OpenAPI specification to define how Glean Assistant interacts with the Google Calendar API:

openapi: 3.0.1
servers:
  - url: 'https://www.googleapis.com/calendar/v3/'
info:
  title: Google Calendar Events API
  description: This API returns events on the primary calendar of the currently logged-in user.
  version: 1.0.0
paths:
  /calendars/primary/events:
    get:
      summary: List Events
      description: Retrieves events from the primary calendar.
      parameters:
        - name: timeMin
          in: query
          description: |
            Lower bound (exclusive) for an event's start time to filter by. Must be an RFC3339 timestamp with a mandatory time zone offset. Its very important to have timestamp in Z format
            Example: 2011-06-03T10:00:00Z
          required: false
          schema:
            type: string
            format: date-time
        - name: timeMax
          in: query
          description: |
            Upper bound (exclusive) for an event's start time to filter by. Must be an RFC3339 timestamp with a mandatory time zone offset. Its very important to have timestamp in Z format
            Example: 2011-06-03T10:00:00Z
          required: false
          schema:
            type: string
            format: date-time
        - name: q
          in: query
          description: Free text search terms to find events that match these terms in various fields such as summary, description, location, etc.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: A list of events.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Identifier of the event.
                        status:
                          type: string
                          description: Status of the event (confirmed, tentative, cancelled).
                        summary:
                          type: string
                          description: Title of the event.
                        description:
                          type: string
                          description: Description of the event.
                        start:
                          type: object
                          properties:
                            dateTime:
                              type: string
                              format: date-time
                              description: The start time of the event.
                        end:
                          type: object
                          properties:
                            dateTime:
                              type: string
                              format: date-time
                              description: The end time of the event.

Leave the “Use existing on-premise server” option unchecked since we’re accessing Google’s API directly.

3

Setting Up Authorization

This action requires OAuth User authentication to access individual users’ calendar data.

Google Cloud Console Setup

  1. Access the Google Cloud Console Credentials page
  2. Create OAuth credentials:

  3. Configure as a web application:

Redirect URI Configuration

Add this URI to your OAuth client:

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

OAuth Settings

Configure these parameters in Glean:

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/calendar.readonly

Enable Google Calendar API

  1. Access your Google Cloud Console
  2. Enable the Calendar API:

4

Testing and Deployment

Test the action thoroughly before deployment.

Initial Testing

  1. Use the provided testing URL
  2. You’ll see the connection banner:

  3. Authenticate with Google
  4. Verify event retrieval:

Deployment

Configure deployment settings:

Set appropriate access controls:

  • Enable for all teammates or
  • Restrict to specific team members

Implementation Guidelines

API Specification Best Practices

Parameter Configuration

When configuring the Calendar API parameters:

  • Use RFC3339 format for all date-time fields
  • Include timezone offsets in timestamp examples
  • Provide clear descriptions for search parameters
  • Consider default values for time ranges

Response Handling

Important considerations for handling calendar data:

  • Process multiple calendar event types (recurring, all-day, etc.)
  • Handle timezone conversions appropriately
  • Consider pagination for large result sets
  • Process cancelled or declined events properly

Authentication Considerations

OAuth Setup

Critical OAuth implementation details:

  • Always use access_type=offline for refresh token support
  • Request minimal scopes (readonly for calendar access)
  • Handle token refresh scenarios gracefully
  • Implement proper token storage and security

Common Implementation Challenges

Watch out for these common issues:

  1. Time Zone Handling

    • Inconsistent timezone formatting
    • Missing timezone offsets
    • Incorrect local time conversions
  2. Calendar Access

    • Primary vs. secondary calendar confusion
    • Shared calendar permissions
    • Resource calendar access
  3. Event Filtering

    • Inefficient time range queries
    • Missing recurring event instances
    • Incomplete search term matching

Performance Optimization

Query Optimization

Optimize calendar queries by:

  • Using appropriate time ranges
  • Implementing result caching
  • Limiting returned fields
  • Managing API quota usage

Testing Strategy

Comprehensive Testing

Test these scenarios thoroughly:

  • Different calendar types (primary, shared, resource)
  • Various event types (single, recurring, all-day)
  • Different time zones and formats
  • Search functionality across event fields
  • Error handling and recovery

Maintenance and Operations

Monitoring Considerations

Regular monitoring should include:

  • API quota usage tracking
  • Authentication success rates
  • Query performance metrics
  • Error rate monitoring
  • User feedback collection

Regular Maintenance Tasks

Establish these routine procedures:

  • OAuth credential rotation
  • API version compatibility checks
  • Performance optimization reviews
  • User permission audits
  • Documentation updates

Troubleshooting Guide

If you encounter issues:

  1. Verify OAuth configuration

    • Check credential settings
    • Confirm correct scopes
    • Validate redirect URIs
  2. Check API access

    • Confirm API is enabled
    • Verify quota availability
    • Check user permissions
  3. Review implementation

    • Validate timestamp formats
    • Check parameter formatting
    • Verify error handling

Next Steps

After implementation:

  1. Create user documentation
  2. Set up monitoring dashboards
  3. Establish support procedures
  4. Plan for feature enhancements
  5. Schedule regular reviews