OneDrive Integration Documentation

Overview

The OneDrive integration allows users to interact with Microsoft OneDrive through the Microsoft Graph API. This integration supports various functionalities, including OAuth token management, file and folder browsing, uploading, downloading, and creation operations. The integration is designed to streamline user access to OneDrive’s capabilities, enhancing data and analytics workflows within the Vantage platform.

Features

• OAuth token management (access and refresh tokens via the Microsoft identity platform)
• File and folder listing and browsing
• Binary and text file downloads
• File uploads, including creation, updating, and overwriting
• Folder creation, including a specified "Intuidy" app folder
• CSV and TSV parsing compatibility, shared with Google Drive

Settings

Description of each setting:

• encryptedRecord

  • Type: String
  • Purpose: Holds the encrypted credentials for securely managing access to OneDrive. The integration will require this record to authenticate API requests.
  • Default Value: None (must be provided).

• serviceId

  • Type: String
  • Purpose: Identifies the specific service instance that the OneDrive integration is associated with. This is crucial for managing multiple service connections simultaneously.
  • Default Value: None (must be provided).

• clientId

  • Type: String
  • Purpose: Represents the Client ID assigned to the application when registered on the Microsoft identity platform. This is necessary for authorization when making API calls.
  • Default Value: None (must be provided).

• credentialId

  • Type: String
  • Purpose: Identifies the stored credentials in the database, allowing the integration to persist and retrieve OAuth tokens effectively.
  • Default Value: None (must be provided).

• _accessToken

  • Type: String (Private)
  • Purpose: Temporarily stores the access token retrieved from OAuth authentication. This token is essential for making authorized API calls to OneDrive’s endpoints.
  • Default Value: null (set upon successful OAuth authentication).

• _tokenExpiry

  • Type: Date (Private)
  • Purpose: Holds the expiry date of the current access token. This is used to determine if a token refresh is needed before making an API request.
  • Default Value: null (set upon first token retrieval).

How It Works

1. OAuth Token Management: The integration handles token acquisition and renewal through the Microsoft identity platform. getAccessToken() checks if the current access token is valid and returns it. If not, it invokes refreshAccessToken() to retrieve a new one using the provided clientId, clientSecret, and refreshToken.

2. API Requests: The integration prepares API requests by attaching the required authorization headers using an access token obtained through the OAuth process. The request(url, init) method manages fetching data from OneDrive, handling authorization and possible token refresh when a 401 error is encountered.

3. File Management: Functions such as listFiles(), downloadFileContent(), createFolder(), and createFile() allow users to manage files and folders in OneDrive smoothly. Each method constructs appropriate API calls to OneDrive’s endpoints based on specified parameters.

Expected Data

The integration expects the following data structures:

• Credentials: Must include encrypted records containing access token, refresh token, and token expiry.
• File Information: Upon uploading or creating files, the integration requires name, mimeType, content, and optionally folderId (the ID of the parent folder where the file should be stored).
• Folder Information: Parameters for folder operations include name (for new folders) and parentId (for specifying the parent folder).

Use Cases & Examples

Use Case 1: Document Management System

A company uses Vantage to integrate their document management system with OneDrive, allowing users to store and retrieve documents directly from OneDrive without leaving the analytics platform.

Use Case 2: Automated Data Reporting

An organization requires a solution for automatically retrieving CSV reports generated by another system, parsing them, and saving them to a specified OneDrive folder for easy access.

Configuration Example for Use Case 2

To automate data reporting where CSV files are retrieved and saved to OneDrive:

1. Configuration Data:

   jsonCopy

   {
       "encryptedRecord": "encrypted_credentials_data_here",
       "serviceId": "my-service-id",
       "clientId": "my-client-id",
       "credentialId": "my-credential-id"
   }

2. Process:

   • Use listFiles({ folderId: 'specified-folder-id' }) to retrieve files from the specified OneDrive folder.
   • Call the external reporting system to generate a new CSV report and fetch its content.
   • Upload the CSV using createFile('report.csv', 'text/csv', reportContent, 'specified-folder-id'), where reportContent holds the CSV data.

This example demonstrates how the OneDrive integration can be effectively utilized to manage files associated with business processes, enhancing operational efficiency.

AI Integrations

The OneDrive integration does not directly include AI functionalities. However, it can be leveraged alongside AI features within the Vantage platform for enhanced data analysis, such as parsing documents or generating insights based on stored files in OneDrive.

Billing Impacts

Integrating with OneDrive may incur costs depending on the usage policies established by Microsoft. Specifically, storage limits and API request rates should be considered. To avoid unexpected charges:

• Monitor OneDrive usage according to the organization’s subscription plan with Microsoft.
• Maintain optimal API call practices to stay within limits to prevent throttling or additional charges.

Ensure that budget adjustments are made accordingly to support the desired level of integration.