# Confluence

Index and search Confluence documentation in Risotto

Connect your Confluence workspace to Risotto to make your documentation searchable through the AI assistant. Risotto indexes Confluence pages by space and keeps content up to date automatically via real-time webhooks.

> **Note:** The Confluence integration has two components: a **Forge app** that receives
> real-time updates when pages change, and an **API token** used to read page
> content during indexing. Both are required for the full experience.

> **Note:** Already connected through the older Atlassian Connect app? See [Migrate from
> Connect to Forge](https://www.tryrisotto.com/docs/integrations/ticketing/migrate-connect-to-forge) to
> move to the current Forge app.

## Prerequisites

Before connecting Confluence, ensure:

1. **Confluence Cloud** - You have a Confluence Cloud instance (e.g. `yourcompany.atlassian.net`)
2. **Atlassian Organization Admin** - You have the `Organization admin` role to install apps. See [Make someone an organization admin](https://support.atlassian.com/user-management/docs/give-users-admin-permissions/#Improved-user-management-experience)
3. **Risotto Admin Access** - You are an administrator in your Risotto organization
4. **Confluence API Token** - You have an [Atlassian API token](https://id.atlassian.com/manage-profile/security/api-tokens) for reading content. A classic token (`ATATT...`) and a scoped token (`ATSTT...`, the kind a service account creates) both work. For a token on your own Atlassian account, click **Create API token**, not **Create API token with scopes**. See [Service accounts and scoped tokens](#service-accounts-and-scoped-tokens).

## Install the Confluence App

1. **Start installation**

   In your Risotto dashboard, go to **Settings > Integrations** and click the **Confluence** card. Find the **Page updates** card ("Reindexes a page when it changes in Confluence."). Click **Install App** on the card.

   *Product example: Settings, Integrations, Confluence before the app is installed: the Page updates card with Install App, and the Confluence spaces row.*

   The **Install Confluence Forge App** dialog opens. Enter your **Atlassian site URL** (for example, `yourcompany.atlassian.net`) and click **Get install link**. If the Jira Forge app is already connected, the dialog skips the URL: click **Get install link** to install the Confluence app on the same site.

2. **Approve permissions**

   The dialog lists three steps: open the Atlassian install page, review and approve the requested permissions, then return and click **Continue**. Click **Open install page** to open the Atlassian installation page in a new tab.

   The Atlassian page for the **risotto-confluence** app (published by Risotto) lists the permissions it requires:

   - Read Confluence detailed content
   - Read Confluence content summary
   - Write Confluence content
   - Access and interact from outside of Atlassian
   - Share data with 1 domain outside of Atlassian

   Click **Get app**, choose the Confluence site to install it on, and click **Install** to add the Risotto app to your Confluence instance.

3. **Complete setup**

   Return to the Risotto dialog and click **Continue**. A toast confirms "Confluence Forge app installed successfully", and the **Page updates** card shows a green **Connected** status, with a menu that holds **Disconnect...**.

   > **Tip:** If you have already installed the Jira Forge app on an Atlassian site, the
   > dialog does not ask for the site URL. It installs the Confluence app on the
   > same site.

## Create a Knowledge Index

After installing the app, add a space to start importing your Confluence content. Each space has its own API token.

1. **Open the Knowledge tab**

   Go to [**Settings > Integrations**](https://dashboard.tryrisotto.com/settings/integrations) and click the **Confluence** card. Open the **Knowledge** tab. In the **Indexed spaces** section, click **Add space**. If nothing is connected yet, the page shows a **Confluence spaces** row instead: click **Index a space**. The **Index a space** dialog opens.

2. **Configure the index**

   The **Index a space** dialog shows these fields. Fill in the required ones:

   | Field             | Required                                 | Description                                                                                                                                                                                                                              |
   | ----------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | **Site URL**      | Yes                                      | Your Confluence site URL (e.g. `https://yourcompany.atlassian.net`). Start it with `https://`. Risotto appends `/wiki` automatically.                                                                                                    |
   | **Space key**     | Yes                                      | The key of the Confluence space to index (e.g. `ENG`, `DOCS`). Enter the key only, not a page URL or path.                                                                                                                               |
   | **Account email** | Yes                                      | Email address of the API token owner                                                                                                                                                                                                     |
   | **API token**     | Yes                                      | Your [Atlassian API token](https://id.atlassian.com/manage-profile/security/api-tokens), stored as a credential vault entry. Classic and scoped (service account) tokens are both supported.                                             |
   | **Query**         | No                                       | [CQL query](https://developer.atlassian.com/cloud/confluence/advanced-searching-using-cql/) to filter which pages are indexed (e.g. `label="documentation"`). See [Index one page or a set of pages](#index-one-page-or-a-set-of-pages). |
   | **Department**    | Org Admins and Managers: No. Others: Yes | Restrict this index to a specific department. Org Admins and Managers can leave it at **Organization-wide (no department restriction)**.                                                                                                 |
   | **Audience**      | No                                       | **Everyone** (the default) or **Assistant only**. An enforced access boundary.                                                                                                                                                           |

   *Product example: The Index a space dialog on the Confluence integration page: the site URL and space key, the account email, an API token from the vault, the optional query, Department and Audience, and Index space.*

   Risotto names the index after the space key.

   > **Note:** The API token is used for reading Confluence content during indexing. It is
   > separate from the Forge app connection, which handles real-time webhook
   > updates.

3. **Start indexing**

   Click **Index space**. A toast confirms "Indexing job enqueued successfully", and the space appears at the top of the **Indexed spaces** list as a card that reads **Indexing**, with the number of pages indexed so far. The card has **Pause** while the job runs, and **Cancel**, **Retry** or **Resume** when it does not.

   > **Warning:** Large Confluence spaces may take a while to index. You can safely navigate
   > away — indexing continues in the background.

**Create index** on [**Knowledge > Indexes**](https://www.tryrisotto.com/docs/dashboard/knowledge/indexes#create-an-index) still adds a Confluence index too. Its **Create Index** dialog asks for the same details plus an **Index name**, and it is the only place to set **Profile filters**.

## Index one page or a set of pages

An index covers one Confluence space. Use the **Query** field to narrow it to some of the pages in that space.

Risotto builds the full search itself. It always adds `type = page` and the **Space key** you entered, then appends your **Query** in parentheses. Enter only the extra filter:

| To index                             | Enter in **Query**                                                                               |
| ------------------------------------ | ------------------------------------------------------------------------------------------------ |
| One page                             | `id = 132579653`. The page ID is the number after `/pages/` in the page URL.                     |
| One page and every page under it     | `id = 132579653 OR ancestor = 132579653`                                                         |
| Every page with a label              | `label = "risotto"`. To add a page later, give it the label in Confluence and click **Reindex**. |
| Every page except those with a label | `type = page AND label != "no-index"`                                                            |

Do not add `space` clauses. Risotto sets the space. A `space` clause at the start of the **Query** can make the rest of the search invalid, and the index then fetches no pages.

Start the **Query** with a positive clause. Because Risotto puts your **Query** in parentheses, Confluence rejects a **Query** whose first clause is negative, such as `NOT label = "no-index"`. To exclude pages, start with `type = page`, then add the negative clause with `AND`, as in the last row of the table.

When you create the index or save a new **Query** in **Configure**, Risotto sends the full search to Confluence once to check it. If Confluence rejects the **Query**, the save fails, Risotto does not store the **Query**, and the dashboard shows "Confluence rejected the Query (CQL) for this index. Check the Query syntax." Correct the **Query** and save again. If Risotto cannot reach Confluence for the check, for example because the credentials are wrong, it saves the **Query** without the check.

> **Warning:** **Reindex** removes the pages that the index holds before it fetches them
> again. If Confluence rejects a stored **Query**, the index stays empty after
> the reindex, and the job error says that Confluence rejected the **Query**.
> Remove or correct the **Query**, then click **Reindex** again.

> **Note:** The link in the **Description** column of the **Indexes** table opens the
> space home page for every Confluence index, whatever the **Query** says. It
> does not show which pages the index holds. To check the contents, read the
> page count on the indexing job (a single page reads "1 pages processed"), or
> ask a question in [**Knowledge > Playground**](https://www.tryrisotto.com/docs/dashboard/knowledge/playground)
> and check the sources it cites.

When you change the **Query** on an existing index (three-dot menu > **Configure**), Risotto saves the new filter but does not fetch pages again. Click **Reindex** in the same menu to apply it. Until then, the index keeps the pages it fetched before.

Real-time updates follow the **Query**. When a page changes, Risotto checks it against the query. A matching page is re-indexed. A page that no longer matches is removed from the index.

## Monitoring Indexing Progress

After you add a space, monitor progress on the space's card on the **Knowledge** tab, or in the **Indexing Jobs** panel on the [**Knowledge > Indexes**](https://dashboard.tryrisotto.com/knowledge/indexes) page:

- **Processing**: Currently indexing pages — shows page count and progress bar
- **Paused**: Indexing has been paused — click the retry button to resume
- **Error**: An issue occurred — check the error message and retry

Use the buttons next to the progress bar to **pause** a running job, **retry** a paused or failed job, or **cancel** a job. Cancel is unavailable while the job is processing: pause it first.

> **Info:** Indexing speed depends on the number of pages in the space. The progress bar
> updates automatically as pages are processed.

## Configure an Existing Index

To update an index after creation:

1. Navigate to [**Knowledge > Indexes**](https://dashboard.tryrisotto.com/knowledge/indexes)
2. Find your Confluence index in the table
3. Click the three-dot menu (⋮) and select **Configure**

From the configuration dialog, you can:

- **Update the Query (CQL) filter**: Saving stores the new filter only. Click **Reindex** to apply it. See [Index one page or a set of pages](#index-one-page-or-a-set-of-pages).
- **Update API credentials**: check the box, then enter the **Email address** and a new **API token**. Use it when your API token expires (tokens expire after one year)
- **Change department assignment** — Restrict or widen access to the indexed content
- **Change the Base URL** — Use this if your Atlassian site moved. Changes take effect on the next reindex.

On the **Knowledge** tab, you can also click the **Site** or **Query** value on the space's card, edit it, and click **Save**. Saving does not reindex: click **Reindex** in the card's menu to apply it. You can change the API token and the account email only with **Configure...** on **Knowledge > Indexes**.

### Service accounts and scoped tokens

Atlassian issues two kinds of API token. A classic token starts with `ATATT`. A scoped token starts with `ATSTT`, and is the only kind an Atlassian service account can create. Risotto accepts both in the **API token** field.

Enter your site URL (for example, `https://yourcompany.atlassian.net`) as the **Base URL** for either kind of token. For a scoped token, Risotto sends its API calls through the Atlassian API gateway (`api.atlassian.com`) at index time. The stored **Base URL** stays your site URL, so page links and real-time updates keep working.

> **Note:** The token owner (the service account) needs read access to the space you
> index, and a scoped token needs scopes that allow it to read Confluence
> content. A scope that allows only search is not sufficient: Risotto reads each
> page by its ID to get the page content.

> **Warning:** Only a service account's scoped token goes through the gateway. A token that
> you create for your own account with **Create API token with scopes** is sent
> to your site URL, and Confluence refuses it (for example, with HTTP 403 when
> Risotto reads the space). For your own account, create the token with **Create
> API token** instead.

To fully refresh the index, click the three-dot menu and select **Reindex**. This re-processes all pages in the space.

## How Content Stays Up to Date

The Confluence app receives real-time webhooks when pages are created, updated, or deleted. Risotto automatically re-indexes affected pages — no manual action is needed for ongoing updates.

Events handled automatically:

- Page created, updated, or published
- Page deleted, trashed, or restored
- Page archived or unarchived

> **Tip:** If you notice a recent page change hasn't been reflected, try waiting a few
> minutes. If it still hasn't updated, you can manually reindex from the index
> configuration menu.

## Access Control

### Department Restriction

Restrict who can search the Confluence 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 Confluence content.

> **Note:** Risotto's access control operates independently of Confluence's space
> permissions. All users with access to the index can search all indexed pages,
> regardless of their Confluence permissions.

## Disconnecting Confluence

To disconnect, go to **Settings > Integrations > Confluence**, click **Connected** on the **Page updates** card, and choose **Disconnect...**. This removes the connection and stops updates to your indexed Confluence pages; you can reconnect at any time.

If your organization still has the legacy Connect app installed alongside the Forge app, the menu offers two options:

- **Disconnect legacy Connect app...** removes only the legacy Connect app. The Forge app stays connected and Confluence keeps working.
- **Disconnect Confluence (all)...** removes both apps and stops updates to your indexed pages.

## Troubleshooting

### App installation fails

- Ensure you have Organization admin permissions in Atlassian
- Confirm your Confluence instance is a Cloud instance (not Data Center or Server)
- Check that your Confluence site is accessible and not behind restrictive firewalls

### Index creation fails

- Verify your API token is valid and the email address matches the token owner
- If you created the token for your own account with **Create API token with scopes**, create a new one with **Create API token** (no scopes). See [Service accounts and scoped tokens](#service-accounts-and-scoped-tokens)
- Confirm the space key exists in your Confluence instance
- Check that the API token owner has read access to the target space

### The index seems to hold the wrong page or the whole space

The **Description** link on the **Indexes** table always opens the space home
page, even for an index that holds one page. Check the page count on the
indexing job instead. If you changed the **Query** after the index was
created, click **Reindex** from the three-dot menu. A saved query is not
applied until the next reindex. See [Index one page or a set of
pages](#index-one-page-or-a-set-of-pages).

### Pages not appearing in search results

- Verify the space key is correct
- Check any CQL filters that may be excluding pages
- Ensure the API token has read access to the space
- Allow time for large spaces to finish indexing — check the progress bar

### Scoped token fails with a cloud id error

The index error says the site's cloud id could not be resolved. Open the index
configuration (three-dot menu > **Configure**) and check that **Base URL** is
your `*.atlassian.net` site URL. Save, then **Reindex**.

### Index fails: Confluence rejected the API token when reading page content

The search for pages worked, but Confluence refused the first page read
(HTTP 401). Risotto stops the job, because every page would fail in the same
way. This occurs most often with a scoped token that can search but cannot
read page content.

1. Give the token a scope that reads page content, or create a new token.
2. Open the index configuration (three-dot menu > **Configure**) and update the **API token**.
3. Click **Reindex**.

### Some pages are missing and admins get a Confluence Indexing Error notification

Confluence refused to show one page (HTTP 403 or 404). For example, the page
is restricted, in the trash, or deleted. Risotto skips that page, counts it as
failed, and indexes the other pages in the space. The notification says
"Unable to read Confluence page" with the page ID and the space key. Risotto
sends one notification for each space until an admin dismisses it.

If the page must be in the index, give the token owner view permission on
the page, then click **Reindex**.

### Index fails: Unable to access Confluence space

Confluence did not find the space, or the token owner cannot view it. Check
the **Space key** in the index configuration and the token owner's
permissions on the space, then click **Reindex**.

### API token expired

- Atlassian API tokens expire after one year
- Open the index configuration (three-dot menu > **Configure**) and update your credentials
- Create a new token at [id.atlassian.com](https://id.atlassian.com/manage-profile/security/api-tokens)

### Real-time updates not working

- Verify the Confluence app is still installed in your Atlassian admin settings
- The Forge app handles webhook delivery automatically — no manual webhook configuration is required
- If updates are consistently delayed, try a manual reindex and contact support

## Next Steps

After setting up your Confluence index:

1. **Test the integration** using [**Knowledge > Playground**](https://dashboard.tryrisotto.com/knowledge/playground)
2. **Ask Risotto questions** about your indexed content in Slack
3. **Monitor answer quality** in the Analytics dashboard
4. **Add more spaces** with **Add space** on the **Knowledge** tab

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

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