# Indexes

Index knowledge sources such as Confluence, Notion and Google Drive so Risotto's agents can answer from them, and manage who gets answers from each index

An index is the content of one knowledge source, such as a Confluence space, a Google Drive folder or a Slack channel, that Risotto has read and made searchable. When the agents answer a question, they search your indexes and answer from your organization's own documentation.

You manage indexes in **Knowledge > Indexes**.

## How it works

1. **You create an index** for a source: you pick the data source, give Risotto access to it, and choose who gets answers from it.
2. **Risotto indexes the content.** An indexing job reads the source and makes it searchable. The index appears in the list when the job completes.
3. **The agents search the index** when they answer, within the limits you set with its audience and department.

To let the agents search public Slack channels live, without an index, see [Slack AI search](https://www.tryrisotto.com/docs/dashboard/knowledge/connect).

## The Indexes page

Click **Knowledge** in the sidebar, then the **Indexes** tab. The page lists your indexes in a table:

| Column           | What it shows                                                                                                                                            |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Source**       | The data source, such as **Confluence** or **Google Drive**.                                                                                             |
| **Description**  | What was indexed, such as the space, folder or channel. Click it to open the content at its source.                                                      |
| **Department**   | The department the index is restricted to, or **Org-wide**.                                                                                              |
| **Audience**     | **Everyone** or **Assistant only**. See [Configuration](#configuration).                                                                                 |
| **Count**        | How many documents the index holds, such as pages, files or threads.                                                                                     |
| **Last Updated** | When the index last changed.                                                                                                                             |
| **Enabled**      | A switch that turns the index on or off for answers. An index that is off keeps its documents and keeps syncing, so turning it back on needs no reindex. |

Type in **Filter description** to find an index, and click a column header to sort by it.

*Product example: Knowledge, Indexes in the Risotto dashboard: the indexes table, with Create index.*

On the right of the tabs, the Knowledge page shows whether [Slack AI search](https://www.tryrisotto.com/docs/dashboard/knowledge/connect) is on: **Slack search on**, **Slack search off** or **Slack search unavailable**.

## Create an index

Before you start, set up access in the source itself, such as an API token or a service account. Each source's page under [Available knowledge sources](#available-knowledge-sources) explains what to create.

1. **Click Create index**

   In **Knowledge > Indexes**, click **Create index** above the table. The **Create Index** dialog opens.

2. **Choose the data source**

   Click **Data source** and pick the source to index.

   *Product example: The Create Index dialog with the Data source list open on Confluence.*

   **Slack** appears only when Slack is connected. **OneNote** appears only when OneNote is connected and your organization has no OneNote index yet: one OneNote index covers every notebook the connected account can open.

3. **Name the index and fill in the source's fields**

   Enter an **Index name**: a descriptive name for this index, which must be unique. Then fill in the fields for the source, such as its credentials and what to index. Each source's page explains its fields.

   Credentials such as API tokens are stored in the [Credential Vault](https://www.tryrisotto.com/docs/dashboard/settings/credential-vault): pick an existing credential or add a new one in the field.

4. **Choose the audience, department and profile filters**

   Under the source's fields, set **Audience**, **Department** and, optionally, **Profile filters**. See [Configuration](#configuration).

5. **Click Create**

   Click **Create**. Risotto shows **Indexing job enqueued successfully**, and the job appears in the **Indexing Jobs** panel at the top of the page. The index appears in the table when the job completes.

   *Product example: The Create Index dialog for a Confluence space, with its audience, department and profile filters, and Create.*

You can also create an index from the source's own page: go to **Settings > Integrations**, click the source and open its **Knowledge** tab. See [Manage indexes from an integration page](#manage-indexes-from-an-integration-page).

## Configuration

Each index has access controls that determine who can receive answers from it. You set them when you create the index. You can change the audience and department later with **Configure...** (see [Change index settings](#change-index-settings)).

**Audience** - Who can receive answers from this index. This is an enforced access boundary, unlike **Profile filters**, which only filter for relevance. Choose from:

- **Everyone** - Any user can receive answers sourced from this index, including end users in chat threads. Use this for employee-facing knowledge.
- **Assistant only** - Only the Assistant will receive answers from this index. Employees won't see it referenced anywhere.

**Department** - Restrict this index to a specific department, or leave it **Organization-wide (no department restriction)**. An Org Admin or Manager can create an index for any department or for the whole organization. A department Supervisor can create an index only for a department they supervise, so the list offers only those departments. A Supervisor of a sub-department picks the parent department, because a sub-department cannot own an index.

**Profile filters** - Users with profiles matching all of the rules will receive answers from this index. This is for result accuracy (not security): it helps relevance by filtering on attributes like location or role. Each rule compares one profile field with a value. Once you add a rule, a tester appears under the rules so you can check which users match.

How Risotto applies profile filters:

- If a profile field holds more than one value, a document matches when one of the values matches.
- If Risotto cannot read the requestor's profile, the requestor gets answers only from documents that the filter does not restrict. This happens when no identity provider is connected, the ticket has no requestor email, the user is not in the identity provider, or the lookup fails. The same applies when the requestor's profile has no value for the filtered field.
- Profile filters do not apply to the dashboard Assistant, unless it acts for a requestor.
- Profile filters are not available for Slack indexes or for indexes with the **Assistant only** audience.
- You set profile filters when you create the index. **Configure...** does not change them. Set them in the **Create Index** dialog on **Knowledge > Indexes**: the add forms on integration pages do not have them.

## Available knowledge sources

### Confluence

Index a Confluence space to make its pages searchable. You enter an API token,
the token owner's email address, your Confluence base URL and the space key,
and optionally a CQL query to filter the pages. Supports real-time updates
with the Confluence app. See the [Confluence integration
guide](https://www.tryrisotto.com/docs/integrations/knowledge/confluence) for setup details.

### Notion

Index Notion workspaces including pages and databases. Requires a Notion
internal integration (you enter its integration secret) and manual sharing of
content. See the [Notion integration
guide](https://www.tryrisotto.com/docs/integrations/knowledge/notion) for setup details.

### Google Drive

Index Google Drive folders to make documents, spreadsheets, and PDFs
searchable. Slides and PowerPoint files are not indexed. Requires a Google
Cloud project and a service account key. You can index a folder, include or
exclude file IDs, or filter with a query. See the [Google Drive integration
guide](https://www.tryrisotto.com/docs/integrations/knowledge/google-drive) for setup details.

### Jira

Index Jira projects to make issue descriptions, comments, and resolution steps
searchable. Requires a Jira API token, the token owner's email address, your
Jira server URL, and a project key. See the [Jira integration
guide](https://www.tryrisotto.com/docs/integrations/knowledge/jira) for setup details.

### Freshservice

Index Freshservice knowledge base articles and solutions. Requires a
Freshservice API key, your Freshservice URL and a workspace ID. You can
exclude categories by ID. See the [Freshservice integration
guide](https://www.tryrisotto.com/docs/integrations/knowledge/freshservice) for setup details.

### Freshservice Tickets

Index Freshservice Tickets content along with the resolution notes. Requires a
Freshservice API key, your Freshservice URL and a workspace ID. See the
[Freshservice Tickets integration
guide](https://www.tryrisotto.com/docs/integrations/knowledge/freshservice-tickets) for setup details.

### Freshservice Service Catalogs

Index the published items of a Freshservice service catalog, so Risotto can
point employees to the right item. Requires a Freshservice API key, your
Freshservice URL, and a workspace ID. See the [Freshservice Service Catalogs
integration guide](https://www.tryrisotto.com/docs/integrations/knowledge/freshservice-service-catalogs)
for setup details.

### Guru

Index the cards in a Guru collection, verified or not, to make them
searchable. Requires the email of a Guru user, that user's API token (a User
Token, not a Collection Token) and the collection slug. See the [Guru
integration guide](https://www.tryrisotto.com/docs/integrations/knowledge/guru) for setup details.

### Zendesk Guide

Index Zendesk Guide help center articles and documentation. Requires your
Zendesk subdomain, a user email, that user's API token and a category ID. See
the [Zendesk Guide integration
guide](https://www.tryrisotto.com/docs/integrations/knowledge/zendesk-guide) for setup details.

### SharePoint

Index files from a SharePoint site. Requires a client ID, client secret and
tenant ID, and the site URL; you can limit the index to a folder path. See the
[SharePoint integration guide](https://www.tryrisotto.com/docs/integrations/knowledge/sharepoint) for
setup details.

### OneNote

Index OneNote notebooks. Connect OneNote from **Settings > Integrations**
first: the index covers every notebook the connected account can open, so an
organization has one OneNote index. See the [OneNote integration
guide](https://www.tryrisotto.com/docs/integrations/knowledge/onenote) for setup details.

### GitHub Repositories

Index GitHub repository files to make code documentation, README files, and
configuration files searchable. Supports branch selection, directory
filtering, and file extension filtering. See the [GitHub repositories
guide](https://www.tryrisotto.com/docs/integrations/knowledge/github-repositories) for setup details.

### GitHub Wikis

Index GitHub wiki pages to make wiki documentation searchable. Automatically
reads markdown files from the specialized wiki repository that GitHub
maintains. See the [GitHub wikis
guide](https://www.tryrisotto.com/docs/integrations/knowledge/github-wikis) for setup details.

### Coda

Index Coda documents, pages and tables to allow Risotto to search your Coda
documentation. Requires a Coda API token and your Coda organization ID; you
can restrict the index to some documents or exclude others. See the [Coda
integration guide](https://www.tryrisotto.com/docs/integrations/knowledge/coda) for setup details.

### Slack Channels

Index Slack channels to capture institutional knowledge from conversations and threads. The index count is in threads.

**Important**: Slack channel indexing requires admin configuration through the Risotto Dashboard:

- **Indexing is admin-controlled**: Simply inviting the Risotto bot to a channel does not automatically trigger indexing. To index a channel, go to **Knowledge > Indexes**, click **Create index**, select **Slack** as the **Data source**, and enter the **Channel ID**. The **Slack** option appears only when Slack is connected. You can also go to **Settings > Integrations**, click **Slack**, open the **Knowledge** tab and click **Add channel**: pick the channel by name, then click **Index channel**. Risotto must be a member of the channel.
- **Silent mode by default**: When Risotto is added to any channel, it enters Silent mode by default to prevent unauthorized actions. An admin must disable Silent mode through the Dashboard to allow Risotto to actively respond in that channel.
- **Silent mode setting**: Go to **Settings > Request Sources** and click **Manage in Slack**. On the **Requests** tab, use the **Silent mode** toggle for the channel.

Once properly configured, content is indexed as conversation threads and updates automatically.

> **Tip:** For detailed setup instructions for each knowledge source, click the links in
> the accordion sections above or visit the
> [Integrations](https://www.tryrisotto.com/docs/integrations/overview) section.

## Managing indexes

Org Admins and Managers can manage every index. A department Supervisor can manage the indexes of the departments they supervise. Other users see the indexes without the row menu or the job controls.

### Monitor indexing jobs

While an index is being built, reindexed, reconfigured or deleted, the **Indexing Jobs** panel appears at the top of the page, with a progress bar and a caption for each job, such as how many pages have been processed. When the job completes, the table updates.

For each running job you can:

- Click the pause button to pause it, or the retry button to resume a paused or failed job.
- Click the delete button to cancel it. You cannot cancel a job while it is processing: pause it first.

A failed job shows its error message in the caption. Jobs that delete or reconfigure an index show **Deleting** or **Configuring** with no controls, and run until they finish.

### Change index settings

1. **Open the row menu**

   Click the menu (**⋮**) at the end of the index's row, then click **Configure...**.

   *Product example: The Indexes page with indexing jobs running and an index's row menu open on Configure....*

2. **Change the settings**

   In the **Configure Index** dialog, change the **Audience** or the **Department**.

   For a Confluence index you can also change the **Base URL** and the **Query** (CQL), which take effect on the next reindex. Confluence API tokens expire after one year: to replace one, check **Update API credentials** and enter the **Email address** and the new **API token**.

3. **Click Update configuration**

   Click **Update configuration**. Risotto shows **Index configuration updated successfully**. When the change needs the content indexed again, such as a new department or new credentials, a job runs in the background and appears in **Indexing Jobs**.

   *Product example: The Configure Index dialog for a Confluence index, with the department set to IT, and Update configuration.*

### Reindex an index

To read a source again now, for example after a large change, open the row menu and click **Reindex**. Risotto shows **Reindex queued** and the job appears in **Indexing Jobs**. If a job for the same index is already running, the reindex is refused and Risotto shows **Error queuing reindex**.

### Delete an index

Open the row menu and click **Delete**. The **Delete index?** dialog names the index. Deleting is irreversible, but you can index the source again later.

If runbooks name the index in a [knowledge directive](https://www.tryrisotto.com/docs/dashboard/runbooks), the dialog lists them: those directives stop resolving, so matching tickets escalate instead of being answered from this source.

Click **Confirm**. Risotto shows **Index deletion started**, and the **Indexing Jobs** panel shows the deletion until it finishes.

### Manage indexes from an integration page

Each knowledge source also has a **Knowledge** tab on its page in **Settings > Integrations**. It lists that source's indexes as cards, with the count and when each was last updated. On a card you can change the department and the audience directly (the change saves when you pick), and the card's menu has **Reindex** and **Remove**, plus a link to the content at its source. The tab's add button (for example **Add space** on Confluence, **Add project** on Jira, **Add folder** on Google Workspace) opens a short form for that source. If nothing is connected yet, the page shows a setup row with the same form. Unlike **Create index**, the form has no **Profile filters**. The card also has the **Use \<name> in answers** switch, and an index you turn off shows a **Disabled** badge.

Slack, Confluence, Notion, Coda, Guru, Jira, Freshservice (articles and tickets), Google Workspace (Drive), SharePoint, Zendesk, GitHub (repositories and wikis) and OneNote have this tab. For a Freshservice service catalog, use **Create index**.

### Document size limits

Risotto indexes a document whole or not at all: it never indexes part of a document, because an answer drawn from a fragment can be wrong without any sign that content is missing. A single document is skipped when it exceeds either limit:

| Limit                 | Value                                                                                   |
| --------------------- | --------------------------------------------------------------------------------------- |
| Text per document     | 5 million characters                                                                    |
| Sections per document | 34,000 indexed sections, which only dense, non-prose text reaches before the text limit |

When a document is skipped:

- It is left out of the index, and any previously indexed version of it is removed, so the agent never answers from an outdated copy.
- Your organization's admins receive a **Document Too Large To Index** warning (in the dashboard and in your [notifications channel](https://www.tryrisotto.com/docs/dashboard/settings/notifications), if configured) naming the document. The notice is sent once per document until it is dismissed, even if the source is re-indexed in the meantime.
- Other documents in the same index are unaffected.

To include a skipped document, reduce its size or split it into smaller documents at the source, then re-index. For a Guru card, the card body and its attachments count as one document, so a card with a very large PDF attached is skipped as a whole.

Source: https://www.tryrisotto.com/docs/dashboard/knowledge/indexes
