What does Opsgenie offer to Jira users?

Opsgenie has a specific update set which 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 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 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.

📘
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

Please create an Opsgenie account if you haven't done so already.
Go to Opsgenie Jira Integration page.
Specify who is notified of Jira alerts using the Teams field. Auto-complete suggestions are provided as you type.
Copy the integration URL which includes the Opsgenie endpoint as well as the API key.
Click Save Integration.

Configuration in Jira

Log in to Jira as an administrator.
From the dashboard, open the Administration menu. Select System.
From the left, select Webhooks under "Advanced".

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 then creates alerts and track them.

🚧
Using SSO?
If you are using SSO to login to Jira, you need to generate an API token and use this token as the password in the integration settings password field. View these instructions to generate an API token in Jira.
After generating your new token, copy and paste it to the password field of the Jira Service Desk integration in Opsgenie. Save the integration.

Action Mapping Feature

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

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 Opsgenie, add it as a comment to issue in Jira. mapping in Send Alert Updates Back to Jira section.

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 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 PROGRESS, RESOLVED, DONE 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

{
  "webhookEvent": "jira:issue_created",
  "user": {
    "self": "https://ifountain.atlassian.net/rest/api/2/user?username=msener",
    "name": "msener",
    "emailAddress": "[email protected]",
    "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": "[email protected]",
        "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": "[email protected]",
        "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": "[email protected]",
        "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": "[email protected]",
  "action_type": "Commented",
  "project_key": "NAAS",
  "created": "2014-02-12T09:59:28.107-0500",
  "reporter_email_address": "[email protected]",
  "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": "[email protected]"
}

Integration via Marid (for On Premise Jira Usage)

🚧
If you are using Opsgenie Edge Connector instead of Marid, you can find the integration specific script and its sample config from here. For more information about OEC, please refer OEC Integration documentation

Alternatively, use Opsgenie's Jira integration package to create/update issues on Jira. This enables deployment of your own scripts/ability to modify the ones provided and execute customized actions on Jira.

To use Jira integration package, follow the steps in the sections below through the end.

Download and install Jira package

For Red Hat Based Distributions

Download Opsgenie Jira (Linux RPM)
Run the following command :
rpm -i opsgenie-jira-<your_version>.rpm

🚧
During upgrades, rpm package does not overwrite existing configurations. It saves the new default configuration file as opsgenie-integration.conf.rpmnew. Find more information about rpm upgrade config file handling from here.

For Debian Based Distributions

Download Opsgenie Jira (Linux DEB)
Run the following command :
dpkg -i opsgenie-jira-<your_version>.deb

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.).

🚧
A restart your system may be needed after setting JAVA_HOME environment variable for Windows XP/2000/2003 operating systems due to a 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 are done either via integration page or Marid configuration file opsgenie-integration.conf. Configuration on the integration page precedes 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, set it by removing the comment at the beginning 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 in Jira, Marid gets the configuration parameters from /etc/opsgenie/conf/opsgenie-integration.conf file.

Configuration Parameter	Description
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 to be executed in Jira, the script to be run is set here. Opsgenie's script is set by default; change the following configuration to run custom script if you like.

Action Mappings	FIle Name
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 parameters 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":"[email protected]"
}

Troubleshooting

If a mandatory custom field is set for creating an issue in Jira, a Jira issue cannot be created from an Opsgenie alert.
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.
Opsgenie's Jira Integration allows users 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.

🚧
Opsgenie checks the transaction names case-sensitively. Transaction names in Jira should be exactly the same. (I.e. In Progress, Resolved, Done and Closed)

Jira does not support non-ASCII characters. Having non-ASCII characters on payload to be sent to Jira may cause 400 Bad Request Error.
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.

What does Opsgenie offer to Jira users?

Functionality of the integration

📘

Adding Jira Integration in Opsgenie

Configuration in Jira

🚧Using SSO?

Action Mapping Feature

For alerts created by Jira

For other Opsgenie alerts

📘

Sample payload sent from Jira

Sample Truncated Data

Integration via Marid (for On Premise Jira Usage)

🚧

Download and install Jira package

🚧

📘

📘

🚧

Configuring Jira Integration for Marid

Marid Configuration

📘

Sample parameters sent to Marid

Troubleshooting

🚧

🚧
Using SSO?