JIRA Integration


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

NOTE: This integration is based on the xMatters Integration Builder, available as part of the Blue Steel release. For Integration Builder documentation, see the xMatters On-Demand help.

How it works

JIRA is a cloud-based, proprietary issue tracking product, developed by Atlassian. Coupled with the power of xMatters alerts, the integration:

  • Quickly identifies and notifies the on-call resource on a variety of devices.
  • Allows for voice, SMS, and push messages to users.
  • Allows users to reply with "Assign to me" from their device and take ownership of the issue.

Event injection is initiated when an incident in JIRA matches the rules contained within a webhook. JIRA builds a payload and sends it to the xMatters inbound integration URL configured in the webhook. 

The integration includes the following inbound integrations: 

  • Issue - Notify Group handles unassigned issues by notifying a recipient (typically, a group) defined in the communication plan's form.

    Group members can respond with "Assign to me", which uses their xMatters username to set them as the Assignee for the issue, and prevent the integration from creating further notifications when the issue is updated.

    Recipients can also choose to respond with "Escalate", which immediately notifies the next user in the escalation.

  • Issue - Notify Assignee creates a targeted event to notify the user if the issue has an Assignee, and the Assignee's username exists in xMatters. Otherwise, xMatters creates an FYI event to notify a recipient configured in the JIRA Issue - Notify Assignee form.

    Recipients can respond with "Accept" which assigns the event to them and prevent the integration from creating further notifications when the issue is updated in JIRA. 

In either case, any current active events for this issue ID addressed to other recipients are terminated.

NOTE: By default, only response callback is active; it authenticates with the xMatters user set up in JIRA (see details below). 

Download the integration package

To begin, download the communication plan attached to this article; it contains everything needed for this integration. 

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 and target other users for notification, 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

Note: When creating the REST API role for this integration, ensure that it has the "View Person" permission selected for any xMatters roles that may be targeted for notification by this integration. For example, under Permissions On Other Roles, select the View Person check box for Full Access User, Support User, and Standard User.

In the following examples,  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.
  4. Assign the user to the REST Web Service User role.
  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 that will receive notifications

The integration will notify the group or the user defined as a recipient in the communication plan's JIRA Issue - Notify Group form for issues that are not assigned to any user.

If an Assignee is designated for the issue, the Assignee will be notified. In this case, the user names in xMatters are expected to match the user names in JIRA.

If the Assignee's user name is not found in xMatters, the recipient defined in the JIRA Issue - Notify Assignee form will be notified.

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 communication plan (.zip file).
  3. Click Import Plan.
  4. Once the communication plan has been imported, click Plan Disabled to enable the plan.
  5. In the Edit drop-down list, select Properties.
  6. For both the priority and status properties, click Edit Property, and make sure the contents of the Values text box for each property matches the values in your JIRA deployment.
  7. If your integration is going to be processing issues of types other than "Bug", add the names of those types to the Values text box of the issue_type property.
  8. Select Forms tab.
  9. For the JIRA Issue - Notify Assignee form, in the Not Deployed drop-down list, click Create Event Web Service.
  10. After you create the web service, the drop-down list label will change to Web Service Only.
  11. In the Web Service Only drop-down list, click Permissions.
  12. Enter the REST API user you created above, and then click Save Changes.
  13. Open Layout of the JIRA Issue - Notify Assignee form, specify a recipient (a user or a group) for events related to unassigned issues or if user does not exist in xMatters, and then click Save Changes.
  14. Repeat steps 9-13 for JIRA Issue - Notify Group form.

Configure endpoints

After you have imported the communication plan, you need to set the authentication for the xMatters and JIRA endpoints.

  1. On the communication plan, click the Integration Builder tab, and then click the Endpoints button to display the endpoints for the integration.
  2. Update the "xMatters" endpoint with the credentials for the REST API user.
  3. Update the "JIRA" endpoint to use Basic authentication, and enter the credentials for a JIRA user that will have permission to update tickets. 
    • For more information about this user, see the Add an xMatters user section, below.
    • Make sure the Preemptive check box is selected.

Accessing web service URLs

Each integration service has its own URL that you can use to target it from JIRA.

To get a web service URL for an integration service:

  1. On the Integration Builder tab, expand the list of inbound integrations.
  2. Click the gear icon beside the integration service you want to target, and then select Integration URL.

 You will need the URL for each integration service when configuring JIRA.

Configure JIRA

Now that you've configured xMatters to integrate with your system, it's time to configure JIRA to integrate with xMatters. The following sections require you to log into JIRA with an administrator account and access the System settings page.

Add an xMatters user

If you are not using an existing administrator account in JIRA, the first step is to create an xMatters user that will authenticate into JIRA to update the issues. 

To create a user in JIRA:

  1. In the Site Administration submenu, click User Management.
  2. Click Create user, and then type a email address and name 'xmatters' in the Email address and Username fields.
    • Note: The email address must not be currently in use and must be valid. A link for resetting the password will be sent to this address. 
  3. In the Full name field, type xMatters
Once the password has been set, make sure you update the Username and Password fields in the JIRA endpoint in the Integration Builder endpoints as explained above. 

Add WebHooks

JIRA uses webhooks to hold the rules for when to initiate the web service calls detailed in the parameters. These are logical conditions that will vary from help desk to help desk.

Use care when developing your webhooks to ensure the alerts are being fired at the relevant times.

The following examples illustrate the settings for some potential webhooks.

To configure a webhook, open the Administration menu (click the cog icon), and then click System. In the Advanced menu, click WebHooks, and then click Create WebHook.

WebHook #1

TitleNotify Assignee

Purpose: Injects event in xMatters for issues that have an assignee and meet all of the following criteria:

  • Type: Bug
  • Priority: High or Highest
  • Status: Open, Reopened, To Do, or Build Broken.

Note the "Create event" inbound integration URL.

WebHook #2

Title: Notify Group

Purpose: Injects event into xMatters for unassigned issues that meet all of the following conditions:

  • Type: Bug
  • Priority: High or Highest
  • Status: Open, Reopened, To Do, or Build Broken

Note the "Create event" inbound integration URL.


WebHook #3

TitleTerminate xMatters Events - Issue deleted 

Purpose: Terminates related xMatters events when issue is deleted.

Note the "Terminate event" inbound integration URL.


WebHook #4

Title: Terminate xMatters Events - Issue updated

Purpose: Terminates related xMatters events when issue's priority or status changes to specific configured values.

Note the "Terminate event" inbound integration URL.

Test the integration

To test the integration, create or update an issue that will satisfy the rules defined above. 


There are several places you can inspect when troubleshooting why an event doesn't seem to make it over to xMatters. 

Inbound to xMatters

The first place to look is the Integration Builder Activity Stream. While on the Integration Builder tab, expand the Inbound Integrations section, click the gear icon beside the intended integration service, and then click Activity Stream.

The Activity Stream contains the incoming (and for outbound integrations, the outgoing) request, any logging statements as well as the final event creation messages.  

Outbound from xMatters

For the two-way integration from xMatters to JIRA, the primary source of logging is the Integration Builder Activity Stream for that particular integration.

For example, if you are troubleshooting why a ticket was not assigned to a user after they replied with "Assign to me", check the Activity Steam for the Response Callback outbound integration.  

Download resources


Have more questions? Submit a request


Please sign in to leave a comment.
Powered by Zendesk