Google Drive Integration Documentation

Overview

The Google Drive Integration for Vantage allows users to seamlessly interact with files stored in Google Drive and manipulate data in Google Sheets. It manages authentication through OAuth tokens while providing methods to access and manipulate Google Drive files and Google Sheets data. This is crucial for transferring data analytics and reporting into spreadsheets or directly referencing Google Drive files within the Vantage platform.

Key Features

• Automatic token management and refresh.
• Secure storage of credentials using encryption.
• Capable of handling Google Sheets API requests to retrieve, manipulate, and batch process spreadsheet data.
• Real-time error handling with exponential retry logic for API requests.

Settings

The integration's behavior can be configured through various settings. Below are the detailed descriptions of all the available settings:

1. serviceId

   • Type: String
   • Description: Represents the unique identifier for the service that is connecting to Google Drive. This identifier is necessary to map the integration with the appropriate user in Vantage.
   • Default Value: None specified. Must be provided during instantiation of the integration.

2. clientId

   • Type: String
   • Description: The client ID provided by Google when the application is registered in the Google Cloud Console. This is essential for OAuth2 authentication and is used in conjunction with the client secret.
   • Default Value: None specified. Must be provided during instantiation of the integration.

3. encryptedRecord

   • Type: Object
   • Description: Contains user-specific credentials and tokens that have been previously encrypted. This record includes the access token, refresh token, and any authorized file IDs. It ensures security by storing sensitive information safely.
   • Default Value: None specified. Must contain valid data for operations involving token management.

4. tokenUrl

   • Type: String
   • Description: The URL endpoint for Google’s OAuth2 token service, used for refreshing tokens. This URL is generally constant and does not require modifications.
   • Default Value: https://oauth2.googleapis.com/token

5. driveApiUrl

   • Type: String
   • Description: Base URL for accessing the Google Drive API. This endpoint allows various operations on Google Drive files.
   • Default Value: https://www.googleapis.com/drive/v3

6. sheetsApiUrl

   • Type: String
   • Description: Base URL for calling Google Sheets API endpoints. It allows user to access data stored in Google Sheets.
   • Default Value: https://sheets.googleapis.com/v4

7. tokenExpiry

   • Type: Date
   • Description: Maintains the expiration time of the current access token. This helps in determining if the token needs to be refreshed before making API requests.
   • Default Value: Initialized as null until an access token is fetched or refreshed.

8. _accessToken

   • Type: String
   • Description: Holds the latest valid access token required for authenticating API requests to Google services. It is updated upon successful token retrieval or refresh.
   • Default Value: Initialized as null until an access token is fetched or set.

How It Works

1. Initialization: The integration is initialized using the constructor, which requires encrypted credentials, service ID, and client ID. It sets up the necessary API URLs and initializes token management properties.

2. Token Management:

   • When an access token is requested, the system checks if there is a valid token cached. If present and unexpired, it is reused.
   • If expired or missing, it uses the provided refresh token to acquire a new access token via refreshAccessToken().
   • The refreshAccessToken() function interacts with Google’s OAuth API and retrieves a new access token, updating the cached and stored credentials accordingly.

3. Authorization Handling: The integration overrides the authorize() method to inject the authorization header with a valid access token into all requests.

4. Error Handling: The request() method has built-in retry logic for 401 errors, which suggests that token refresh is required. It attempts to refresh the token and retry the request automatically.

5. Interact with Google Drive and Sheets: The integration provides several API methods such as getSpreadsheet() and getSheetValues() to fetch data from Google Sheets or check file authorizations. These methods facilitate interaction with spreadsheet content and file management in Google Drive.

Data Expectations

The integration expects structured credentials passed through the encryptedRecord. The data typically includes:

• OAuth2 Access Token
• Refresh Token
• Expiration timestamp
• Authorized File IDs

Each method will need the necessary IDs (like spreadsheetId) as arguments to fetch or manipulate specific sheets or files.

Use Cases & Examples

Use Case 1: Automated Reporting

Businesses can automate the generation of reports by fetching data from operational databases and directly populating Google Sheets for team collaboration and data visibility.

Use Case 2: Data Consolidation

Data analysts may need to aggregate information from multiple Google Sheets into a single source for enhanced analytics and reporting capabilities.

Example Configuration for Automated Reporting

To configure the Google Drive Integration for automated reporting, you can set it up as follows:

const encryptedCredentials = { // Placeholder for actual encrypted record
  accessToken: 'encryptedAccessToken',
  refreshToken: 'encryptedRefreshToken',
  tokenExpiry: '2023-12-01T12:00:00Z',
  authorizedFileIds: ['fileId1', 'fileId2']
};

const integration = new GoogleDriveIntegration(encryptedCredentials, 'service_123', 'client_xyz');

// Fetching values from a specific sheet in Google Sheets
const spreadsheetId = 'yourSpreadsheetId';
const range = 'Sheet1!A1:B10';

integration.getSheetValues(spreadsheetId, range, { valueRenderOption: 'FORMATTED_VALUE' })
  .then(values => {
    console.log('Fetched Values:', values);
  })
  .catch(error => {
    console.error('Error fetching values:', error);
  });

This example retrieves formatted values from the specified range in a Google Sheet, which could be used for reporting processes.

AI Integrations & Billing Impacts

Currently, there are no direct AI integrations specified within the Google Drive Integration. However, users may choose to leverage AI-powered analytics within Vantage on the data fetched from Google Sheets.

In terms of billing impact, the API requests made to Google Drive and Sheets can incur usage costs depending on the volume of requests and operations performed. Users should monitor API usage against their Google Cloud billing account to avoid unexpected charges. Each Google Drive and Sheets operation can be monitored through the Google Cloud Console for more detailed billing insights.