Set up an API integration

This article highlights a new alerting feature that's natively available in Jira Service Management which is gradually rolling out to some Jira Service Management Cloud customers. It may not yet be visible or available on your site.

A default API integration is provided in your Jira Service Management account which you can use to configure users as well as alerts. However, we recommend adding a separate API Integration for each of your monitoring systems. The purpose of the default API integration is to have control over default features like alerts created via notification forwarding and the web UI.

Features

Supports all the features of API Integration
Alerts created via the web application are processed by the default AP and can be modified. Alerts can be modified or ignored.
Team members' actions such as acknowledge, close, and add note are processed by the default API. Actions can be modified.
Forwarding and other internal alerts are processed by the default API. Alerts can be modified or ignored.
Configuration objects can be read & writen by using the default API.

Tags for built-in alerts

Tags added so that bulletin alerts can be modified or ignored from the default API integrations settings.
Forwarding rules
Amazon CloudWatch Integration confirmation: CloudWatch, Confirmation.
New Relic (Legacy) Integration confirmation: NewRelic, Confirmation.

Restrictions

The name of the default API integration can’t be changed.
The default API integration can’t be turned off or deleted.

What does the integration offer?

Through API integration, you can access Jira Service Management services to create alerts and configure users, on-call schedules, and teams for third-party applications.

How does the integration work?

A default API integration comes with your Jira Service Management account. You can use this integration to configure users as well as alerts. However, we recommend adding a separate API Integration for each of your monitoring systems.

Jira Service Management has the built-in capability to integrate with many management systems, making the configuration easier. Before using API Integration, check our current list of supported applications; if you can’t find what you’re looking for, contact us.

Set up the integration

Add an API Integration

Bidirectional integrations aren’t supported in Free and Standard plans. All the other integrations are supported at a team level in Free and Standard; however, for their outgoing part to work, you need to upgrade to a higher plan. To add any integration at a site level through Settings (gear icon) > Products (under JIRA SETTINGS) > OPERATIONS, you need to be either on Premium or Enterprise.

Adding an integration from your team’s operations page makes your team the owner of the integration. This means Jira Service Management only assigns the alerts received through this integration to your team.

To set up an API integration in Jira Service Management, complete the following steps:

Go to your team’s operations page.
On the left navigation panel, select Integrations and then Add integration.
Run a search and select “API”.
On the next screen, enter a name for the integration.
Optional: Select a team in Assignee team if you want a specific team to receive alerts from the integration.
Select Continue.
The integration is saved at this point.
Select Turn on integration.
The rules you create for the integration will work only if you turn on the integration.

If you're using REST API with the default API integration, copy the API key and paste it into the Authorization header in the following format: GenieKey <API key>
For example: GenieKey g4ff854d-a14c-46a8-b8f0-0960774319dd

Define rules for creating and processing alerts

The configuration of an API integration involves defining many different alert scenarios. These scenarios specify how and when alerts can be created, closed, acknowledged, etc. The integration comes with a default set of alert creation and processing rules; you can customize them and add as many rules of your own as you like. For example, you can add three rules for create alert, which means the incoming data is evaluated against these three scenarios in order, and if one of them matches, an alert is created. There’s a slight difference in how API integration works though - unlike in the case of other integrations, it only considers the rules for the specific endpoint you're working with. For instance, when you send a “Clear alert” request, it'll only check the rules under the 'Create alert' section and won’t keep cascading trying to match other alert processing rules if any.

Dynamic properties (custom priority, payload, URL, and headers) are unavailable for API integrations.

Still need help?

The Atlassian Community is here for you.

Ask the Community