# Jira

> Data Center, Server and Cloud: two integrations, their access, webhooks and specifics.

Jira is connected with an integration from the catalogue — like any other tracker. The general behaviour
(how to address the bot, what it writes, visibility scope, events) is described in
[“Tracker integrations”](/en/docs/connector/trackers); here is only what
concerns Jira specifically.

_Illustration: An ordinary ticket: a person mentioned the bot in a comment, and the bot answered in the same discussion._

## Two integrations, not one

| | `jira` | `jira-cloud` |
|---|---|---|
| What for | Jira **Data Center** and **Server** (self-hosted, including old versions) | Jira **Cloud** (`*.atlassian.net`) |
| Sign-in | Personal Access Token (Jira 8.14+) or login and password (older) | the account email + an API token from `id.atlassian.com` |
| Comment | text with Jira markup | a document (ADF): paragraphs and mentions are nodes, not text |
| Search | JQL, `POST /rest/api/2/search` | JQL, `GET /rest/api/3/search/jql` |
| Webhook signature | checked | Cloud does not sign — the secret in the link serves as the pass |
| Showcase page | [/marketplace/jira](/en/marketplace/jira) | [/marketplace/jira-cloud](/en/marketplace/jira-cloud) |

They had to be split because Cloud has a different API — to the point that the familiar
`POST /rest/api/2/search` answers “410 Gone” there. One integration “just in case”
would mean that half of its code was not tested on any installation.

## Setup

Install the integration from the [catalogue](/en/docs/connector/marketplace) and create
a connection. The fields:

| Field | `jira` | `jira-cloud` |
|---|---|---|
| Address | `https://jira.corp.local` (with the context path, if there is one) | `https://your-company.atlassian.net` |
| Project keys | `PROJ, OPS` — the letters before the ticket number | the same |
| Credentials | a token (or login and password on old versions) | **the account** (email) **and** an API token |
| Alias | a short name for the bot, for example `buff` | the same |
| Development project | a project or space in Buff: questions and tasks from Jira go there, and its “Ask” and research get Jira’s tools | the same |

_Illustration: The form is built from the schema the integration declares about itself: the connector knows nothing about Jira’s fields._

Create a **separate account** for the bot and give it access only to the projects
you need: the account’s permissions are the outer boundary, the list of project keys is the
inner one. Permissions to view and comment are enough; the bot must not be
an administrator.

**“Check connection”** answers not with “ok” but with the version and edition of your Jira and the
account the agent signed in with — so you can see that exactly what you
need has been set up.

_Illustration: Connectivity check: version, edition and whose name the agent signed in under._

## Mentioning the bot

Three forms work:

- **Jira’s autocomplete** — inserts a real mention (a link and a notification to the bot);
- **plain text** `@buff` — for Jira this is ordinary text, but the bot still answers;
- **a slash command** — `/ask`, `/research`, `/task`.

In Cloud accounts have no login: there you address the **display name**
(“@Buff Bot”) or the alias from the settings. Case does not matter.

## The link and the document in the ticket

Jira can store links separately from comments, and the integration uses this:
the link to the conversation or research in Buff goes into the ticket’s links block **once**
— with the first answer; later answers in the same ticket do not duplicate it. The research
document is attached to the ticket **as an attachment** — in both Data Center and Cloud — so
it can be opened and forwarded without going into Buff.

<Callout>
The PDF in the ticket and the export from the app are typeset independently and do not look the same.
The content is identical. Every page carries a colophon — the version and the commit of
the code the research was prepared on — so that a printed copy stays
identifiable.
</Callout>

## Webhooks

Polling always works; a webhook only speeds up delivery.
[The general procedure](/en/docs/connector/trackers#events-polling-and-webhooks) is the same as for
other trackers; the place in Jira is **Administration → System → WebHooks → Create a
WebHook**. Tick **“Issue updated”** and **“Comment created”**; if you like, narrow the
coverage with a JQL filter for the projects you need.

Data Center can sign its calls, and the connector checks this signature. Cloud cannot
— there the secret inside the issued link serves as the pass, so the link must not be
published.

## If something does not work

| Symptom | Cause |
|---|---|
| “Failed: … personal access tokens” | Jira is older than 8.14 — switch to login and password |
| “Jira answered 410” on the `jira` integration | the address leads to the cloud: this search method no longer exists there — install `jira-cloud` |
| 401 with a correct token in `jira-cloud` | the **account** is not filled in: Cloud signs in with the “email + token” pair |
| the bot is silent on a mention | the project is not among the connection’s project keys |
| the “Overview” section says the `jira` section is not used | the config is left over from the version with the built-in integration — see below |

<Callout type="warn">
**The built-in Jira integration has been removed.** It used to be configured right in the agent,
with a `jira:` section in the config; now it is an integration from the catalogue. An agent with such a config
**starts** — it keeps the section untouched, does not use it and says so on
the settings page — but the section no longer works: the connection has to be created anew.
</Callout>