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.

Contents

Introduction

Prerequisites

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 and above
  • JIRA Service Desk: 3.2.2 and above
  • xMatters On-Demand

Note: 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.

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 and queries xMatters for the JIRA Username stored in the JIRA Custom Field constant. 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 xMatters 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 xMatters 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.

Prerequisites

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

Create an integration user

This integration requires a user who can authenticate REST web service calls when injecting events.

This user needs to be able to work with events, but not update administrative settings. While you can use the default Company Supervisor role to authenticate REST web service calls, the best method is to create a user specifically for this integration with the "REST Web Service User" role that includes the permissions and capabilities.

Note for trial: If you are installing this integration into an xMatters trial instance, you don't need to create a new user. Instead, locate the "Integration User" sample user that was automatically configured with the REST Web Service User role when your instance was created and assign them a new password. You can then skip ahead to the next section

To create an integration user:

  1. Log in to the target xMatters system.
  2. On the Users tab, click Add.
  3. Enter the appropriate information for your new user. Because this user affects how messages appear for recipients and how events are displayed in the reports and Communication Center, you may want to identify the user as specific to this integration. For example:
    • First Name: JIRA
    • Last Name: Integration
    • User ID: jirasd
  4. Set the password for the user.
    • Make a note of the user ID and password details; you'll need them when configuring other parts of the integration.
  5. Assign the user to the REST Web Service User role.
  6. Click Add

Create users and groups that will 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. 

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 you created above, 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 you created above, 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. Log out of xMatters, and then log back in as the integration user you configured above.
  2. Navigate to the Integration Builder tab for the communication plan, and expand the list of inbound integrations.
  3. Click the name of an integration to view its details.
  4. From the drop-down list in the Select authentication method step:
    • For the Notify Assignee or Terminate inbound integration, select URL Authentication
    • For the Engage with xMatters or Engage with xMatters - Conference inbound integration, select Basic Authentication.
  5. Click Update Inbound Integration.
  6. Scroll down to the bottom of the page, and click Copy beside the field (you'll need this later to configure the JIRA plug-in):

CopyURL.jpg

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 you created above.)
    • Password: Password for authenticating to the REST API. (Enter the credentials for the integration user you created above.)
  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. 

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 Custom Field". This name is important as the code relies on this specific text to find the username. 

Download resources

 

Have more questions? Submit a request

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

     

Please sign in to leave a comment.
Powered by Zendesk