JIRA Service Desk 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

Configure xMatters

Configure JIRA

Test the integration

Advanced Setup

Download resources

Introduction

This article provides installation, configuration, and implementation details when integrating xMatters On-Demand with JIRA Service Desk on premise. 

The integration with JIRA Service Desk:

  • 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 Core: 7.2.2 and above
  • JIRA Service Desk: 3.2.2 and above
  • xMatters: 5.5.136 and above

Download the communication plan

To begin, download the communication plan attached to this article to a location on your local machine. You do not need to extract the contents.

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 an HTTP call to the Notify - Assignee inbound integration. The integration script builds the event payload, 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

Users 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, the user can search for users or groups and add them to the Recipients list.

After completing the form, the user clicks Submit, which sends the payload and recipients to the Engage with xMatters inbound integration, which triggers an event. 

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. 

Configure xMatters

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

Create a REST API user

This integration requires a REST API user to authenticate REST web service calls when injecting events.

This user needs to be able to work with events, but not update administrative settings. The best way to create a user for this integration is to have a dedicated "REST Web Service User" role that includes the permissions and capabilities. If this role does not exist in your deployment, you will need to create it, or ask your xMatters Client Success Manager to create it for you. (For detailed procedures about creating the role, see Authentication and Permissions.)

In the following example, this role is named "REST Web Service User".

To create a REST API user:

  1. Log in to the target xMatters system.
  2. On the Users tab, click the Add New User icon.
  3. Enter the appropriate information for your new user. Because this user will affect how messages appear for recipients and how events will be displayed in the reports and Communication Center, you may want to identify the user as specific to JIRA; for example:
    • First Name: JIRA
    • Last Name: Integration
    • User ID: jirasd
  4. In the Roles area, add the REST Web Service User, Group Supervisor and Person Supervisor roles.
  5. Click Save.
  6. On the next page, set the web login ID and password. 
Make a note of these details; you will need them when configuring other parts of this integration.

Create users and groups

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 the communication plan

The next step is to import the communication plan.

To import the communication plan:

  1. In the target xMatters system, on the Developer tab, click Import Plan.
  2. Click Browse, and then locate the downloaded JIRAServiceDesk-CommPlan.zip file.
  3. Click Import Plan.
  4. In the Edit drop-down list, select Forms.
  5. In the Web Service Only drop-down list, click Permissions.
  6. Enter the REST API user you created above, and then click Save Changes.
  7. Repeat steps 7-9 for each of the remaining forms in the plan.

Finally, navigate to the Notify Assignee form and click Edit > Layout. In the Recipients area, specify a default group to target. This group will be notified if the assignee is not populated in the issue.

Update endpoints

The endpoints in the Integration Builder hold the authentication into xMatters as well as the URL and authentication for JIRA. Navigate to the Integration Builder and click Edit Endpoints. Click the xMatters endpoint and assign the endpoint to the REST API User created above.

Click on the JIRA endpoint and update the Base URL and Authentication information with the appropriate values for authenticating into your JIRA instance. 

Access integration URLs

The web service calls from JIRA are sent to inbound integration endpoints. These can be found by expanding the list of inbound integrations in the Integration Builder. Click the gear icon next to each integration, and then select Integration URL.  

When configuring JIRA, you will need the URL for each of the inbound integrations:

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

Configure JIRA Service Desk

Install the Plugin

You can now configure JIRA to integrate with xMatters.

Option 1: Install from Marketplace

To begin, install the xMatters add-on from the JIRA marketplace by clicking on the gear icon > Add-ons and search for xMatters. 

Click the Install button and click Close on the dialog.

 

Option 2: Download jar file

If installing from the marketplace is not an option, the jar file can be downloaded from here and clicking on the "Get it now" button at the top. 

Then, login to JIRA and click the gear icon > Add-ons. Click Manage Add-ons and click the Upload add-on link. Select the jar file and click Upload.

 

Configure the Plugin 

Configure the Engage with xMatters feature:
  1. Navigate to Add-ons, and then click xMatters Configuration
  2. Populate the following fields, and then click Save:

Field descriptions

Field Name Field Values
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 REST API user you created above.)
Password Password for authenticating to the REST API

To configure issue assignment:

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

  1. Navigate to System settings and scroll down to display the webhooks.
  2. Click Create a WebHook, populate the following fields, 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 SQL query field, type:
    priority = Highest
  • Under Issue, select created

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

 

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 SQL query field, type:
    priority = Highest and priority changed
  • Under Issue, select updated

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

  
 
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

Next, create another webhook to terminate the event if the issue is resolved; click Create a WebHook again, and then populate the following fields: 

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

Specify the following settings:

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

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

 

Create JIRA User 

 To allow xMatters to make updates to the JIRA issues, a user must be created.

Click the gear icon and click User Management. Click Create User and populate the fields:

 

 

Field Value
Email An email address. This will not be used and does not need to be a valid email address. 
Full Name Full name of the integration user. "xMatters Integration" is helpfully descriptive
Username The username for authentication
Password The password for authentication
Application Access

Mark both boxes:
JIRA Service Desk
JIRA Software

 

Next, the user needs to be added to the Project. Click on the gear icon > Projects. Click on the appropriate project that the xMatters integration will be working with. Then scroll down and click Users and roles. Click on the "Add users to a role" link in the upper right and type the name of the xMatters user above. Select "Service Desk Team" and click Add. 

Finally, update the endpoint in the JIRA Communications Plan in xMatters to hold the username and password. Make sure to check the Preemptive checkbox. 


Test the integration

Test Issue Workflow

To test the Assign Issue workflow, create a new issue that meets the criteria you defined for the Notify Assignee webhook. This will target the default group defined in the Notify Assignee form layout. The members of this group will receive notifications based on their device schedules and settings. For example, an email will look like this:

Click Accept to assign the issue, and check the and the issue will be assigned to you. 

Test Engage with xMatters

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

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

This will generate a new event targeting the recipients listed and deliver notifications across the users' devices. If a Conference Bridge was selected, a voice call can invite the user to the conference bridge. An email notification will look like this:

Troubleshooting

General Troubleshooting

The first place to look is in the 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. 

The JIRA log located at $JIRAHOME/log/atlassian-jira.log will have any stack traces or error messages dumped by the xMatters plugin. 

If the request is making it to xMatters, then the Activity Stream for each of the inbound or outbound integrations will have the most help. 

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

Download resources

 

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk