JIRA Server plugin integration

The information in this article is the intellectual property of xMatters and is intended only for use with xMatters products by xMatters customers and their employees. Further, this intellectual property is proprietary and must not be reused or resold.

Check out our built-in integration

You can now install a built-in Jira Server integration right from within xMatters, using the Integration Directory (Developer tab > Integrations). Built-in integrations simplify the integration process. They're pre-configured for your xMatters: you don't need to download and import the communication plan, or follow the configuration steps described below.

You can find instructions on installing the built-in integration in our online integration guide.

The article below is for reference if you're using an integration you originally set up from a communication plan.

Contents

Introduction

Before you begin

Configure xMatters

Configure JIRA

Test the integration

Advanced Setup

Download resources

Introduction

This article provides you with the installation, configuration, and implementation details you need to integrate xMatters On-Demand with JIRA Software and JIRA Service Desk on premise. 

The integration with JIRA:

  • Targets xMatters users or groups from JIRA issues
  • Logs event creation and notification responses to the issue
  • Automatically assigns the issue to a user who responds
  • Can create ad-hoc conference bridges targeting multiple users and groups

Supported Versions:

  • JIRA Software: 7.2.2 to 7.12.2
  • JIRA Service Desk: 3.2.2 and above
  • xMatters On-Demand

How it works

This integration is based on the plugin architecture from Atlassian and is an add-on that resides on the JIRA server. 

Issue Assignment

A webhook triggers the Notify - Assignee inbound integration. The integration transforms the payload into an xMatters event, and queries xMatters for the assignee (if one is populated) based on the JIRA Username custom field or the targetName. If the user is found, xMatters sets them as a recipient and creates the event. If they are not found, xMatters targets the form default set in the Recipients section of the form layout. 

When a user responds with "Accept", the "Notify Assignee - Response" script runs to assign the responder as the assignee in Jira. In order to do this, the User ID (targetName) in xMatters needs to match the username in Jira, or you need store the Jira username in the JIRA Username custom field. The user also needs to have access to the project in Jira and have Assignable User permissions. When the response script runs, it queries xMatters for the JIRA Username stored in the custom field. If the custom field does not exist, the script uses the user's targetName instead. The script assigns the ticket to the responder and makes a note in the Comments tab. 

The Terminate Events inbound integration can be used from a different webhook to terminate events based on updates to issues. 

Engage with xMatters

You can manually launch the Engage with xMatters workflow from within the JIRA View Issue screen by clicking the Engage button on the right side of the screen. In the Engage with xMatters dialog box, you can search for users or groups and add them to the Recipients list.

When the event is created, the Engage - Status outbound integration makes an entry in the Comments tab of the issue with the event ID. As users respond, the Engage - Response outbound integration is triggered and passes updates along to the original issue.

Before you begin

Before you get started configuring the integration, there are a couple of things you can do ahead of time to make it easier. 

Download the communication plan

To begin, download the communication plan attached to this article to a location on your local machine. The communication plan contains pre-configured integrations, forms, properties, and messages specifically designed for JIRA.

Don't extract the contents of the communication plan .zip file! You'll import it directly into xMatters.

Create JIRA User 

To allow xMatters to make updates to the JIRA issues, you need to create an xMatters user in JIRA.

When you create the user:

  • Make sure you give the user application access to both JIRA Service Desk and JIRA Software in the Create new user dialog.
  • The email address entered is not used, so it doesn't not need to actually exist. 
  • Add the user to the projects you want the xMatters integration to work with, adding the user with the Service Desk Team role.

Make note of the username and password - you'll need these when you configure xMatters.

Configure xMatters

The first step in setting up your integration is to configure xMatters.

Set up an integration user

This integration requires a user who can authenticate REST web service calls when working with events – these permissions are provided by the "REST Web Service User" role in xMatters.

For Free and Trial customers, your system has an "Integration User" already configured with the REST Web Service User role, so you don't need to burn up an extra user from your limited supply. Make sure you've changed this user's password from the default, then you're good to go.

For everyone else, we recommend you create a user specifically for this integration because this user appears as the initiator or submitter of events from the integration (in messages, the Communication Center, event reports, etc.). Give this user the "REST Web Service User" role and a profile that lets you easily identify the user as specific to the integration – for example:

  • User ID: jirasd
  • First name: Jira
  • Last name: Integration

Note: Make sure you keep the user ID and password of this user handy. You'll need them when configuring other parts of this integration. 

Create users and groups to receive notifications

You can target users directly from an issue or a supply a default group. You can also use the Engage with xMatters feature to target users or groups directly. 

You can create multiple groups and users at once using the EPIC feature.
 
For the integration to assign the responder as the assignee in Jira, the username for that person needs to be the same in both systems, or you need to set up the Jira Username custom field in xMatters.

Import and configure the communication plan

The next step is to import the communication plan.

To import the communication plan:

  1. In xMatters, click the Developer tab, and then click Import Plan.
  2. Click Choose File, and then locate the plan you downloaded from this article (the .zip file).
  3. Click Import Plan.
    • Once the import is finished, the plan should be automatically enabled. If it isn't, click Plan Disabled to enable the plan.
  4. Click the Edit drop-down list for the plan, and select Access Permissions.
  5. Add the integration user, and then click Save Changes.
  6. Click the Edit drop-down list for the plan and select Forms.
  7. For the first form in the list (Engage with xMatters), click the Web Service drop-down list, and then select Sender Permissions.
  8. Add the integration user, and then click Save Changes.
  9. Repeat steps 7-8 for each of the other forms in the plan.
  10. Click the Edit drop-down list beside the Notify Assignee form and select Layout.
  11. In the Recipients area, specify a default group to target. This group will be notified if the assignee is not populated in the issue.
  12. Finally, update the "status" list property with the correct values by clicking the Properties section of the Comm Plan. Scroll down and click the Edit Property next to "status". Enter the appropriate status values for your Jira project.

Configure the endpoints and inbound integrations

You need to retrieve the URLs for the inbound integrations and configure the integration endpoints.

Copy the inbound integration URLs

The web service calls from JIRA are sent to the inbound integrations. You need to add the URLs for each of these when configuring JIRA:

  • Engage with xMatters
  • Engage with xMatters - Conference
  • Notify Assignee
  • Terminate Events

To copy the URL for an inbound integration:

  1. In the Integration Builder, expand the list of inbound integrations.
  2. Click the name of an integration to view its details.
  3. In Select authentication method, select URL Authentication then click Save.
  4. Scroll down to How to trigger the integration at the bottom of the page, and select the integration user as the authenticating user. The URL trigger is updated to reflect the new user.
    • To be able to select the integration user, you need to be a supervisor of that user and the user needs to be assigned to the REST Web Services role.
  5. Click Copy beside the Trigger field (you'll need this later to configure the JIRA plug-in):

CopyURL.jpg

  1. Repeat steps 2-5 for the other inbound integrations.

Update the JIRA endpoint in xMatters

The endpoints in the Integration Builder hold the URL and authentication for JIRA.

  1. In the Integration Builder, click Edit Endpoints
  2. Click on the JIRA endpoint and update the Base URL and Authentication information with the appropriate values for authenticating into your JIRA instance, entering in the username and password for the xMatters user you created in JIRA
  3. Check the Preemptive box. 
  4. Click Save Changes.

Configure JIRA

You can now configure JIRA to integrate with xMatters.

Install the xMatters plugin

Option 1: Install from Marketplace

To install the xMatters add-on from the JIRA marketplace:

  1. Log into your JIRA instance as an admin.
  2. Click the admin dropdown and select Add-ons.
  3. Click Find new add-ons from the left-hand side of the page and search for xMatters.

marketplace.png

  1. Click Install to download and install your app.
  2. After the installation completes, click Close.

Option 2: Download the .jar file

If installing from the marketplace is not an option, you can download the .jar file here by clicking on the "Get it now" button at the top and selecting "For Jira Server". 

Then, login to JIRA as an admin, click the admin drop-down and select Add-ons. Click Manage Add-ons and then click the Upload add-on link. Select the .jar file and click Upload.

Upload.png

Configure the Plugin 

Configure the Engage with xMatters feature

  1. Navigate to Add-ons, and then click xMatters Configuration
  2. Fill in the following fields:
    • Endpoint: The integration URL for the Engage with xMatters inbound integration.
    • Conference Endpoint: The integration URL for the Engage with xMatters - Conference inbound integration.
    • User ID: The user ID for authenticating to retrieve the groups and users for the Engage with xMatters panel. (Enter the credentials for the integration user.)
    • Password: Password for authenticating to the REST API. (Enter the credentials for the integration user.)
  3. Click Save.

xM-Config.png

Configure issue assignment workflow

The issue assignment workflow is triggered by webhooks. The following are several examples of how to create these webhooks, but the settings for your environment may vary based on your business needs.

  1. Click the admin dropdown then select System and scroll down to display the webhooks.
  2. For each trigger listed below, click Create a WebHook, fill in the fields as outlined in the sections below, and then click Create.

Trigger One: Highest Priority Issue Created

Field Name Field Values
Name A descriptive name for the webhook
Status Click Enabled.
URL The integration URL for the Notify Assignee inbound integration.
Description Some helpful text describing the webhook.
Events Specify the following settings:
  • In the JQL query field, type:
    priority = Highest
  • Under Issue, select created

You can customize these settings later, based on your business needs.

WebhookCreateIssueHighest.png 

Trigger Two: Issue Moved to Highest Priority

Field Name Field Values
Name A descriptive name for the webhook
Status Click Enabled.
URL The integration URL for the Notify Assignee inbound integration.
Description Some helpful text describing the webhook.
Events Specify the following settings:
  • In the JQL query field, type:
    priority = Highest and priority changed
  • Under Issue, select updated

You can customize these settings later, based on your business needs.

 WebhookCreateIssueMovedToHighest.png

Caution: It is very easy to accidentally make an infinite loop when an issue is updated and xMatters then updates the issue. Make sure the webhook conditions fire only when something "changed".

Trigger Three: Terminate Events

This creates a webhook to terminate the event if the issue is resolved. 

Field Name Field Values
Name A descriptive name for the webhook
Status Enabled
URL The integration URL for the Terminate Events inbound integration.
Description Some helpful text describing the webhook.
Events

Specify the following settings:

  • In the JQL query field, type:
    resolution changed from empty
  • Under Issue, select updated

You can customize these settings later, based on your business needs.

WebhookTerminate.png

Trigger Four: Terminate events if issue priority moved to Low

This creates a webhook to terminate the event if the issue priority moves to Low. 

Field Name Field Values
Name A descriptive name for the webhook
Status Click Enabled.
URL The integration URL for the Terminate Events inbound integration.
Description Some helpful text describing the webhook.
Events

Specify the following settings:

  • In the JQL query field, type:
    priority changed TO Low
  • Under Issue, select updated

You can customize these settings later, based on your business needs.

WebhookTerminateIfLow.png

Trigger Five: Terminate events if issue deleted 

This creates a webhook to terminate the event if the issue is deleted in JIRA. 

Field Name Field Values
Name A descriptive name for the webhook
Status Click Enabled.
URL The integration URL for the Terminate Events inbound integration.
Description Some helpful text describing the webhook.
Events

Specify the following settings:

  • In the JQL query field, type:
    All issues
  • Under Issue, select deleted

You can customize these settings later, based on your business needs.

 WebhookTerminateIfDelete.png

How to use the integration

To use the Assign Issue workflow:

  1. Create a new issue that meets the criteria you defined for the Notify Assignee webhook.
  2. Target a user with a device you can access (so you can respond to the notification when it arrives) and who exists in both JIRA and xMatters.
  3. Click Accept to assign the issue, and then check that the issue is assigned to the user.

Here's an example email:

Email.png

Test Engage with xMatters:

  1. Click the Engage button to display the Engage with xMatters dialog. 

Engagepanel.png

  1. Start typing in the Recipients field to see a list of users or groups, and then select one or more recipients.
  2. Enter the remaining details, and then click Submit

This generates a new event targeting the recipients listed and delivers notifications across the users' devices. If a conference bridge was selected, a voice call invites the user to the conference bridge. An example email notification looks like this:

Engage.email.png

Troubleshooting

General Troubleshooting

The first place to look is in your browser console. There are many useful messages written here, especially anything around the Engage with xMatters dialog, retrieving users or groups from xMatters, or submitting the request to xMatters. 

Check the JIRA log, located at $JIRAHOME/log/atlassian-jira.log, for any stack traces or error messages dumped by the xMatters plugin. 

If the request is making it to xMatters, check the Activity Stream for each of the inbound or outbound integrations. 

Troubleshooting issue assignment

If you run into issues with the integration not assigning the responder as the assignee in Jira, make sure:

Advanced Setup

JIRA Custom Field

In some instances, the user ID in xMatters may not match the user ID in JIRA. Fortunately, the JIRA username can be stored in a Custom Field. Follow the steps for creating a Custom Field in xMatters, using the name "JIRA Username". This name is important as the code relies on this specific text to find the username - if you change the field name, make sure you update the value of the "JIRA Username Field Name" constant.

Download resources

 

Have more questions? Submit a request

8 Comments

  • 0
    Avatar
    Don Clark

    A heads up for any Jira Server integration users out there: I added this note to the supported versions section above.

    A client has reported an issue with Jira Server version 7.8 (version 7.7 does not seem to be affected). We're working on a change, but until we can release the fix, this integration does not work on Jira Server 7.8.

    I'll comment again as soon as we get it fixed.

     

  • 0
    Avatar
    Christine Astle

    Updated to clarify the instructions on configuring the inbound integrations.

  • 0
    Avatar
    Christopher Parsons

    When I download the communication plan and try to install it, I get a communication plan for JIRA Service Desk.  We're looking to build an integration with plain JIRA.  Does that exist?  If not, we can hack around it.

  • 0
    Avatar
    Don Clark

    Hi Christopher

    I might be going out on a bit of a limb here, but I'm pretty sure that the "JIRA Service Desk" name of the resulting plan is just a naming error. (There may have been some indecision on Atlassian's part when it came to naming their products that coincided with the development of the original plan.) The communication plan should work just fine for plain Jira.

    We also have a built-in integration available from within the Integration Directory in xMatters (look for Jira Cloud) that might suit your purposes better, though. Once it's set up, you can convert it to a communication plan for more hacking, too.

     

  • 0
    Avatar
    Kirk Friedman

    Nice Travis!

    This is very cool.  May have to try it out. 

    Do you know if there is a way to make this work with Jira Filters and subscriptions.  Right now you can create a Jira filter and have it send you an email every <x time>.  Would love to see it fire off something to xMatters instead.  

    Use case:

    If my filter spots a new high priority Jira thats still in the Open state (no one's taken care of it yet) then fire off an xMatters alert so the team can address it!

     

    Thanks,

    Kirk

  • 0
    Avatar
    Travis DePuy

    Hmm, I'm guessing you mean these? It doesn't look like Jira provides a webhook and instead only allows for email. However, you could set up an Inbound Email integration that would then send those along to you or your group. 

    The email format might be a little funky, but it should work. 

  • 0
    Avatar
    Don Clark

    As promised, commenting to confirm that the integration does work with Jira Server 7.8.

  • 0
    Avatar
    Christine Astle

    Updated the attached communication plan to support Jira Server versions up to 7.12.2.

Please sign in to leave a comment.
Powered by Zendesk