Overview

Jira Service Management Alerts (JSM for short, formerly Atlassian Opsgenie, now consolidated under JSM) is Atlassian’s alert response / On-Call management platform. After alerts are pushed to it via the Alert REST API, JSM is responsible for:

• Team-based on-call scheduling and rotation;
• Multi-level Escalation and phone / SMS / App push notifications;
• Alert dedup, ticket linking, and SLA reporting.

Nightingale’s JSM integration uses two endpoints of the JSM Alerts API:

• Trigger: POST /v2/alerts to create an alert;
• Resolve: POST /v2/alerts/{alias}/close?identifierType=alias to close an alert.

The two are matched via the alert’s alias (set to {{$event.Hash}}, i.e. the Nightingale event’s RuleID + dimension hash) — when a close is posted with the same alias after a trigger, the alert is closed.

• Use case: an overseas team using the Atlassian suite, or wanting to bridge monitoring alerts into the JSM ticket system.
• Prerequisites:
  • An Atlassian Cloud / JSM instance;
  • In Operations → Integrations in JSM, create an API integration or a Nightingale-type integration to obtain an API Key;
• The whole setup has three steps: (1) Create an API integration in JSM and obtain the API Key → (2) Create a JSM Alert notification channel in Nightingale → (3) Fill in the API Key in the notification rule.

Step 1: Create an integration in JSM and obtain the API Key

1. Sign in to your Atlassian instance and open Jira Service Management → Operations (or directly visit https://<your-team>.app.opsgenie.com/settings/integration/integration-list).

2. From the left, Settings → Integrations → Add integration.

3. Search and pick API in the list (the generic REST API integration; if a “Nightingale” dedicated integration is available, you can also pick it — they are equivalent).

4. Fill in a name (such as Nightingale) and pick the team (Responders) that should handle alerts from this integration.

5. After saving, the page shows an API Key like:

   1234abcd-5678-90ef-1234-567890abcdef
   

   Save it — this is the api_key you will fill into Nightingale later.

JSM’s alert API has different domains for different Atlassian regions:

• Global / North America: https://api.atlassian.com/jsm/ops/integration/v2/alerts (Nightingale’s default URL);
• EU: https://api.eu.atlassian.com/...;
• If your JSM is standalone Opsgenie (not migrated to JSM unified auth): https://api.opsgenie.com/v2/alerts or https://api.eu.opsgenie.com/v2/alerts.

The Nightingale default URL is the unified JSM endpoint; if you are on the legacy Opsgenie domain, change the URL in the channel form accordingly.

Step 2: Create a JSM Alert notification channel in Nightingale

1. Sign in to Nightingale → left menu Notification → Notification Channels.

2. In the type panel on the left, click JSM Alert (URL /notification-channels/add?ident=jsm_alert).

3. Fill in the form. All templates are pre-set by the system — you only need to change the name:

   

   Section	Field	Notes
   Basic	Name	e.g. JSM Alert
   Variables	Parameters	Keep default; the parameter api_key is pre-set
   HTTP	URL	Default https://api.atlassian.com/jsm/ops/integration/v2/alerts..., with {{if $event.IsRecovered}}/{{$event.Hash}}/close?identifierType=alias{{end}} — on trigger it forms the create URL, on recovery it forms the close URL
   HTTP	Method	POST
   HTTP	Header Authorization	GenieKey {{$params.api_key}} (keep default; GenieKey is JSM’s API Key auth prefix)
   HTTP	Header Content-Type	application/json

4. Scrolling down you see “Request Body”, also keep the default:

   

   The default request body uses Go template to branch on IsRecovered:

   {{if $event.IsRecovered}}
     {"note":"{{$tpl.content}}","source":"{{$event.Cluster}}"}
   {{else}}
     {
       "message":"{{$event.RuleName}}",
       "description":"{{$tpl.content}}",
       "alias":"{{$event.Hash}}",
       "priority":"P{{$event.Severity}}",
       "tags":[ ...tag list... ],
       "details":{{jsonMarshal $event.AnnotationsJSON}},
       "entity":"{{$event.TargetIdent}}",
       "source":"{{$event.Cluster}}"
     }
   {{end}}
   

   Field meanings:

   • message → the JSM alert title; uses Nightingale’s alert rule name;
   • description → the alert detail; the content rendered by your chosen message template (Markdown or plain text recommended);
   • alias → the alert alias; the Nightingale event’s Hash. JSM treats subsequent events with the same alias as the same alert;
   • priority → P1~P5, formed directly from Nightingale’s Severity (1~3); to map Nightingale severity to P1/P2/P3 differently, do a switch in the message template;
   • tags / entity / source → for filtering and routing on the JSM side.

5. Click Save.

Step 3: Fill in the API Key in the notification rule

1. Left menu Notification → Notification Rules → New (or edit an existing rule).

2. In the “Notification Configuration” area:

   • Notification Channel: pick the JSM Alert channel you just created;
   • Message Template: pick a template that outputs Markdown or plain text (description is capped at 15,000 characters);
   • API Key: paste the api_key from Step 1;
   • Applicable Severity / Time Range / Tags: filter as needed.

3. After saving, click “Notification Test” — a test alert should immediately appear in JSM and be auto-closed once the alert recovers.

FAQ

Q1: Getting 401 Unauthorized / AuthenticationException?

• Wrong api_key;
• You are using a legacy Opsgenie API Key but the URL points to the new JSM endpoint (or vice versa) — align them;
• The API integration is disabled in the JSM admin; toggle “Enabled” back on.

Q2: Getting 404 Not Found / alias close failure?

A: The JSM close endpoint requires the alert to exist. Common causes:

• The alert was just triggered and hadn’t been persisted before recovery hit;
• The alias exceeded 512 bytes (Nightingale’s Hash is normally under 64 chars and won’t hit this limit);
• The integration owning this API Key has no permission for that alert.

Q3: Why are duplicate triggers not deduplicated?

A: JSM dedups by alias by default — calling /v2/alerts again with the same alias returns 202 and creates nothing. If you still see duplicates:

• Check whether the alert rule’s Hash is stable (Nightingale’s Hash is composed of rule ID + dimension labels; changing either generates a new hash);
• Check whether the JSM integration has “Alert de-duplication” enabled.

Q4: The alert’s priority doesn’t match JSM’s P1~P5?

A: The default template directly maps Nightingale’s Severity (1/2/3) to P1/P2/P3. If your JSM response policy (Heartbeat / Policy) tiers by P4/P5, do the mapping in the message template:

{{- $pri := "P3" -}}
{{- if eq $event.Severity 1 -}}{{- $pri = "P1" -}}{{- end -}}
{{- if eq $event.Severity 2 -}}{{- $pri = "P2" -}}{{- end -}}
...

Q5: How do I sync claim/close events from JSM back into Nightingale?

A: You need to set up an additional Webhook callback in JSM that hits Nightingale’s OpenAPI (alert claim / mute endpoints). This is beyond the scope of this page — see Nightingale’s Open API docs.

Q6: What URL should I use for an EU instance?

A: Replace api.atlassian.com with api.eu.atlassian.com in the default URL. For standalone Opsgenie (rare these days), use api.opsgenie.com or api.eu.opsgenie.com. The auth header remains GenieKey <api-key>.

References

• JSM Operations · Alerts API docs
• JSM Operations · API Integration setup
• Opsgenie · Alert REST API (legacy)