# 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.