JIRA Integration

 is an extremely popular project and issue tracking application. OpsGenie is an alert and notification management solution that is highly complementary to JIRA.

​What does OpsGenie offer to JIRA users?

OpsGenie has a specific update set which allows bi-directional integration between OpsGenie and JIRA. Using the integration, JIRA sends issues to OpsGenie, with detailed information. And OpsGenie forwards alerts as issues to JIRA. OpsGenie can determine the right people to notify based on on-call schedules, using email, text messages (SMS), phone calls and iOS & Android push notifications, and escalating alerts until the alert is acknowledged or closed.

OpsGenie provides a Marid 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 will be closed on OpsGenie automatically.
  • When a comment is added on 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 will be executed in JIRA when the chosen action is executed in OpsGenie for alerts which are created by the JIRA integration.
  • If Create JIRA Incidents for OpsGenie Alerts is enabled, actions for JIRA will be 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.
If the data from JIRA is too big (larger than 200KB), we truncate the data and only accept the fields shown in the "Sample Truncated Data" section below

Adding JIRA Integration in OpsGenie

  1. Please create an OpsGenie account if you haven't done already
  2. Go to OpsGenie JIRA Integration page,
  3. Specify who should be notified for JIRA alerts using the "Recipients" field. User(s), group(s), escalations policies and on-call schedules can be specified as the alert recipients. Auto-complete suggestions will be provided as you type. 
  4. Copy the integration URL by clicking on the copy button or selecting. URL includes OpsGenie endpoint as well as the API key.
  5. Click on "Save Integration".

Configuration on JIRA

  1. Login to JIRA as administrator.
  2. From the dashboard, open Administration menu. Select "System".
  3. From the left, select "Webhooks" under "Advanced".
  4. Click "Create A Webhook". In the opening section, paste the Url provided by OpsGenie's JIRA integration into URL input. Click "Create".

Now that the webhook is configured, JIRA will notify OpsGenie when changes are made to issues. OpsGenie will in follow create alerts and track them.

Action Mapping Feature

  • OpsGenie allows customers to define action mappings between OpsGenie actions and JIRA actions.

  • For alerts created by JIRA
  • You can 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.)
  • You can map different OpsGenie actions to different JIRA actions. For example, you can add comment to JIRA issue, when the alert is acknowledged. In order to do this, you should define If alert is acknowledged in OpsGenie, add it as a comment to issue in JIRA. mapping in Send Alert Updates Back to JIRA section.

  • For other OpsGenie alerts
  • You can 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, you can use Create JIRA Issues for OpsGenie Alerts section. In order to use this functionality, you need to 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 tag is added to the alert and a custom action is executed on alert actions differ from other actions. When you select one of these actions, you'll see an extra field to enter for which tags or for which custom action this mapping will work.
  • You can enter multiple tags by separating the tags with a comma. If you enter multiple tags, the mapping will work if the alert has one or more of the specified tags. You can also leave the tags field empty, if you would like the mapping to work for any tag.
  • If you select a custom action mapping, you must specify the name of the custom action that the mapping will work. It cannot be left empty.
  • If you map an OpsGenie action to multiple JIRA actions, you will get an error except for the a tag is added to the alert and a custom action is executed on alert actions. You can save multiple mappings for these actions, because they will differ by the given tags and the given custom action names.
OpsGenie JIRA Integration allows you to set the status of the issue to IN PROGRESS, RESOLVED, DONE 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.

Sample payload sent from JIRA

{
  "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
}

Sample Truncated Data

{
  "isTruncated": true,
  "summary": "test bug issu3",
  "components": ["Admin Web Application", "Data Collector", "Mobile App"],
  "user_email": "mustafa.sener@ifountain.com",
  "action_type": "Commented",
  "project_key": "NAAS",
  "created": "2014-02-12T09:59:28.107-0500",
  "reporter_email_address": "mustafa.reporter@ifountain.com",
  "issue_type": "Bug",
  "webhookEvent": "jira:issue_created",
  "priority": "Major",
  "event_type_name": "issue_created",
  "labels": ["label2", "label3", "label1"],
  "comment_author": "",
  "versions": ["v0.1", "v0.2", "iPhone v0.2"],
  "key": "NAAS-155",
  "status": "Open",
  "comment_body": "",
  "description": "test description",
  "assignee_email_address": "mberkay.assignee@gmail.com"
}

Integration via Marid (for On Premise JIRA Usage)

Alternatively, you can use OpsGenie's JIRA integration package to create/update issues on JIRA. This will enable you to deploy your own scripts / modify the ones provided and execute customized actions on JIRA.

To use JIRA integration package, you need to follow the steps in the sections below through the end.

Download and install JIRA package

For Red Hat Based Distributions
During upgrades, rpm package does not overwrite your existing configurations. It saves the new default configuration file as opsgenie-integration.conf.rpmnew. You can find more information about rpm upgrade config file handling from here.
For Debian Based Distributions For Windows
  • Download OpsGenie JIRA (Windows)
  • Unzip opsgenie integration zip file which contains Marid package into a directory (C:\opsgenie-integration is the preferred path. C:\opsgenie-integration\marid will be referred as MARID_HOME in the rest of documentation.)
  • To install Marid as a service:
    • Open a command window
    • Go to <MARID_HOME> directory
    • For 32 bit systems, run marid.exe -install
    • For 64 bit systems, run marid_64.exe -install
    Name of the service will be assigned to "OpsGenie Marid"
To set JAVA_HOME environment variable, refer to Setting JAVA_HOME for more information.
To enable Ruby scripting, you need to download JRuby Complete jar file and put this jar file in lib directory (/var/lib/opsgenie/marid On Linux, MARID_HOME/lib on Windows systems.).
You may need to restart your system after setting JAVA_HOME environment variable for Windows XP/2000/2003 operating systems due to problem reported at http://support.microsoft.com/kb/821761

Configuring JIRA Integration for Marid

  • In order to use Marid utility, enable Send Via Marid.
  • Other configurations regarding JIRA can be done either via integration page or Marid configuration file opsgenie-integration.conf. Configuration in integration page will precede the configuration file.

Marid Configuration

The plugin uses Marid utility (included in the plugin) to update issues on JIRA when alerts are updated.

  • To start Marid, run the following command:
    /etc/init.d/marid start 
  • To stop Marid, run the following command:
    /etc/init.d/marid stop 

Marid is a java application; therefore requires the Java Runtime version 1.6+ Both the Open JDK and Oracle JVMs can be used.

Ensure that JAVA_HOME environment variable is set. If it is not, you may set it by removing the comment at the begining of the following line in /etc/opsgenie/profile file and set JAVA_HOME to your JRE installation directory.
#JAVA_HOME=<path/to/JDK or JRE/install>

To be able to execute actions on JIRA, Marid gets the configuration parameters from /etc/opsgenie/conf/opsgenie-integration.conf file.

Configuration Parameters
apiKey Copy the API key from the JIRA integration you've created above
jira.issueType Type of the issue which can be "Task", "Bug", "Story" or your custom issue type ("Epic" is not supported!)
jira.url Your JIRA url where the issues will be created, resolved, closed etc.
jira.username Your username for your JIRA account
jira.password Your password for your JIRA account
jira.projectKey The issues will be created for this project

According to the action that will be executed in JIRA, the script to be run can be set here. OpsGenie's script is set by default; you can change the following configuration to run your own custom script if you like.

Action Mappings
mappedActions.addCommentToIssue.script jiraActionExecutor.groovy
mappedActions.createIssue.script jiraActionExecutor.groovy
mappedActions.resolveIssue.script jiraActionExecutor.groovy
mappedActions.closeIssue.script jiraActionExecutor.groovy
mappedActions.issueDone.script jiraActionExecutor.groovy
mappedActions.inProgressIssue.script jiraActionExecutor.groovy

Sample params sent to Marid

{
  "summary":"test",
  "issueTypeName":"Task",
  "integrationName":"JIRA",
  "sendViaMarid":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 you set a mandatory custom field for creating an issue in JIRA, you cannot create a JIRA issue from an OpsGenie alert.
  2. If you cannot add comment to an issue by performing an action on an alert, please look at our 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 JIRA Integration allows you to set the status of the issue to IN PROGRESS, RESOLVED, DONE 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.
  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.