Log InStart Free Trial

Jira Service Desk Integration

Jira Service Desk is a collaborative IT service desk with a powerful ticketing system, a self-service knowledge base, and real-time reporting.

Suggest Edits

What does Opsgenie offer Jira Service Desk users?

Opsgenie provides a powerful two-way integration with Jira Service Desk. When a new issue is created in Jira Service Desk, a corresponding Opsgenie alert is automatically created, containing rich information about the issue. Opsgenie provides rich notifications with on-call rotations, scheduling features, and alert escalations to ensure the best alert and incident management for Jira Service Desk customers. As users execute actions on the alerts, like acknowledge or snooze, the issue in Jira Service Desk automatically updates with comments about these alert actions. If users close the alert, the issue in Jira Service Desk is resolved (Only if the issue has a Resolve the issue transition).

Functionality of the integration

Jira Service Desk to Opsgenie:

  • When an issue is created in Jira Service Desk, an alert is created in Opsgenie.
  • When a comment is added to issue in Jira Service Desk, the same comment is added as a note to the alert in Opsgenie.
  • When an issue is closed and resolved in Jira Service Desk, the alert in Opsgenie is closed.

Opsgenie to Jira Service Desk:

  • If Send Alert Updates Back to Jira Service Desk is enabled, actions for Jira Service Desk are executed in Jira Service Desk when the chosen action is executed in Opsgenie for alerts which are created by the Jira Service Desk integration.
  • If Create Jira Service Desk Issues for Opsgenie Alerts is enabled, actions for Jira Service Desk are executed in Jira Service Desk when the chosen action is executed in Opsgenie for alerts which have a source other than the Jira Service Desk integration.
  • This action mapping features are explained in detail in the Action Mapping Feature section below.

📘

If the data from Jira ServiceDesk is larger than 200KB, we truncate the data and only accept the fields shown in the "Sample Truncated Data" section below.

Adding Jira Service Desk Integration in Opsgenie

  1. Please create an Opsgenie account if you haven't done so already.
  2. Go to the Jira Service Desk Integration page.
  3. Specify who is notified of Jira Service Desk alerts using the Teams field. Auto-complete suggestions are provided as you type.
  4. Copy the integration URL to use in the Jira Service Desk configuration.
  5. Click Save Integration.

🚧

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.

🚧

Users who don't have Atlassian Account

Users who are authenticating against the REST API but do not have Atlassian Accounts, need to convert them to Atlassian Account. You can check here to see the instructions to convert Atlassian Account.

Action Mapping Feature

  • Opsgenie allows customers to define action mappings between Opsgenie actions and Jira Service Desk actions.
  • To use the Action Mappings feature, provide some information to the integration which are listed below:
  • Issue Type Name: The issue types defined in Jira Service Desk e.g. Task, IT Help, Sub-task, Service Request or any other custom defined type. Make sure you write the issue type syntax error free.
  • Jira Service Desk URL: This is the domain name of your service desk e.g. https://testops.atlassian.net
  • Username: The e-mail address you use to login to Jira Service Desk.
  • Password: The password you use to login to Jira Service Desk.
  • 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 Service Desk

  • You can use this section to map Opsgenie actions to Jira Service Desk actions when the source of the alert is Jira Service Desk (i.e When the alert is created by Jira Service Desk integration.)
  • You can map different Opsgenie actions to different Jira Service Desk actions. For example, you can add note to Jira Service Desk 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 the issue in Jira Service Desk. mapping in Send Alert Updates Back to Jira Service Desk section.

For other Opsgenie alerts

  • You can use this section to map Opsgenie actions to Jira Service Desk actions when the source of the alert is NOT Jira Service Desk (i.e When the alert is created by another integration.)
  • For this purpose, you can use Create Jira Service Desk Issues for Opsgenie Alerts section. In order to use this functionality, you need to map one Opsgenie action to create an issue Jira Service Desk 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 is added 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. For the mapping to work for any tag, leave the tags field empty.
  • If an Opsgenie action is mapped to multiple Jira Service Desk 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.

Configuration in Jira Service Desk

  1. On the Jira Service Desk dashboard, go to Project Settings.
  1. Click Automation.
  1. Click Add Rule on the right side of the screen.
  1. Select Custom Rule from the list and click Next.
  2. Give a name to the rule e.g. "Opsgenie".
  3. Click Add Trigger in "WHEN" section.
  1. Add Issue created, Issue resolution changed, Status change, Comment added and Comment edited.
  2. Click Add Action in the "THEN" section.
  3. Select Webhook and click Add.
  4. Paste the Opsgenie Jira Service Desk URL copied previously into URL field.
  5. Check Include payload in request body.
  6. Make sure enabled is checked and click Save.

Now manage your Jira Service Desk alerts at Opsgenie and leverage its full alerting functionality.

Sample payload sent from Jira Service Desk

Create Alert payload:

{
  "issue": {
    "id": "10042",
    "self": "https://test.atlassian.net/rest/api/2/issue/10042",
    "key": "TEST-43",
    "fields": {
      "issuetype": {
        "self": "https://test.atlassian.net/rest/api/2/issuetype/10000",
        "id": "10000",
        "description": "For system outages or incidents. Created by JIRA Service Desk.",
        "iconUrl": "https://test.atlassian.net/servicedesk/issue-type-icons?icon=incident",
        "name": "Incident",
        "subtask": false
      },
      "timespent": null,
      "project": {
        "self": "https://test.atlassian.net/rest/api/2/project/10000",
        "id": "10000",
        "key": "TEST",
        "name": "Test",
        "avatarUrls": {
          "48x48": "https://test.atlassian.net/secure/projectavatar?avatarId=10324",
          "24x24": "https://test.atlassian.net/secure/projectavatar?size=small&avatarId=10324",
          "16x16": "https://test.atlassian.net/secure/projectavatar?size=xsmall&avatarId=10324",
          "32x32": "https://test.atlassian.net/secure/projectavatar?size=medium&avatarId=10324"
        }
      },
      "fixVersions": [],
      "aggregatetimespent": null,
      "resolution": null,
      "customfield_10027": {
        "id": "1",
        "name": "Time to resolution",
        "_links": {
          "self": "https://test.atlassian.net/rest/servicedeskapi/request/10042/sla/1"
        },
        "completedCycles": [
          {
            "startTime": {
              "iso8601": "2016-06-27T11:25:37+0300",
              "jira": "2016-06-27T11:25:37.877+0300",
              "friendly": "Today 11:25 AM",
              "epochMillis": 1467015937877
            },
            "stopTime": {
              "iso8601": "2016-06-27T11:37:33+0300",
              "jira": "2016-06-27T11:37:33.572+0300",
              "friendly": "Today 11:37 AM",
              "epochMillis": 1467016653572
            },
            "breached": false,
            "goalDuration": {
              "millis": 14400000,
              "friendly": "4h"
            },
            "elapsedTime": {
              "millis": 715695,
              "friendly": "11m"
            },
            "remainingTime": {
              "millis": 13684305,
              "friendly": "3h 48m"
            }
          }
        ],
        "ongoingCycle": {
          "startTime": {
            "iso8601": "2016-06-27T16:01:45+0300",
            "jira": "2016-06-27T16:01:45.920+0300",
            "friendly": "Today 4:01 PM",
            "epochMillis": 1467032505920
          },
          "breachTime": {
            "iso8601": "2016-06-28T12:01:45+0300",
            "jira": "2016-06-28T12:01:45.920+0300",
            "friendly": "28/Jun/16 12:01 PM",
            "epochMillis": 1467104505920
          },
          "breached": false,
          "paused": false,
          "withinCalendarHours": true,
          "goalDuration": {
            "millis": 14400000,
            "friendly": "4h"
          },
          "elapsedTime": {
            "millis": 197118,
            "friendly": "3m"
          },
          "remainingTime": {
            "millis": 14202882,
            "friendly": "3h 56m"
          }
        }
      },
      "customfield_10028": {
        "id": "2",
        "name": "Time to first response",
        "_links": {
          "self": "https://test.atlassian.net/rest/servicedeskapi/request/10042/sla/2"
        },
        "completedCycles": [
          {
            "startTime": {
              "iso8601": "2016-06-27T11:25:37+0300",
              "jira": "2016-06-27T11:25:37.877+0300",
              "friendly": "Today 11:25 AM",
              "epochMillis": 1467015937877
            },
            "stopTime": {
              "iso8601": "2016-06-27T11:37:33+0300",
              "jira": "2016-06-27T11:37:33.572+0300",
              "friendly": "Today 11:37 AM",
              "epochMillis": 1467016653572
            },
            "breached": false,
            "goalDuration": {
              "millis": 14400000,
              "friendly": "4h"
            },
            "elapsedTime": {
              "millis": 715695,
              "friendly": "11m"
            },
            "remainingTime": {
              "millis": 13684305,
              "friendly": "3h 48m"
            }
          }
        ]
      },
      "resolutiondate": null,
      "workratio": -1,
      "lastViewed": "2016-06-27T16:01:46.447+0300",
      "watches": {
        "self": "https://test.atlassian.net/rest/api/2/issue/TEST-43/watchers",
        "watchCount": 1,
        "isWatching": true
      },
      "created": "2016-06-27T11:25:37.859+0300",
      "customfield_10020": "Not started",
      "customfield_10021": null,
      "customfield_10022": null,
      "priority": {
        "self": "https://test.atlassian.net/rest/api/2/priority/3",
        "iconUrl": "https://test.atlassian.net/images/icons/priorities/medium.svg",
        "name": "Medium",
        "id": "3"
      },
      "customfield_10023": [],
      "customfield_10024": null,
      "customfield_10025": null,
      "labels": [],
      "customfield_10026": null,
      "customfield_10016": null,
      "customfield_10017": null,
      "customfield_10018": null,
      "customfield_10019": null,
      "timeestimate": null,
      "aggregatetimeoriginalestimate": null,
      "versions": [],
      "issuelinks": [],
      "assignee": null,
      "updated": "2016-06-27T16:05:02.852+0300",
      "status": {
        "self": "https://test.atlassian.net/rest/api/2/status/10001",
        "description": "This was auto-generated by JIRA Service Desk during workflow import",
        "iconUrl": "https://test.atlassian.net/images/icons/status_generic.gif",
        "name": "Waiting for support",
        "id": "10001",
        "statusCategory": {
          "self": "https://test.atlassian.net/rest/api/2/statuscategory/1",
          "id": 1,
          "key": "undefined",
          "colorName": "medium-gray",
          "name": "No Category"
        }
      },
      "components": [],
      "timeoriginalestimate": null,
      "description": "test description",
      "customfield_10010": null,
      "customfield_10011": null,
      "customfield_10012": null,
      "customfield_10013": null,
      "customfield_10014": null,
      "timetracking": {},
      "customfield_10015": null,
      "customfield_10007": "0|i0009b:",
      "customfield_10008": "com.atlassian.serv[email protected]cf82e6",
      "attachment": [],
      "customfield_10009": null,
      "aggregatetimeestimate": null,
      "summary": "New Summary",
      "creator": {
        "self": "https://test.atlassian.net/rest/api/2/user?username=admin",
        "name": "admin",
        "key": "admin",
        "emailAddress": "[email protected]",
        "avatarUrls": {
          "48x48": "https://secure.gravatar.com/avatar/asd0a6bb5e5c8ce4c5152b54b45ee5c?d=mm&s=48",
          "24x24": "https://secure.gravatar.com/avatar/asd0a6bb5e5c8ce4c5152b54b45ee5c?d=mm&s=24",
          "16x16": "https://secure.gravatar.com/avatar/asd0a6bb5e5c8ce4c5152b54b45ee5c?d=mm&s=16",
          "32x32": "https://secure.gravatar.com/avatar/asd0a6bb5e5c8ce4c5152b54b45ee5c?d=mm&s=32"
        },
        "displayName": "Administrator",
        "active": true,
        "timeZone": "Europe/Helsinki"
      },
      "subtasks": [],
      "reporter": {
        "self": "https://test.atlassian.net/rest/api/2/user?username=admin",
        "name": "admin",
        "key": "admin",
        "emailAddress": "[email protected]",
        "avatarUrls": {
          "48x48": "https://secure.gravatar.com/avatar/asd0a6bb5e5c8ce4c5152b54b45ee5c?d=mm&s=48",
          "24x24": "https://secure.gravatar.com/avatar/asd0a6bb5e5c8ce4c5152b54b45ee5c?d=mm&s=24",
          "16x16": "https://secure.gravatar.com/avatar/asd0a6bb5e5c8ce4c5152b54b45ee5c?d=mm&s=16",
          "32x32": "https://secure.gravatar.com/avatar/asd0a6bb5e5c8ce4c5152b54b45ee5c?d=mm&s=32"
        },
        "displayName": "Administrator",
        "active": true,
        "timeZone": "Europe/Helsinki"
      },
      "customfield_10000": null,
      "aggregateprogress": {
        "progress": 0,
        "total": 0
      },
      "customfield_10001": null,
      "customfield_10002": null,
      "customfield_10003": null,
      "environment": null,
      "duedate": null,
      "progress": {
        "progress": 0,
        "total": 0
      },
      "comment": {
        "comments": [
          {
            "self": "https://test.atlassian.net/rest/api/2/issue/10042/comment/10027",
            "id": "10027",
            "author": {
              "self": "https://test.atlassian.net/rest/api/2/user?username=admin",
              "name": "admin",
              "key": "admin",
              "emailAddress": "[email protected]",
              "avatarUrls": {
                "48x48": "https://secure.gravatar.com/avatar/asd0a6bb5e5c8ce4c5152b54b45ee5c?d=mm&s=48",
                "24x24": "https://secure.gravatar.com/avatar/asd0a6bb5e5c8ce4c5152b54b45ee5c?d=mm&s=24",
                "16x16": "https://secure.gravatar.com/avatar/asd0a6bb5e5c8ce4c5152b54b45ee5c?d=mm&s=16",
                "32x32": "https://secure.gravatar.com/avatar/asd0a6bb5e5c8ce4c5152b54b45ee5c?d=mm&s=32"
              },
              "displayName": "Administrator",
              "active": true,
              "timeZone": "Europe/Helsinki"
            },
            "body": "test comment",
            "updateAuthor": {
              "self": "https://test.atlassian.net/rest/api/2/user?username=admin",
              "name": "admin",
              "key": "admin",
              "emailAddress": "[email protected]",
              "avatarUrls": {
                "48x48": "https://secure.gravatar.com/avatar/asd0a6bb5e5c8ce4c5152b54b45ee5c?d=mm&s=48",
                "24x24": "https://secure.gravatar.com/avatar/asd0a6bb5e5c8ce4c5152b54b45ee5c?d=mm&s=24",
                "16x16": "https://secure.gravatar.com/avatar/asd0a6bb5e5c8ce4c5152b54b45ee5c?d=mm&s=16",
                "32x32": "https://secure.gravatar.com/avatar/asd0a6bb5e5c8ce4c5152b54b45ee5c?d=mm&s=32"
              },
              "displayName": "Administrator",
              "active": true,
              "timeZone": "Europe/Helsinki"
            },
            "created": 1467032702852,
            "updated": 1467032702852
          }
        ],
        "maxResults": 1,
        "total": 1,
        "startAt": 0
      },
      "votes": {
        "self": "https://test.atlassian.net/rest/api/2/issue/TEST-43/votes",
        "votes": 0,
        "hasVoted": false
      },
      "worklog": {
        "startAt": 0,
        "maxResults": 20,
        "total": 0
      }
    }
  },
  "timestamp": 1467032703044
}

Integration via Marid (for On Premise Jira Service Desk 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 Service Desk. This enables deployment of your own scripts/ability to modify the ones provided and execute customized actions on Jira Service Desk.

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

Download and install Jira Service Desk package

For Red Hat Based Distributions

🚧

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

For Windows

  • Download Opsgenie Jira Service Desk (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 to 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 Service Desk Integration for Marid

  • In order to use Marid utility, enable Send Via Marid.
  • Other configurations regarding Jira Service Desk 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 Service Desk 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 Service Desk, 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

jiraServiceDesk.issueType

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

jiraServiceDesk.url

Your Jira Service Desk url where the issues will be created, resolved, closed etc.

jiraServiceDesk.username

Your username for your Jira Service Desk account

jiraServiceDesk.password

Your password for your Jira Service Desk account

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

mappedActions.addCommentToIssue.script

jiraActionExecutor.groovy

mappedActions.createIssue.script

jiraActionExecutor.groovy

mappedActions.resolveIssue.script

jiraActionExecutor.groovy

Sample parameters sent to Marid

{
  "summary":"test",
  "issueTypeName":"Task",
  "integrationName":"Jira Service Desk",
  "sendViaMarid":true,
  "description":"this is a test",
  "integrationId":"3af28c92-b71c-459c-8d72-04a6f7f7ebac",
  "url":"https://jiratestopsgenie.atlassian.net",
  "password":"******",
  "projectKey":"OPSGENIE",
  "integrationType":"JiraServiceDesk",
  "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]"
}

Sample Truncated Data

{
  "isTruncated": true,
  "summary": "test bug issue",
  "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]"
}

Troubleshooting

  1. If a mandatory custom field is set for creating an issue in Jira ServiceDesk, a Jira ServiceDesk issue cannot be created from an Opsgenie alert.
  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 in Jira ServiceDesk populated from that alert. Thus it could not add a comment to a non-existing issue.
  3. Opsgenie's Jira ServiceDesk Integration allows setting the status of the issue to RESOLVED in Jira ServiceDesk. However, if the workflow of the project does not allow that transitions, you cannot set that transition using Opsgenie too.
  4. Jira ServiceDesk does not support non-ASCII characters. Having non-ASCII characters on payload to be sent to Jira ServiceDesk may cause 400 Bad Request Error.
  5. If the Jira Service Desk integration is assigned to a team, in order to create issues in Jira Service Desk 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 Service Desk integration and the other Opsgenie integrations.

Updated almost 3 years ago

Did this page help you?