1. Home
  2. Integrations
  3. Jira Integration Guide – VictorOps

Jira Integration Guide – VictorOps

About Jira and VictorOps

The VictorOps and Jira integration helps with project and ticket tracking while centralizing incident information in VictorOps. Depending on how your organization is using Jira, an issue could represent a software bug, a project task, a helpdesk ticket, a leave request form, etc. The VictorOps and Jira integration works in two ways: 1) The Jira integration allows you to create a new Jira ticket for any incident that comes into VictorOps. 2) You can create VictorOps incidents whenever a new issue is added to a Jira ticket.

VictorOps and Jira: Flexible Project and Ticket Tracking for Software Teams

  • Create new Jira tickets for incidents that comes into VictorOps
    • Integrate Jira issues with every VictorOps incident by adding the Jira email address to the first step of that team’s escalation policy
  • Create VictorOps incidents whenever a new issue is added to your Jira project.
  • The VictorOps and Jira integration empowers continuous delivery and site reliability through detailed project tracking in both Jira and VictorOps

This integration provides a wide range of customizable configuration options, so there is not just one way to set this up. This guide aims to provide you with all the tools you will need to setup this integration to fit your workflows.

Jira Webhook Integration Guide

Getting Started

The first step is to copy your Service API Endpoint to the clipboard. Navigate to Settings >> Alert Behavior >> Integrations and scroll down to “Jira (webhook)”

copy your Service API Endpoint to the clipboard - 1

copy your Service API Endpoint to the clipboard - 2

 

Next, copy the Service API Endpoint and paste it to a temporary location for later usage. Replace the $routing_key with whichever routing key is desired, leaving it blank will route to the default routing key.

copy the Service API Endpoint and paste it to a temporary locationIn Jira (Webhook Integration)

From the main web interface, select the cog in the upper right hand corner and then System. 

select webhooks in Jira

In the left side bar under “Advanced” select WebHooks.

select webhooks in Jira - 2

Select + Create a Webhook. Give the WebHook a name set the status to Enabled and paste in the VictorOps JIRA URL.

Select + Create a Webhook - Jira VictorOps

You will then have the options to use specific JQL queries to send only certain issues.

Next select the events you would like to have a webhook sent to VictorOps for. In our example we have chosen to send a webhook whenever an “Issue” is created, updated or deleted.

select the events you would like to have a webhook sent to VictorOps for

Finally un-check the “Exclude body” check box so that JIRA sends JSON and then select Create.

Now when an issue is created, a CRITICAL incident will be created, any updates will be sent to the timeline as an alert associated to that incident including info messages when a comment is added. When the issue is resolved or deleted in JIRA, the incident will be resolved in VictorOps. That is the out of the box functionality. Any additional functionality you desire can be accomplished through the use of custom fields and the Transmogrifier.

In VictorOps (Webhook Integration)

Now that webhooks are being sent from JIRA, we have a number of options on how we can manipulate those into different types of alerts and update JIRA issues based on actions in VictorOps. We will start with a simple transmogrifier rule. For example you may want to adjust the severity level of an alert based on the priority that was set in JIRA or the jira.issue.fields.priority.name. Let’s say for all JIRA issues with a priority of Sev 4 you want to make those WARNING alerts in VictorOps. The transmogrifier rule would look like:

Jira Webhooks transmogrifier rule VictorOps

Next, to send information based on actions in VictorOps back into JIRA you will need to setup Outbound Webhooks that accomplish this. You can do things such as update the status of a ticket when the incident is acknowledged in VictorOps or add a comment to the ticket. The following example will walk you through how to add a comment to a JIRA ticket when someone writes in the associated incident timeline in VictorOps.

Select Settings then Webhooks then Add a webhook.

Set the “Event” to “Incident-Chats”
Set the “Method” to POST
Set the “Content Type” to application/json
Set the “To” to the JIRA rest endpoint for issue comments. You will need to pass through authentication and the Jira Issue Key or ID in the url. The URL should look like so:

https://username:password@sub_domain.atlassian.net/rest/api/2/issue/${{ALERT.jira.issue.key}}/comment

Set the “Payload” to include the chat text from the incident timeline. The payload should look like so:

{"body": "Via VictorOps Timeline: ${{CHAT.TEXT}}"}

The final result should like like so:

Set the "Payload" to include the chat text from the incident timeline.

Now every time a chat is entered into the timeline a comment will be added to the issue in JIRA.

Some important JIRA fields for both Transmogrifier and the Outbound Webhooks are:

jira.issue.fields.status.id
jira.issue.fields.status.name
jira.issue.fields.priority.id
jira.issue.fields.priority.name
jira.issue.id
jira.issue.key

For Additional information on JIRA’s API see the documentation here.

This is just one of many ways to set up this integration, if you are trying to setup a custom workflow and have any questions please contact support.

 

Jira Service Desk Integration

JIRA Software offers flexible issue and project tracking for software teams. VictorOps has two integrations with JIRA, one for each direction. The first will allow you to create a new JIRA ticket for any incident that comes into VictorOps. The second one below allows you to create VictorOps incidents whenever a new issue is added to your JIRA project.

VictorOps =>JIRA (Email Endpoint)

This integration requires that you setup JIRA email that creates and updates Issues. This is only available with JIRA Service Desk. For more information see the documentation HERE.

In Jira (Service Desk Integration)

The first step is to setup an “Incoming mail handler” for the project you want to receive issues from VictorOps. To do so select Settings (gear icon) and then System.

setup an Incoming mail handler - Jira VictorOps

In the left sidebar under “Mail” select Incoming Mail.

select Incoming Mail

Under “Mail Handlers” select Add Incoming mail handler.

add incoming mail handler - Jira VictorOps

Give it a name and select the appropriate handler you want to use for this integration (We suggest the “Create a new issue or add a comment to an existing issue” option), then hit Next.

Create a new issue or add a comment to an existing issue - Jira VictorOps

Select the Project you want to associate this integration with, in this example we selected the “VictorOps Critical Incidents” then select Add.

adding VictorOps Critical Incidents project - Jira

Next, retrieve the email address associated to the project. To do this go into your projects administration page and select Email requests. Copy the email you want to use to your clipboard.

projects administration page and select Email requests

In VictorOps (Service Desk Integration)

We will use the JIRA email address as part of a team’s escalation policy so that when an alert is routed to that team, a ticket is created. This gives you two options:

1) Create JIRA issues from specific VictorOps incidents by re-routing incidents to a “New JIRA Ticket” team that has a single escalation step to send an email to the JIRA email address.
2) Create JIRA issues from every VictorOps incident that goes to a team by adding the JIRA email address to the first step of that teams escalation policy.

The following will walk you through the first option.

In the VictorOps web portal select Settings then Schedules and then Add Team.

In VictorOps web portal select Settings then Schedules and then Add Team

Add your JIRA Email address to the first step of the escalation policy.

 

And that’s it! Now any time you want to create a JIRA issue from any VictorOps incident all you need to do is re-route that incident to the “New JIRA Ticket” team.

rerouting incident to new JIra team in VictorOps

 

VictorOps Jira integration success

If you have any questions please reach out to support.

VictorOps to Jira (Custom URL)

This integration method utilizes a custom URL and the VictorOps Transmogrifier to generate a JIRA ticket with information from the alert automatically added.

In VictorOps (Custom URL)

From the web portal select Settings -> Alert Behavior -> Transmogrifier.

selecting transmogrifier - VictorOps Jira

Add a new rule. Set it to match on the alerts you would want to create JIRA tickets from. In the below example we have set it to match on any alert containing a host_name.

Next add an Annotation and select the URL type. Give it a name and then build a custom create JIRA ticket using documentation from Atlassian here:

Altassian Documentation

You can use Variable Expansion within the transmogrifier to build the URL in a way that pulls in information for the ticket dynamically. Below is an example where we set the Description, Summary and Label fields.

https://YOUR_DOMAIN_HERE.atlassian.net/secure/CreateIssueDetails!init.jspa?pid=10506&issuetype=1&description=${{state_message}}&summary=${{entity_id}}&labels=${{labels}}

Now whenever the rule matches on an alert, you will have a one touch option to create a JIRA ticket that already has information pulled directly from the VictorOps alert.

Create Jira Ticket custom URL VictorOps

Create an Issue in Jira with custom url - VictorOps

And that’s it, if you have any questions please reach out to the VictorOps support team.

Updated on May 1, 2019

Was this article helpful?

Related Articles