# Incident and service-management tools

Three more tools sit behind the same provider seam as Jira, Linear and GitHub Issues
([issue-trackers.md](issue-trackers.md)): each can be an alert channel, can be linked from an
issue, and is told when the issue resolves.

| Tool | What Bucker creates | Key | Public API used |
| --- | --- | --- | --- |
| Opsgenie | An alert | `bucker-<issue id>` (the alias) | `POST /v2/alerts`, `POST /v2/alerts/<alias>/close` |
| incident.io | An alert event | `bucker-<issue id>` (the deduplication key) | `POST /v2/alert_events/http/<alert source id>` |
| Jira Service Management | A service-desk request | `SD-123` | `POST /rest/servicedeskapi/request` |

Atlassian is folding Opsgenie into Jira Service Management. Opsgenie keeps working today and
is a provider for that reason; new Atlassian customers will want the JSM one.

## Behaviour they share

- Linking is idempotent. A second click, an alert storm and a retried delivery find the first
  alert or request and create nothing.
- A 4xx from the tool (a wrong key, a rejected field) is permanent and is not retried; a 5xx or a
  timeout is.
- Resolving the issue in Bucker closes or resolves the item in the tool. A regression opens it
  again (Opsgenie and incident.io). JSM moves through the transition ids you configure, since
  those are specific to each workflow.
- Hosts are fixed. Opsgenie is `api.opsgenie.com` or `api.eu.opsgenie.com` by the `region`
  setting, incident.io is `api.incident.io`, and a JSM base URL must be HTTPS and public. A key
  is never sent to a host typed into a form.

## Connecting

All three are connected in Settings, Integrations, and each is then available as an alert
channel kind.

| Tool | Settings | Credentials | You create, once |
| --- | --- | --- | --- |
| Opsgenie | `region` (`us` or `eu`), optional `teams`, `tags` | `apiKey` | An "API" integration in Opsgenie |
| incident.io | `alertSourceId` | `token` | An HTTP alert source in incident.io |
| JSM | `baseUrl`, `serviceDeskId`, `requestTypeId`, optional `transitionMap`, `statusMap` | `email`, `apiToken` | An Atlassian API token, and the ids from your service desk |

Creating those keys, tokens and sources is a step for a person with admin access to the tool.
Bucker does not do it and has no way to.

For JSM status coming back, add a Jira webhook (or an automation rule) on the project that posts
to the receiver URL shown when you connect, with the secret shown there. Opsgenie and incident.io
are outbound only.

An agent reads the links these tools create with `incident_links_list`; see [Incident links](alert-routing.md#incident-links).
