Jira Service Management

Open, acknowledge and close Jira Service Management Operations alerts from Fleetera alerts with a native notification channel.

A Jira Service Management channel turns Fleetera alerts into alerts in Jira Service Management Operations, the on-call and alerting part of Jira Service Management that took over from Opsgenie. Fleetera calls the Operations alert API directly, so there is no relay to host and no payload to map. You supply the API key of an API integration; Fleetera does the rest.

The Jira Service Management alert follows the Fleetera alert through its life:

In Fleetera	In Jira Service Management
The alert fires	Fleetera opens an alert.
The alert is acknowledged	Fleetera acknowledges the alert.
The alert resolves	Fleetera closes the alert.

The relay is one way. Acknowledging or closing the alert in Jira Service Management does not acknowledge or resolve it in Fleetera. Acknowledge the alert in Fleetera too, so both sides agree.

What a Jira Service Management channel needs

Field	Required	Description
Name	Yes	A label to identify the channel. Naming it after the team that receives the alerts (for example, "Field operations") keeps your routing rules readable.
API key	Yes	The API key of an API integration in Jira Service Management Operations: 8 to 128 letters, digits and dashes. Paste it, or choose a provisioned secret that holds it.
Priority mapping	No	The priority each Fleetera severity opens with. Starts at Critical to P1, Warning to P3 and Info to P5.

Fleetera needs no site address or cloud ID: the API key is all it sends.

There is no Include resolve notifications switch on a Jira Service Management channel. Closes are always sent, so an alert never stays open in Jira Service Management after it has resolved in Fleetera.

Create the integration in Jira Service Management

Add an API integration

Go to the operations page of the team that should receive Fleetera's alerts. In the left navigation, select Integrations, then Add integration. Search for API, select it, give the integration a name, and select Continue.

Turn the integration on

Select Turn on integration. Jira Service Management acts on an integration's alerts only while it is on.

Copy the API key

Copy the integration's API key. The key is a credential: anyone holding it can open alerts through that integration, so handle it like a password.

Add the channel in Fleetera

Jira Service Management channels are managed under Notifications → Channels. Choose Create channel, set the type to Jira Service Management, paste the API key, and adjust the priority mapping if you want something other than the default.

Fleetera checks the key's shape before saving, so a key with spaces or other characters outside letters, digits and dashes is rejected in the form.

Fleetera stores the API key encrypted and never returns it. Every later read shows only four bullets and the key's last four characters, for example ••••4e5f. Keep your own copy if you need it elsewhere.

Channels can also be managed through the platform API:

POST /notification-channels
Content-Type: application/json

{
  "name": "Field operations",
  "type": "jsm-ops",
  "config": {
    "apiKey": "3f2a91c4-7b0e-4c1d-9e8f-000000a14e5f",
    "priorityMap": { "warning": "P2" }
  }
}

A severity the request leaves out keeps its default. The response carries the key masked and the complete map:

{
  "id": "6c1d0e4b-2a7f-4b39-9d15-8e3f2a1c7b60",
  "name": "Field operations",
  "type": "jsm-ops",
  "config": {
    "apiKeyMasked": "••••4e5f",
    "priorityMap": { "info": "P5", "warning": "P2", "critical": "P1" },
    "includeResolved": true
  },
  "enabled": true,
  "hasSecret": true,
  "secretShownOnce": null
}

includeResolved is always true for a Jira Service Management channel, and a request that sets it to false is rejected.

Use a provisioned secret

Instead of pasting the API key, a channel can use a secret that Fleetera staff provision for your organization. Contact Fleetera support to have the key provisioned under a name, for example ops-jsm. Nobody then pastes the key into the channel dialog.

In the channel dialog, under API key, choose Provisioned secret and pick the name. The list shows only the secrets that fit this channel type. Paste stays the default. If none fits, the dialog says so, and you paste the key instead.

When Fleetera staff rotate the secret, later deliveries use the new key. You do not edit the channel.
The channels list shows the secret's name, for example Provisioned: ops-jsm, where a pasted key shows its masked form.
To switch an existing channel, open Edit channel, choose Provisioned secret, pick the name, and choose Save changes. Saving discards the stored key, so to switch back you choose Paste and enter a key again.

Through the API, send "secretRef": { "name": "ops-jsm" } in config in place of apiKey. Send one or the other, never both. A name that is not provisioned for your organization is refused with a 422 and the code secret_ref_not_found; a provisioned value that is not a valid API key is refused with secret_ref_invalid.

What Jira Service Management receives

Each Fleetera alert is its own Jira Service Management alert. Fleetera derives a key from the alert itself and sends it as the alert's alias, so every call about one alert reaches the same Jira Service Management alert:

A repeat notification for an alert that is still firing does not open a second alert: Jira Service Management allows one open alert per alias and raises the open alert's count instead.
The next time the same rule fires on the same asset and variable, after the earlier alert resolved, it is a new Fleetera alert, so it gets a new alias and a new Jira Service Management alert. A late close or acknowledgement of the earlier alert can never change the new one.
Acknowledge and close find the alert by its alias, so Fleetera never needs Jira Service Management's own alert ID.

When an alert fires, the Jira Service Management alert carries:

A message that names the severity, the rule, the asset and its site, and the measured value against its threshold, for example [CRITICAL] Overheat: Turbine 7 at North Ridge · temperature 99 °C (threshold 80 °C). Fleetera shortens a message longer than 130 characters.
A description with the same line, the rule's corrective action and time to respond when they are set, and a link to the alert in Fleetera.
The priority from the channel's priority mapping.
The entity (the asset and its site), the source (Fleetera), and the tags fleetera and severity:critical (or warning, or info).
Extra properties: the asset, site, variable, value, threshold, rule, severity, when it triggered, the corrective action and time to respond, and links to the alert and the rule in Fleetera.

When the alert is acknowledged in Fleetera, from its page or in bulk from the alerts list, Fleetera acknowledges the Jira Service Management alert with the note Acknowledged in Fleetera, followed by the acknowledgement note when there is one. Only channels that received the alert's trigger are told. Taking an acknowledgement back in Fleetera (Un-ack) sends nothing; the alert stays acknowledged until it closes.

When the Fleetera alert resolves, Fleetera closes the Jira Service Management alert with the note Resolved in Fleetera. This happens even when Notify on resolve is off on the routing policy that delivered the alert: that switch governs the other channel types, never an incident tool.

Jira Service Management accepts each call first and processes it afterwards. A delivery marked sent means Jira Service Management accepted the request. If it later fails to apply it, that failure shows in Jira Service Management, not in Fleetera.

Send a test alert

Before you route real alerts through the channel, confirm it reaches Jira Service Management. Use Send test on the channel row, or the API:

POST /notification-channels/{channelId}/test

Fleetera opens a clearly-marked test alert, named Fleetera incident tool test, prefixed [TEST] and tagged test, and closes it straight away, so nothing is left open. It is a real alert while it is open, so tell your on-call team before you test. The response reports both steps:

{
  "delivered": true,
  "deliveryId": "a1b2c3d4-e5f6-4711-89ab-0123456789ab",
  "status": "sent",
  "httpStatus": 202,
  "attempts": 1,
  "error": null
}

delivered is true only when Jira Service Management accepted both the open and the close. When the open was accepted and the close was not, the channel row says Trigger sent, resolve failed, and error starts with resolve:. The test alert may then still be open: close it in Jira Service Management.

Reading the delivery log

Each channel's detail page lists its deliveries. A Jira Service Management channel records one row per call: the open (marked Initial, or Repeat for a repeat notification), the Acknowledge and the close (Resolve). A test send records two rows, the open and its close, both marked Test send.

Status	Meaning
`sent`	Jira Service Management accepted the request.
`pending`	An attempt failed transiently and a retry is scheduled.
`failed`	Delivery was abandoned, either on a permanent error or because the retry budget ran out.
`skipped`	Nothing was sent, and the row records why (for example, the channel was disabled).

When a delivery does not succeed, the details column carries the HTTP status and Jira Service Management's own message when it sent one. The API key never appears in the delivery log.

Error	What it means	What to do
`http 400` to `http 499`, except `429`	Jira Service Management refused the request. Fleetera does not retry it.	Check that the integration is turned on and that the channel holds its current API key. If it does, report the delivery ID to Fleetera support.
`http 429`	Jira Service Management is asking Fleetera to slow down.	Nothing to do; Fleetera backs off and retries.
`http 5xx`, `network error`	Jira Service Management was unreachable or erroring.	Nothing to do; Fleetera retries.

Retries

A transient failure, a 429, a 5xx or a network error, is retried up to 5 attempts in total, with exponential backoff and jitter running from about 30 seconds out to about 8 minutes. When Jira Service Management sends a Retry-After header, Fleetera waits for the interval it asked for, bounded to between 1 second and 15 minutes.

Every 4xx other than 429 is permanent: the call is not retried and the delivery is marked failed.

Updating, rotating, and removing a channel

You can rename a channel, change its priority mapping, and enable or disable it at any time. A channel's type cannot be changed.

To rotate the key, create a new API integration in Jira Service Management, then choose Replace next to the masked key in Fleetera and paste the new one. Leaving the masked key in place keeps the stored one. A channel that uses a provisioned secret is rotated by Fleetera staff, with no edit to the channel.

Disabling a channel stops new deliveries to it, which makes it the fastest way to stop alerting without losing its configuration.

Jira Service Management

On this page