# OneNote

Index and search Microsoft OneNote notebooks in Risotto

Connect your Microsoft OneNote notebooks to Risotto to make all your notes searchable through the AI assistant.

> **Note:** OneNote uses OAuth authentication, which requires connecting through the **Settings > Integrations** page before creating an index. This is different from integrations like SharePoint, where you enter API credentials in the index form.

## Key Characteristics

| Feature         | OneNote                           | SharePoint                           |
| --------------- | --------------------------------- | ------------------------------------ |
| Authentication  | OAuth (user login)                | API credentials                      |
| Setup Location  | Settings > Integrations > OneNote | Settings > Integrations > SharePoint |
| Indexes per Org | One                               | Multiple                             |
| Scope           | All user's notebooks              | Specific site/folder                 |

## Prerequisites

Before connecting OneNote, ensure:

1. **Microsoft Account** - You have a Microsoft 365 account with OneNote access
2. **Admin Access** - You are an administrator in your Risotto organization
3. **Notebook Access** - Your Microsoft account can access the notebooks you want to index

> **Tip:** No Azure AD app registration is required - Risotto handles the Microsoft
> integration automatically.

## Step 1: Connect OneNote

1. **Navigate to Integrations**

   In your Risotto dashboard, go to [**Settings** > **Integrations**](https://dashboard.tryrisotto.com/settings/integrations).

   Click the **OneNote** card. Find the **Notebook access** card ("Reads the notebooks the connected Microsoft account can open.").

   *Product example: Settings, Integrations, OneNote before it is connected: the Notebook access card with Connect.*

2. **Start OAuth Flow**

   Click the **Connect** button. You'll be redirected to Microsoft's login page.

3. **Sign In and Authorize**

   1. Sign in with your Microsoft 365 account 2. Review the permissions Risotto
      is requesting: - **Read all OneNote notebooks** - Access to your notebooks and
      pages - **Read SharePoint sites** - Access to notebooks stored in SharePoint -
      **Maintain access** - Keep the connection active for background indexing 3.
      Click **Accept** to grant permissions

4. **Verify Connection**

   After authorization, Risotto opens the OneNote settings page and shows the message **OneNote connected**. The OneNote card shows:

   - **Tenant ID**: Your Microsoft tenant identifier
   - A **Connected** menu that holds **Disconnect...**

## Step 2: Create a OneNote Index

1. **Open the Knowledge tab**

   On [**Settings** > **Integrations** > **OneNote**](https://dashboard.tryrisotto.com/settings/integrations/onenote), open the **Knowledge** tab and click **Index notebooks**. The button shows only after you connect OneNote, and only while your organization has no OneNote index. The **Index notebooks** dialog opens.

2. **Configure Index**

   OneNote has no source fields. The dialog says "Agents answer from every notebook the connected Microsoft account can open." Enter the fields:

   | Field          | Required                                 | Description                                                             |
   | -------------- | ---------------------------------------- | ----------------------------------------------------------------------- |
   | **Name**       | Yes                                      | Descriptive name (e.g., "Company Knowledge Base"), up to 100 characters |
   | **Department** | Org Admins and Managers: No. Others: Yes | Restrict access to a specific department                                |
   | **Audience**   | No                                       | **Everyone** (the default) or **Assistant only**                        |

   Click **Index notebooks** to start indexing.

   *Product example: The Index notebooks dialog on the OneNote integration page: a name, Department and Audience, and Index notebooks.*

**Create index** on [**Knowledge > Indexes**](https://www.tryrisotto.com/docs/dashboard/knowledge/indexes#create-an-index) works the same way: **OneNote** appears in its **Data source** list only after you complete the OAuth connection, and only while your organization has no OneNote index. It is the only place to set **Profile filters**.

## What Gets Indexed

Once created, Risotto indexes:

- All OneNote notebooks your connected account can access
- All sections within those notebooks
- All pages within those sections

Content is converted from OneNote's HTML format to searchable text.

> **Warning:** Only **one OneNote index** is allowed per organization since it's tied to a
> single OAuth connection.

## Monitoring Progress

After creating the index, its card on the **Knowledge** tab reads **Indexing**, with the number of pages so far. On [**Knowledge** > **Indexes**](https://dashboard.tryrisotto.com/knowledge/indexes), the **Indexing Jobs** panel above the table shows the same job while it runs:

- A progress bar captioned with the pages processed so far and the pages found (for example, `OneNote 'IT Notebooks' - 120/340 pages processed`), and the percentage complete
- If the job fails, the caption shows the error, and a retry button appears next to the bar

When the job finishes, it leaves the panel, and the **Count** column of your OneNote index shows the pages indexed.

## Managing Your Connection

### Reconnecting After Expiration

Microsoft OAuth tokens expire periodically. When this happens:

1. The **Notebook access** card on the OneNote integration page (**Settings** > **Integrations** > **OneNote**) shows a **Connection expired** alert: "Reconnect to resume indexing. Paused jobs resume on their own."
2. Click **Reconnect** on the card
3. Sign in with Microsoft again
4. Grant permissions

> **Tip:** Any indexing jobs that were paused due to token expiration will automatically
> resume after you reconnect.

### Disconnecting OneNote

To remove the OneNote connection:

1. Go to [**Settings** > **Integrations**](https://dashboard.tryrisotto.com/settings/integrations)
2. Click the **OneNote** card
3. On the **Notebook access** card, click the **Connected** menu, then click **Disconnect...**

This will:

- Remove the OAuth connection
- Prevent new indexing
- Existing indexed content remains searchable until you delete the index

## Reindexing Content

To refresh your indexed content with the latest OneNote changes:

1. Go to [**Knowledge** > **Indexes**](https://dashboard.tryrisotto.com/knowledge/indexes)
2. Find your OneNote index
3. Click the row's **⋮** menu (**Index actions**), then click **Reindex**

Reindexing will:

- Fetch all current notebooks and pages
- Update content that has changed
- Add new pages created since last index
- Remove pages that no longer exist

## Access Control

### Department Restriction

Restrict who can search the OneNote index:

1. When creating or editing the index, select a **Department**
2. Only members of that department will see results from this index

### Organization-Wide Access

Select "Organization-wide (no department restriction)" to allow all users to search the OneNote content.

## Troubleshooting

### OneNote not available in Data Source dropdown

**Cause**: OneNote OAuth connection not established or expired.

**Solution**:

1. Go to **Settings** > **Integrations**
2. Connect or reconnect OneNote
3. Return to create index

### Connection expired alert

**Cause**: Microsoft OAuth refresh token has expired (typically after extended inactivity).

**Solution**:

1. Click **Reconnect** on the OneNote integration page
2. Sign in with Microsoft
3. Paused jobs will automatically resume

### Unable to connect to OneNote

**Cause**: Microsoft OAuth flow failed.

**Solutions**:

- Ensure you're using a valid Microsoft 365 account
- Check that your account has OneNote access
- Try using an incognito/private browser window
- Clear browser cookies and try again

### No pages indexed

**Cause**: The connected account may not have access to any notebooks.

**Solutions**:

- Verify the Microsoft account has OneNote notebooks
- Check that notebooks are not in a restricted location
- Ensure notebooks have pages with content

### Only one OneNote index allowed

**Cause**: Risotto limits OneNote to one index per organization.

**Solution**:

- Delete the existing OneNote index if you need to recreate it
- Or reindex the existing index to refresh content

## Permissions Explained

When you connect OneNote, you grant these Microsoft permissions:

| Permission       | Purpose                                          |
| ---------------- | ------------------------------------------------ |
| `Notes.Read.All` | Read all OneNote notebooks you have access to    |
| `Sites.Read.All` | Access notebooks stored in SharePoint sites      |
| `offline_access` | Allow Risotto to refresh access without re-login |

> **Info:** These are **delegated permissions** - Risotto can only access what your
> Microsoft account can access. Risotto cannot access notebooks belonging to
> other users unless those notebooks are shared with you.

## Security Considerations

### Token Storage

- OAuth tokens are encrypted at rest
- Refresh tokens are stored securely and never exposed
- Tokens are isolated per organization

### Data Access

- Risotto only reads OneNote content - no write access
- Indexed content is stored within your Risotto instance
- Access respects your configured department restrictions

### Token Health Monitoring

- Risotto automatically monitors OAuth token health
- Administrators are notified when reconnection is needed
- No manual intervention required for routine token refresh

## Limits

| Limit                            | Value                                                |
| -------------------------------- | ---------------------------------------------------- |
| OneNote indexes per organization | 1                                                    |
| Maximum pages per index          | 10,000                                               |
| Token refresh                    | Automatic                                            |
| Re-authentication frequency      | When refresh token expires (\~90 days of inactivity) |

> **Warning:** If you have more than 10,000 pages across all notebooks, only the first 10,000
> will be indexed.

## Next Steps

After setting up your OneNote index:

1. **Test the integration** using [**Knowledge** > **Playground**](https://dashboard.tryrisotto.com/knowledge/playground)
2. **Ask Risotto questions** about your indexed notes in Slack
3. **Monitor answer quality** and adjust if needed
4. **Set up regular reindexing** to keep content current

For additional help, contact support at <support@tryrisotto.com>.

Source: https://www.tryrisotto.com/docs/integrations/knowledge/onenote
