# Excel Agent

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td><strong>Overview</strong></td><td><ul><li>Search and retrieve Excel workbooks stored in OneDrive or SharePoint through Blockbrain</li><li>Read, update, and analyze data within Excel worksheets and tables</li><li>Extract and summarize spreadsheet content for reporting or AI analysis</li><li>Access workbook properties and file metadata</li><li>Automate data processing and reporting workflows using Excel files</li></ul></td><td><a href="https://3232460952-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIabFtGTeQzwfWCzp8vd6%2Fuploads%2FUwHxKX9rpt3NC6yRBTXA%2FScreenshot%202025-12-04%20at%2013.51.34.png?alt=media&#x26;token=c5a58bce-5ede-4ad9-985e-556b4ebeed5e">Screenshot 2025-12-04 at 13.51.34.png</a></td></tr><tr><td><strong>Prerequisites</strong></td><td><ul><li>Complete the <a href="https://docs.en.theblockbrain.ai/for-users/agents">general setup steps</a> from the main AI Agents page</li><li>Ensure users have active Microsoft 365 accounts with access to OneDrive or SharePoint</li><li>Verify appropriate Microsoft 365 or Office licensing for Excel Online and file access</li></ul></td><td><a href="https://3232460952-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIabFtGTeQzwfWCzp8vd6%2Fuploads%2Fvi22Kf04WdMUhdg0dI0h%2FScreenshot%202025-12-04%20at%2013.51.48.png?alt=media&#x26;token=cc189408-a272-40e5-988b-b7486983d97e">Screenshot 2025-12-04 at 13.51.48.png</a></td></tr></tbody></table>

### Azure App Registration Configuration

#### Required API Permissions

Add the following Microsoft Graph permissions to your app registration:

| Permission        | Type      | Description                                                                                       |
| ----------------- | --------- | ------------------------------------------------------------------------------------------------- |
| `offline_access`  | Delegated | Maintain access to data you have given it access to                                               |
| `Files.Read`      | Delegated | Read all files the signed-in user can access, including Excel workbooks in OneDrive or SharePoint |
| `Files.ReadWrite` | Delegated | Read and write all files the signed-in user can access, including editing Excel workbooks         |
| `openid`          | Delegated | Sign in the user and allow the app to read the user's basic profile information                   |
| `User.Read`       | Delegated | Read the signed-in user's profile, including basic information such as name and email             |
| `Sites.Selected`  | Delegated | Access content in specific SharePoint sites selected by the admin, including Excel files          |

> For Excel-specific operations, the most relevant permissions are `Files.Read`, `Files.ReadWrite`, and `Sites.Selected`, as these control access to Excel workbooks stored in OneDrive or SharePoint.

#### Redirect URL

* Add <https://nango.theblockbrain.ai/oauth/callback> as allowed redirect URL to your app registration

#### Permission Configuration Steps

1. In your Azure app registration, go to **API permissions**
2. Click **"Add a permission"** > **Microsoft Graph** > **Delegated permissions**
3. Search for and select each required permission
4. Click **"Add permissions"**
5. Click **"Grant admin consent"** (recommended for organization-wide deployment)

### Agent Configuration in Blockbrain

<div data-with-frame="true"><figure><img src="https://3232460952-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIabFtGTeQzwfWCzp8vd6%2Fuploads%2FlCh1gAaJCesXA1tJveWC%2FScreenshot%202025-12-04%20at%2009.37.36.png?alt=media&#x26;token=d32831ce-82cf-4640-921f-60009d842eb8" alt=""><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="https://3232460952-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIabFtGTeQzwfWCzp8vd6%2Fuploads%2FBF22iUre3CkPooNdFbbz%2FScreenshot%202025-12-04%20at%2009.38.28.png?alt=media&#x26;token=9e7e40f1-8eb2-4b41-8abb-41ae0dc5d91a" alt=""><figcaption></figcaption></figure></div>

1. **Access Agent Settings**:
   * Navigate to your Blockbrain admin panel
   * Go to **Agents** > **Excel Agent**
   * Click **"Configure"**
2. **Enter Azure Credentials**:
   * **Client ID**: Enter the Application ID from your Azure app registration
   * **Client Secret**: Paste the client secret you generated
   * **Tenant**: Enter your Azure tenant ID
3. **Configure OAuth Scopes**:
   * Add each required scope individually using the **"Add"** button as mentioned [here](#required-api-permissions)
   * Each scope will appear as a removable tag
   * Use the **"X"** button to remove incorrect scopes
4. **Additional Configuration** (Optional):
   * Add custom key-value pairs if needed for specific requirements
   * Configure any organization-specific settings
5. **Save Configuration**:
   * Click **"Save"** to apply the settings
   * Wait for the confirmation message

### Alternative: Admin Consent Configuration

For simplified scope management with admin pre-approval:

1. In Azure, grant admin consent for all required permissions
2. In Blockbrain configuration, use `.default` scope instead of individual scopes
3. This eliminates the need for users to consent to individual permissions

### Testing the SharePoint Agent

#### Verification Steps

1. **Connection Test**:
   * Use the built-in connection test in Blockbrain
   * Verify successful authentication with Microsoft Graph
2. **User Testing**:
   * Have a test user connect their Microsoft account
   * Attempt to access a known Excel file in OneDrive or SharePoint
   * Verify file retrieval, worksheet access, and data read/write functionality
3. **Permission Validation**:
   * Check that the agent can access the appropriate Excel files and locations
   * Confirm read and write permissions are working correctly

### Common Excel Integration Use Cases

* **Workbook Search**: Find Excel files across OneDrive and SharePoint
* **Data Extraction**: Access and analyze data from specific worksheets or tables
* **File Editing**: Update or write data to Excel workbooks
* **Metadata Retrieval**: Extract workbook properties and file metadata

### Troubleshooting

#### Authentication Issues

**Problem**: "Access denied" or authentication failures

* **Solution**: Verify admin consent is granted for all required permissions
* **Check**: Ensure the redirect URL is exactly `https://nango.theblockbrain.ai/oauth/callback`

#### Permission Errors

**Problem**: "Insufficient privileges" when accessing Excel files

* **Solution**: Confirm the app registration has `Files.Read`, `Files.ReadWrite`, and `Sites.Selected` permissions
* **Check**: Verify the user has access to the relevant OneDrive or SharePoint locations

#### Scope Configuration Issues

**Problem**: Scopes not saving correctly

* **Solution**: Add each scope individually using the "Add" button
* **Check**: Remove any duplicate or incorrect scopes using the "X" button

### Security Considerations

* **File Access**: The agent inherits the user's Microsoft 365 file permissions
* **Location Scope**: Access is limited to files and sites the authenticated user can access
* **Data Privacy**: Files are processed according to Blockbrain's data handling policies
* **Audit Trail**: Excel file access is logged in both Azure AD and Microsoft 365 audit logs

### Next Steps

After successful Excel Agent configuration:

* Train users on Excel integration features
* Configure additional agents (e.g., SharePoint, Outlook) if needed
* Monitor usage and performance through Azure AD reports