# Jira Issues

Index and search the issues and comments of a Jira project in Risotto

Connect a Jira project to Risotto to make its issues searchable through the AI assistant. Risotto indexes each issue's summary, description, and comments, so past solutions in resolved issues can answer new requests.

> **Note:** This index is a knowledge source only. It does not create tickets from Jira
> issues or sync replies. To sync Jira issues as tickets, see the [Jira
> ticketing integration](https://www.tryrisotto.com/docs/integrations/ticketing/jira) instead.

## Prerequisites

Before setting up this integration, ensure you have:

1. **Jira Cloud** — a Jira project on a Jira Cloud instance (e.g. `yourcompany.atlassian.net`)
2. **An Atlassian API Token** — see [Manage API tokens](https://id.atlassian.com/manage-profile/security/api-tokens). A classic token (`ATATT...`) and a scoped token (`ATSTT...`, the kind a service account creates) both work.
3. **The email address of the API token owner**
4. **The project key** of the Jira project whose issues you want to index

> **Tip:** If you've already connected Confluence, you can generate a separate API token
> here or reuse one whose owner can view the Jira project. Jira and Confluence
> Cloud share the same Atlassian authentication.

## Setup Process

### Step 1: Configure Integration in Risotto

1. **Open Jira's page**

   Go to [**Settings** → **Integrations** → **Jira**](https://dashboard.tryrisotto.com/settings/integrations/jira) and open the **Knowledge** tab. Click **Add project**. If nothing is connected yet, click **Index a project** on the **Jira projects** row. The **Index a project** dialog opens.

2. **Configure the Index**

   Enter the following information, in the dialog's order:

   - **Site URL**: Your Jira site URL (e.g. `https://yourcompany.atlassian.net`). Start it with `https://`. Risotto accepts only an Atlassian site.
   - **Project key**: The Jira project whose issues you want to index (e.g. `IT`)
   - **Account email**: Email address of the API token owner
   - **API token**: A [vault credential](https://www.tryrisotto.com/docs/dashboard/settings/credential-vault) that holds your Atlassian API token. Choose it, or click **Add a vault credential** to create one. Classic and scoped (service account) tokens are both supported.
   - **Query** *(optional)*: A [JQL](https://www.atlassian.com/software/jira/guides/jql/overview#what-is-jql) filter that narrows which issues of the project Risotto indexes, for example `status = Done`. Risotto puts your query in parentheses and adds it to the project filter with `AND`, so a top-level `OR` stays inside the project. An `ORDER BY` clause stays outside the parentheses. Jira checks the query when you save it. If Jira rejects it, the save fails with "Jira rejected the Query (JQL)" and the reason.
   - **Skip internal comments**: Check this box to leave Jira Service Management internal comments out of the index. Use it to prevent agents from quoting internal notes to employees. Comments on projects that are not Service Management projects are always indexed.
   - **Department** and **Audience**: Choose who gets answers from this index. See [Indexes](https://www.tryrisotto.com/docs/dashboard/knowledge/indexes).

   Risotto names the index after the project key.

   *Product example: The Index a project dialog on the Jira integration page: the site URL and project key, the account email, an API token from the vault, a JQL query, Skip internal comments, Department and Audience, and Index project.*

   > **Note:** You set **Skip internal comments** when you create the index. To change it
   > on an existing index, create a new index with the setting you want and
   > delete the old one. The **Configure** dialog of a Jira index changes only
   > its **Query**, **Audience**, and **Department**.

   > **Note:** Enter your site URL as the **Site 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. Links to issues still point at your
   > site URL.

3. **Create and Monitor Index**

   Click **Index project**. The project's card on the **Knowledge** tab shows the progress, and so does the **Indexing Jobs** panel on **Knowledge > Indexes**.

**Create index** on [**Knowledge > Indexes**](https://www.tryrisotto.com/docs/dashboard/knowledge/indexes#create-an-index) still adds a Jira index. Its dialog names the site URL **Server URL** and the account email **Email address**, and adds an **Index name**. It is the only place to set **Profile filters**.

### Edit the Query later

You can change the **Query** of an existing Jira index. You cannot change the other settings.

- On [**Settings** → **Integrations** → **Jira**](https://dashboard.tryrisotto.com/settings/integrations/jira), open the **Knowledge** tab. In the **Indexed projects** card, click the **Query** row, edit it, and click **Save**. An empty Query reads "Every issue in the project".
- Or, on **Knowledge** → **Indexes**, open the index's actions menu and select **Configure...**. Edit **Query** and click **Update configuration**.

Saving does not reindex. Issues that the old Query indexed stay in the index until you **Reindex** the project. Reindex removes the old documents and indexes again with the new Query.

## Content Considerations

- Risotto indexes every issue in the project that matches the optional **Query**, with its summary, description, and comments
- Internal comments on Jira Service Management issues are indexed unless you check **Skip internal comments**

## Reindexing Content

To pull in issue updates:

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

## Troubleshooting

### Index returns zero issues despite valid credentials

Confirm the project key is correct and that the API token owner has permission
to view the project. If you entered a **Query**, check that it matches issues
in the project.

### Authentication fails

Atlassian API tokens can expire or be revoked. Generate a new one at
[id.atlassian.com](https://id.atlassian.com/manage-profile/security/api-tokens).
Then put it in the vault credential that the index uses: in **Settings →
Credential Vault**, open the credential's row menu and choose **Rotate
Value**. See [Rotate a
value](https://www.tryrisotto.com/docs/dashboard/settings/credential-vault#rotate-a-value). Then
reindex.

### Content Verification

After indexing, use [**Knowledge** → **Playground**](https://dashboard.tryrisotto.com/knowledge/playground) to confirm Risotto can find and reference your indexed issues.

## Related Integrations

- [Jira Integration](https://www.tryrisotto.com/docs/integrations/ticketing/jira) — two-way ticket sync
- [Confluence Integration](https://www.tryrisotto.com/docs/integrations/knowledge/confluence) — index a Confluence space directly

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