• Products
  • Get started
  • Documentation
  • Resources

Integrate Opsgenie with Jira

What does Opsgenie offer to Jira users?

Opsgenie has a specific update set that allows a bi-directional integration between Opsgenie and Jira. Use the integration to have Jira send issues to Opsgenie with detailed information. Opsgenie forwards alerts as issues to Jira. Opsgenie determines the right people to notify based on on-call schedules– notifies via email, text messages (SMS), phone calls and iOS & Android push notifications, and escalates alerts until the alert is acknowledged or closed.

Opsgenie provides OEC solution for Jira On-Premise users to send Opsgenie alerts to Jira. Refer Creating Issues from Alerts in Jira blog post for more information.

Functionality of the integration

  • When an issue is created or reopened on Jira, an alert is created on Opsgenie automatically through the integration.

  • When an issue is resolved or closed or fixed on Jira, the related alert is closed on Opsgenie automatically.

  • When a comment is added to an issue on Jira, a note is added to related alert on Opsgenie.

  • If Send Alert Updates Back to Jira is enabled, actions for Jira are executed in Jira when the chosen action is executed in Opsgenie for alerts which are created by the Jira integration.

  • If Create Jira Issues for Opsgenie Alerts is enabled, actions for Jira are executed in Jira when the chosen action is executed in Opsgenie for alerts which have a source other than the Jira integration.

  • These action mapping features are explained in detail in the Action Mapping Feature section below.

Adding Jira Integration in Opsgenie

If you're using Opsgenie's Free or Essentials plan or if you’re using Opsgenie with Jira Service Management's Standard plan, you can add this integration from your team dashboard only. The Integrations page under Settings is not available in your plan.

  1. Go to Teams and select your team.

  2. Select Integrations on the left navigation and then select Add integration.

Adding the integration from your team dashboard will make your team the owner of the integration. This means Opsgenie will assign the alerts received through this integration to your team only. Follow the rest of the steps in this section to set up the integration.

  1. Go to Settings > Integrations. Search for Jira Software and select Add

  2. From integration settings, specify who is notified of Jira alerts using the Responders field. Auto-complete suggestions are provided as you type.

  3. Copy the integration URL which includes the Opsgenie endpoint as well as the API key.

  4. Select Save Integration.

A screenshot of Opsgenie's Jira integration page.

Configuration in Jira

  1. Log in to Jira as an administrator.

  2. From the dashboard, open the Administration menu. Select System.

  3. From the left, select Webhooks under "Advanced".

A screenshot from Jira Software showing where to select webhooks.

4. Click Create A Webhook. In the opening section, paste the URL provided by Opsgenie's Jira integration into URL input. Click Create.

A screenshot from Jira Software showing webhook details for creating a Jira integration.

Now that the webhook is configured, Jira will notify Opsgenie when changes are made to issues. Opsgenie then creates alerts and track them.

Using SSO?

If you are using SSO to log in to Jira, you need to generate an API token and use this token as the password in the integration settings. Visit Manage API tokens for your Atlassian account to learn how to generate an API token in Jira.

After generating your new token, copy and paste it to the Password field of the Jira integration in Opsgenie. Then, save the integration.

 

Action Mapping Feature

  • Opsgenie allows customers to define action mappings between Opsgenie actions and Jira actions.

  • To use the Action Mappings feature, provide some information to the integration which are listed below:

  • Issue Type: The issue types defined in Jira e.g. Task, Bug or any other custom defined type. Make sure you write the issue type syntax error-free.

  • URL: This is the domain name of your Jira Software e.g. https://testops.atlassian.net

  • Username: The e-mail address you use to login to Jira.

  • Password/API Token: The password or API token you use to login to Jira.

  • Project Key: The key of the project you want to create alerts from e.g. OT, OPS, SIT. The project key is usually in capital letters so make sure you write it in the right form.

For alerts created by Jira

  • Use this section to map Opsgenie actions to Jira actions when the source of the alert is Jira (i.e When the alert is created by Jira integration.)

  • Map different Opsgenie actions to different Jira actions. For example, add comments to Jira issue, when the alert is acknowledged. In order to do this, define If alert is acknowledged in Opsgenieadd it as a comment to issue in Jira. mapping in Send Alert Updates Back to Jira section.

A screenshot from Opsgenie showing rules to create Jira issues with Opsgenie alerts.

For other Opsgenie alerts

  • Use this section to map Opsgenie actions to Jira actions when the source of the alert is NOT Jira (i.e When the alert is created by another integration.)

  • For this purpose, use Create Jira Issues for Opsgenie Alerts section. In order to use this functionality, map one Opsgenie action to create an issue Jira action. The Opsgenie action doesn't have to be alert is created, it can be other actions as well.

A screenshot showing issue creation rules for Opsgenie alerts.
  • a tag is added to the alert and a custom action is executed on alert actions differ from other actions. When one of these actions is selected, an extra field appears to enter for which tags or for which custom action this mapping works.

  • Enter multiple tags by separating the tags with a comma. If multiple tags are entered, the mapping works if the alert has one or more of the specified tags. Leave the tags field empty to have the mapping to work for any tag.

  • If an Opsgenie action is mapped to multiple Jira actions, an error occurs except for the a tag is added to the alert and a custom action is executed on alert actions. Save multiple mappings for these actions because they differ by the given tags and the given custom action names.

Opsgenie Jira Integration allows the status of the issue to be set to IN PROGRESSRESOLVEDDONE or CLOSED in Jira. However, if the workflow of the project does not allow any of the transitions, the transition cannot be set using Opsgenie too.

Sample payload sent from Jira

JSON

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 { "webhookEvent": "jira:issue_created", "user": { "self": "https://ifountain.atlassian.net/rest/api/2/user?username=msener", "name": "msener", "emailAddress": "mustafa.sener@ifountain.com", "avatarUrls": { "16x16": "https://ifountain.atlassian.net/secure/useravatar?size=xsmall&avatarId=10122", "24x24": "https://ifountain.atlassian.net/secure/useravatar?size=small&avatarId=10122", "32x32": "https://ifountain.atlassian.net/secure/useravatar?size=medium&avatarId=10122", "48x48": "https://ifountain.atlassian.net/secure/useravatar?avatarId=10122" }, "displayName": "Mustafa Sener", "active": true }, "issue": { "id": "11601", "self": "https://ifountain.atlassian.net/rest/api/2/issue/11601", "key": "NAAS-155", "fields": { "summary": "test bug issuy", "progress": { "progress": 0, "total": 0 }, "timetracking": {}, "issuetype": { "self": "https://ifountain.atlassian.net/rest/api/2/issuetype/1", "id": "1", "description": "A problem which impairs or prevents the functions of the product.", "iconUrl": "https://ifountain.atlassian.net/images/icons/issuetypes/bug.png", "name": "Bug", "subtask": false }, "timespent": null, "reporter": { "self": "https://ifountain.atlassian.net/rest/api/2/user?username=msener", "name": "msener", "emailAddress": "mustafa.reporter@ifountain.com", "avatarUrls": { "16x16": "https://ifountain.atlassian.net/secure/useravatar?size=xsmall&avatarId=10122", "24x24": "https://ifountain.atlassian.net/secure/useravatar?size=small&avatarId=10122", "32x32": "https://ifountain.atlassian.net/secure/useravatar?size=medium&avatarId=10122", "48x48": "https://ifountain.atlassian.net/secure/useravatar?avatarId=10122" }, "displayName": "Mustafa Sener", "active": true }, "created": "2014-02-12T09:59:28.107-0500", "updated": "2014-02-12T09:59:28.107-0500", "priority": { "self": "https://ifountain.atlassian.net/rest/api/2/priority/3", "iconUrl": "https://ifountain.atlassian.net/images/icons/priorities/major.png", "name": "Major", "id": "3" }, "description": "test deskriptin", "issuelinks": [], "customfield_10000": "126", "status": { "self": "https://ifountain.atlassian.net/rest/api/2/status/1", "description": "The issue is open and ready for the assignee to start work on it.", "iconUrl": "https://ifountain.atlassian.net/images/icons/statuses/open.png", "name": "Open", "id": "1", "statusCategory": { "self": "https://ifountain.atlassian.net/rest/api/2/statuscategory/2", "id": 2, "key": "new", "colorName": "blue-gray", "name": "New" } }, "labels": [ "label2", "label3", "label1" ], "workratio": -1, "project": { "self": "https://ifountain.atlassian.net/rest/api/2/project/10100", "id": "10100", "key": "NAAS", "name": "Nofications as a Service", "avatarUrls": { "16x16": "https://ifountain.atlassian.net/secure/projectavatar?size=xsmall&pid=10100&avatarId=10011", "24x24": "https://ifountain.atlassian.net/secure/projectavatar?size=small&pid=10100&avatarId=10011", "32x32": "https://ifountain.atlassian.net/secure/projectavatar?size=medium&pid=10100&avatarId=10011", "48x48": "https://ifountain.atlassian.net/secure/projectavatar?pid=10100&avatarId=10011" } }, "environment": "env", "lastViewed": null, "components": [ { "self": "https://ifountain.atlassian.net/rest/api/2/component/10006", "id": "10006", "name": "Admin Web Application" }, { "self": "https://ifountain.atlassian.net/rest/api/2/component/10000", "id": "10000", "name": "Data Collector" }, { "self": "https://ifountain.atlassian.net/rest/api/2/component/10002", "id": "10002", "name": "Mobile App" } ], "comment": { "startAt": 0, "maxResults": 0, "total": 0, "comments": [] }, "timeoriginalestimate": null, "votes": { "self": "https://ifountain.atlassian.net/rest/api/2/issue/NAAS-155/votes", "votes": 0, "hasVoted": false }, "fixVersions": [ { "self": "https://ifountain.atlassian.net/rest/api/2/version/10000", "id": "10000", "description": "Private BETA", "name": "v0.1", "archived": false, "released": false, "releaseDate": "2012-01-31" }, { "self": "https://ifountain.atlassian.net/rest/api/2/version/10100", "id": "10100", "description": "Public Beta", "name": "v0.2", "archived": false, "released": false }, { "self": "https://ifountain.atlassian.net/rest/api/2/version/10200", "id": "10200", "description": "First release of the iPhone app", "name": "iPhone v0.1", "archived": false, "released": false, "releaseDate": "2012-04-27" } ], "resolution": null, "resolutiondate": null, "creator": { "self": "https://ifountain.atlassian.net/rest/api/2/user?username=msener", "name": "msener", "emailAddress": "mustafa.sener@ifountain.com", "avatarUrls": { "16x16": "https://ifountain.atlassian.net/secure/useravatar?size=xsmall&avatarId=10122", "24x24": "https://ifountain.atlassian.net/secure/useravatar?size=small&avatarId=10122", "32x32": "https://ifountain.atlassian.net/secure/useravatar?size=medium&avatarId=10122", "48x48": "https://ifountain.atlassian.net/secure/useravatar?avatarId=10122" }, "displayName": "Mustafa Sener", "active": true }, "duedate": "2014-02-28", "watches": { "self": "https://ifountain.atlassian.net/rest/api/2/issue/NAAS-155/watchers", "watchCount": 0, "isWatching": false }, "worklog": { "startAt": 0, "maxResults": 20, "total": 0, "worklogs": [] }, "customfield_10103": null, "customfield_10601": "Not Started", "customfield_10102": null, "customfield_10101": null, "customfield_10600": null, "customfield_10100": null, "customfield_10506": null, "assignee": { "self": "https://ifountain.atlassian.net/rest/api/2/user?username=mberkay", "name": "mberkay", "emailAddress": "mberkay.assignee@gmail.com", "avatarUrls": { "16x16": "https://ifountain.atlassian.net/secure/useravatar?size=xsmall&avatarId=10122", "24x24": "https://ifountain.atlassian.net/secure/useravatar?size=small&avatarId=10122", "32x32": "https://ifountain.atlassian.net/secure/useravatar?size=medium&avatarId=10122", "48x48": "https://ifountain.atlassian.net/secure/useravatar?avatarId=10122" }, "displayName": "Berkay M", "active": true }, "customfield_10505": null, "attachment": [], "customfield_10504": null, "customfield_10503": null, "customfield_10502": null, "customfield_10200": "110", "customfield_10501": null, "customfield_10500": null, "versions": [ { "self": "https://ifountain.atlassian.net/rest/api/2/version/10000", "id": "10000", "description": "Private BETA", "name": "v0.1", "archived": false, "released": false, "releaseDate": "2012-01-31" }, { "self": "https://ifountain.atlassian.net/rest/api/2/version/10100", "id": "10100", "description": "Public Beta", "name": "v0.2", "archived": false, "released": false }, { "self": "https://ifountain.atlassian.net/rest/api/2/version/10201", "id": "10201", "description": "Second release of the iPhone app", "name": "iPhone v0.2", "archived": false, "released": false } ], "customfield_10700": null, "customfield_10400": null, "timeestimate": null, "customfield_10300": null, "customfield_10301": null } }, "timestamp": 1392217168146 }

Integration via OEC (for Jira Software Server & Data Center Usage)

Use Opsgenie's OEC and the Jira Software Server & Data Center script to update issues on Jira Software Server & Data Center. This enables the deployment of your own scripts/ability to modify the ones provided and execute customized actions on Jira Software Server & Data Center.

To use the Jira Software Server & Data Center integration package, follow the steps in the sections below through the end.

 

Download the latest version of OEC

To download the latest version of Jira package, please use readme file of oec-scripts repository.

Installation

For Red Hat Based Distributions

  • Run following command : rpm -i opsgenie-jira-<your_version>.rpm

For Debian Based Distributions

  • Run following command : dpkg -i opsgenie-jira-<your_version>.deb

For Windows

  • Unzip opsgenie integration zip file which contains OEC package into a directory (C:\opsgenie is the preferred path.) Follow the instructions here to install OEC on Windows.

  • In order to learn more about how to run OEC you can refer to the Running OEC documentation.

Configuring Jira Software Integration for OEC

  • In order to use OEC utility for your Jira Software integration, enable Send Via OEC in your integration settings.



A screenshot showing OEC option for Jira integration.
  • Other configurations regarding Jira Software can be done either via the integration settings page or the OEC configuration file. Configuration on the integration page precedes the configuration file.

 

A screenshot showing extra OEC settings for Jira integration.

OEC Configuration

To be able to execute actions in Jira Software, OEC gets the configuration parameters from the configuration file.

Configuration parameters

  • apiKey – Copy the API key from the Jira integration you've created above.

  • issueTypeName – Type of the issue which can be "Task", "Bug", "Story" or your custom issue type ("Epic" is not supported!).

  • url – Your Jira url where the issues will be created, resolved, closed etc.

  • username – Your username for your Jira account.

  • password – Your password for your Jira account

  • projectKey – The issues will be created for this project

The package that you downloaded also includes OEC utility which is located under /usr/local/bin and the script that is needed to be run by OEC which is under /home/opsgenie/oec/scripts. After the configuration of OEC is done, you need to run it. In order to learn more about how to run OEC, you can refer to the Running OEC documentation.

Sample parameters sent to OEC

JSON

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 { "summary":"test", "issueTypeName":"Task", "integrationName":"JIRA", "sendViaOEC":true, "description":"this is a test", "integrationId":"3af28c92-b71c-459c-8d72-04a6f7f7ebac", "url":"https://jiratestopsgenie.atlassian.net", "password":"******", "projectKey":"OPSGENIE", "integrationType":"Jira", "customerId":"04912a27-5fc1-4145-a6dd-8819afc0d870", "alias":"c570a4cc-3f57-4b60-814e-f04c63e7442d", "action":"Create", "alertId":"c570a4cc-3f57-4b60-814e-f04c63e7442d", "key":null, "mappedAction":"createIssue", "username":"jiratest@opsgenie.com" }

Troubleshooting

  1. If a mandatory custom field is set for creating an issue in Jira, a Jira issue cannot be created from an Opsgenie alert. However, by using OEC and configuring the script, the creation of Jira ticket can be achieved.

  2. If a comment cannot be added to an issue by performing an action on an alert, please look at the Logs page first. If the URL does not contain the issue key it means there is no issue on Jira which is populated from that alert. Thus it could not add a comment to a non-existing issue.

  3. Opsgenie's Jira Integration allows users to set the status of the issue to In ProgressResolvedDone or Closed in Jira. However, if the workflow of the project does not allow any of the transitions, you cannot set that transition using Opsgenie too.

Opsgenie checks the transaction names case-sensitively. Transaction names in Jira should be exactly the same. (I.e. In ProgressResolvedDone and Closed)

4. Jira does not support non-ASCII characters. Having non-ASCII characters on payload to be sent to Jira may cause 400 Bad Request Error.

5. If the Jira integration is assigned to a team, in order to create issues in Jira from alerts created in Opsgenie, the other integrations must also be assigned to the same team, or, no team must be assigned for both the Jira integration, and the other Opsgenie integrations.



Additional Help