# Jira

Configure Jira and Jira Service Management integration with Risotto

Risotto integrates with Jira and Jira Service Management to provide bidirectional ticket synchronization. This allows you to manage tickets in either system while keeping them synchronized.

To watch the whole setup first, from connecting Jira to requests from Slack, Teams and your Jira portal, see the [three-and-a-half-minute video](https://www.tryrisotto.com/docs/guides/initial/jira-setup-video).

> **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 — no reconfiguration needed.

> **Warning:** You must have the `Organization admin` role in Jira to set up this
> integration. See [Make someone an organization
> admin](https://support.atlassian.com/user-management/docs/give-users-admin-permissions/#Improved-user-management-experience).

## Setup Process

1. **Enter your Jira site URL**

   In your Risotto dashboard, go to **Settings > Integrations** and click the **Jira** card. Until the app is set up, the card shows **Connect**. On the **Jira app** card, click **Connect**.

   The **Install Jira Forge App** dialog opens with a single **Jira site URL** field. Enter your Jira site URL (e.g. `yourcompany.atlassian.net`) and click **Get install link**.

   *Product example: The Install Jira Forge App dialog in the Risotto dashboard, with northwind.atlassian.net in Jira site URL and Get install link.*

2. **Install the Risotto app**

   Click **Open install page** to open the Atlassian installation page in a new tab.

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

   - View Jira issue data
   - Create and manage issues
   - View user profiles
   - Manage Jira global settings
   - Read Email Address
   - View workflows
   - Access and interact from outside of Atlassian

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

3. **Confirm installation**

   Return to the Risotto dialog, and don't reload the page. It shows **Installing Jira Forge App** until Atlassian finishes, which can take a few minutes. The installation is automatically detected — the dialog changes to **Jira Forge App Installed** with a green checkmark and the message "Your Jira integration is ready to use." Click **Done**.

   > **Tip:** Project metadata begins loading in the background as soon as the app is installed. You can safely close the dialog and continue setup.

4. **Configure field mapping**

   Go to **Settings**. Under **Departments**, click a department, then click **Ticket Sync**. Click **Add ticket sync** and select **Jira**. Configure the Jira integration settings including:

   - Jira project and issue type
   - [Status field mappings](https://www.tryrisotto.com/docs/integrations/ticketing/jira-status-sync) (resolved, waiting states)
   - Service Desk request type (if using JSM)

   The **Configure Jira for \<department>** dialog has these fields:

   - **Jira Site**: your Jira site, pre-filled from the installation. The refresh icon next to it (**Refresh Jira metadata**) reloads project metadata from Jira and clears every field in the dialog.
   - **Project** — the project in which issues will be created.
   - **Issue Type**: the type of issue that will be created in this project (e.g. Task). The options load after you select a project.
   - **Customer Request Type**: the Service Desk request type. This field shows only for JSM projects. If the request type has no **Description** field, Risotto creates the request with the summary only, then adds the description as an internal comment. Requesters do not see that comment in the portal.
   - **Status Mapping**: one row per Risotto status, each with a dropdown of statuses from the selected project. For example, map **Resolved** to your project's **Done** status. Choose **Not mapped** to leave a row empty. This section shows after you select a project. See [Jira Status Sync](https://www.tryrisotto.com/docs/integrations/ticketing/jira-status-sync) for what an empty row does.
   - **Sync priority to Jira**: sends the Risotto ticket priority to the Jira issue. When it is on, the dialog shows one row each for **Urgent**, **High**, **Medium**, and **Low**. Map each row to a Jira priority. A row set to **Not mapped** does not sync, and the Jira issue keeps its default priority.

   *Product example: The Configure Jira for IT dialog: the IT Service Desk project, its issue and request types, the seven Status Mapping rows, the priority and JSM participant switches, and Save.*

   Click **Save**. The department's **Ticket Sync** page then shows a **Jira Settings** row with a **Connected** menu, and summarizes the site, project, issue type, and status mappings you chose. To remove the sync later, open the **Connected** menu and choose **Disconnect...**.

   > **Warning:** For larger organizations, loading all the metadata can take up to 10 minutes.

5. **Test the integration**

   Verify the integration is working correctly by creating a test ticket.

   Create a ticket via Risotto, then navigate to Jira to confirm the ticket was created there as well.

   > **Tip:** Try responding to a ticket as the requester from Jira. You should see Risotto respond automatically!

## Features

Once configured, the Jira integration provides:

- **Bidirectional Sync**: Tickets created in either system are synchronized to the other
- **Field Mapping**: Customize how fields are mapped between Jira and Risotto. A department's [additional ticket fields](https://www.tryrisotto.com/docs/dashboard/settings/departments#syncing-field-values-to-jira-or-servicenow) can be mapped to your site's global Jira custom fields, and their values are pushed to the issue when it is created or updated
- **Status Synchronization**: Status changes in one system are reflected in the other — see [Jira Status Sync](https://www.tryrisotto.com/docs/integrations/ticketing/jira-status-sync) for how this works and what your workflow must provide
- **Comment Sync**: Comments added in either system appear in both places. In Slack, a Jira comment is posted under the Jira author's name and avatar. In Microsoft Teams, Risotto posts it as a bot message that starts with **From \<author>:**, because a Teams bot cannot post under another identity. Internal Jira comments stay out of the requestor's thread in both.
- **Screenshots**: Risotto reads images on a Jira issue and in synced Jira comments, as it does for Slack and Microsoft Teams. It adds a short description of each image to the ticket, after the line "\[Attachment summary below]", so the agent can use what the screenshot shows. The description is also in the comment that Risotto posts to Slack or Teams. Risotto processes up to 20 attachments per issue description or comment, and skips a file larger than 25 MB. Other files, such as PDFs, are stored on the ticket without a description. If Risotto cannot describe an image, the ticket or comment is still created.
- **Automatic Responses**: Risotto can automatically respond to Jira ticket updates
- **Branded agent replies**: agent replies can show your own Jira user's name and avatar instead of the Risotto app. See [Post agent replies as your own Jira user](#post-agent-replies-as-your-own-jira-user).
- **Runbook tools**: Two tools run on this connection, with no separate credentials: [Get Atlassian User ID](https://www.tryrisotto.com/docs/integrations/tools/jira/get_atlassian_user_id) resolves a person to their Atlassian account ID, and [Add Participant to Work Item](https://www.tryrisotto.com/docs/integrations/tools/jira/add_participant_to_work_item) adds a request participant to a Jira Service Management request.

## Department Configuration

After setting up the global Jira integration, you can configure department-specific settings:

1. Go to **Settings**.
2. Under **Departments**, click a department, then click **Ticket Sync**.
3. Click **Add ticket sync** and select **Jira**.
4. In the **Configure Jira for \<department>** dialog, select the **Project** and **Issue Type** this department should sync with.
5. Click **Save**.

> **Note:** A department files every ticket that it syncs under the one **Issue Type**
> and **Customer Request Type** that you select. To file requests under
> different request types, use one of these:
>
> - [Service Catalog](https://www.tryrisotto.com/docs/dashboard/settings/service-catalog): import your JSM request types. Risotto picks the matching request type, asks its form questions in chat, and files the request under that type.
> - [Sub-departments](https://www.tryrisotto.com/docs/dashboard/settings/sub-departments): give each sub-department its own ticket sync settings, for example a different request type on the same project. A sub-department uses the knowledge, runbooks, and agent channel of its parent.

### Keep Risotto off JSM request participants

By default, Risotto adds itself as a request participant on the Jira Service Management issues it creates, and again when it syncs a later update to the issue. If this interferes with your JSM SLAs or notifications, turn it off for each department that syncs to a JSM project:

1. Go to **Settings**. Under **Departments**, click the department, then click **Ticket Sync**.
2. On the **Jira Settings** row, open the **Connected** menu and choose **Configure...**.
3. In the **Configure Jira for \<department>** dialog, turn on **Skip JSM participant** and click **Save**.

The setting applies per department. It shows only when the department's project is a JSM service desk project. It does not remove Risotto from issues where it is already a participant.

> **Warning:** **Refresh Jira metadata** in the same dialog clears every field in it,
> including **Skip JSM participant**. After the metadata loads, choose the
> settings again before you save, or click **Cancel** to keep the saved ones.

## Post agent replies as your own Jira user

By default, agent replies in Jira and Jira Service Management show the Risotto app name and icon. To show your own name and avatar, set a dedicated Jira user in the **Replies post as** row. This setting is for the whole organization, not for one department.

Before you start, make sure that the Jira user:

- Is a full Atlassian account, not an app account or a portal customer.
- Has a Jira Service Management agent license and is in the Service Desk Team role.
- Signed in to Atlassian at least once.
- Is a dedicated account. Risotto ignores every comment that this user writes, so do not use a real person's account.

To set the user:

1. Go to **Settings > Integrations > Jira**. Find the **Jira app** card.
2. In the **Replies post as** row, enter the email address of the Jira user.
3. Click **Save**. The row shows the user's name and email address.

*Product example: Jira's page in the Risotto dashboard: the Jira app card on Forge, with a Jira user's email in Replies post as and Save.*

Risotto checks the user when you save. The email address must match the Jira user exactly. If the check fails, the error says what is missing, for example "This user can't reply to customers. Give it a Jira Service Management agent license and add it to the Service Desk Team role."

After you save:

- Agent replies post as this user.
- A comment from a person who has a Jira account still posts as that person. A comment from a person with no Jira account posts as this user, with a "From \<name>:" line.
- If Risotto cannot post as this user, it posts the reply as the Risotto app.
- Status changes and other updates still run as the Risotto app.

To go back to the Risotto app, click **Switch to Risotto**.

> **Note:** The setting shows only for the Jira Forge app, and only in the organization
> that installed it. An organization that uses another organization's install
> does not see it. You need the Admin or Manager role.

## Request Sources

Once departments have Jira sync configured, you can set up Jira projects as request sources:

1. Navigate to **Settings > Request Sources** and click **Manage in Jira**
2. On the **Requests** tab, in the **Jira projects** section, click **Add Project**
3. Select from eligible Jira projects (those with department sync configured)
4. Configure issue type and request type filters as needed

For more details, see [Setting up Jira as a Request Source](https://www.tryrisotto.com/docs/operating/creating-tickets-jira).

## Troubleshooting

### App installation fails

- Ensure you have Organization admin permissions in Jira
- Check that the site URL you entered is correct (e.g. `yourcompany.atlassian.net`)
- Confirm your Jira instance is accessible and not behind restrictive firewalls

### Installation not detected

- Wait up to 60 seconds for the installation to be detected
- If still not detected, close the dialog and check **Settings > Integrations > Jira**: the installation may have succeeded
- Try refreshing the page

### Tickets not syncing

- Verify the Jira app is installed and active in your Atlassian admin
- Check field mapping configuration in Risotto
- Ensure **External ticket sync enabled** is on for the department and Jira ticket sync is configured
- Review webhook connectivity between Jira and Risotto
- For status transitions specifically, see the [Jira Status Sync troubleshooting guide](https://www.tryrisotto.com/docs/integrations/ticketing/jira-status-sync#troubleshooting)

### I moved a Jira issue to another project

- Jira gives the issue a new key, for example `OLD-123` becomes `NEW-45`. When Jira sends the move event, Risotto updates the Jira key and link on the ticket, and sync continues
- If Risotto did not get the move event, the ticket keeps the old key and stops syncing
- The ticket stays in its department and uses the status mapping of that department. If the new project uses other statuses, check the mapping

### Metadata loading slowly

- Large Jira instances may take up to 10 minutes to load all metadata
- Refresh the page if the loading seems stuck
- Contact support if metadata fails to load after extended periods

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