Notifications via Jira

1. Introduction

If you use the Jira software for error tracking, problem tracking, or project management, from Version 1.6.0 of Checkmk Enterprise you can send notifications from Checkmk to Jira.

The following options are supported:

• Creation of Issues for host or service problems.
• Creation of issues with a defined Priority
• Creation of issues with a defined label
• Link to hosts/services in Checkmk from the generated Jira issues
• Set a Resolution in the issue on entering OK states

2. Configuration

To set up the connection of Checkmk to Jira, you first have to create two new Fields in Jira and determine certain Jira IDs. In addition the alerting program must be set up in Checkmk.

2.1. Setting up the user-defined fields in Jira

When interacting with Jira Checkmk must know which alerts have already generated an issue, and which have not. To make this possible you have to create two so-called Custom fields in Jira – i.e. user-defined fields.

To do this, as the administration user open the Administration item in the header bar in Jira.

Next select Issues, and in the Fields section navigate to Custom Fields. Add Custom Field allows you to create a new, user-defined field.

In the next window please select All, so that all field types become visible.

Find the Text Field (single line) option, and press the Next button.

In the Name section enter the desired name – in our example CMK_HOST_FIELD. You can optionally fill-out the Description with a description of the custom field.

Since we also need such a field for service notifications, please repeat the procedure with a corresponding entry for services, e.g. with the field name CMK_SVC_FIELD.

In order for CMK to create issues in Jira, you need the following Jira IDs:

• Project ID
• Issuetype ID
• Priority ID
• Custom Host Field ID
• Custom Service Field ID

There are two ways to find these IDs.

Identify IDs via the Jira GUI (requires administrator account in Jira)

Atlassian, the creater of Jira, provides its own procedure for this here: Instructions.

Determining IDs via an external script

You can also query collected IDs with a script:

#!/usr/bin/env python

import requests
import sys
import urllib3
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)

user = "JIRA_USERNAME"
password = "JIRA_PASSWORD"
project_name = "PROJECT_NAME"
jira_instance = "https://jira.server.your-domain.de"
custom_field_1 = "CMK_HOST_FIELD"
custom_field_2 = "CMK_SVC_FIELD"

def handle_response(user, password, jira_instance, what):
    url = "%s/rest/api/2/%s" % (jira_instance, what)
    sess = requests.Session()
    sess.auth = (user, password)
    response = sess.get(url, verify=False)

    return response

sys.stdout.write("=== IDs for project %s ===\n" % project_name)
infotext = ""
for section, id_name in [ ("Project_ID", "project"),
                          ("Issue", "issuetype"),
                          ("Priority", "priority"),
                          ("Field", "field"),
                        ]:

    json_response = handle_response(user,password,jira_instance,id_name).json()
    if id_name == "project":
        try:
            infotext += "Project ID: %s\n\n" % (section, [
                 item["id"]
                 for item in json_response if item["key"] == project_name
                ][0])
        except IndexError as e:
            sys.stderr.write(
                "Error getting Project ID: %s, Project name existing?\n" % e)

    else:
        types = ""
        for line in json_response:
            if id_name == "field":
                if line["name"].lower() == custom_field_1.lower() or \
                    line["name"].lower() == custom_field_2.lower():
                    types += "%s: %s\n" % (line["name"], line["id"].split("_")[1])
            else:
                types += "%s: %s\n" % (line["name"], line["id"])

        infotext += "=== %s types\n%s\n" % (section, types)

sys.stdout.write(infotext)

The output from the script looks like this:

=== IDs for project MY_PROJECT ===
Project ID: 10401

=== Issue types
Test case: 10600
Epic: 10000
Task: 10003
Sub-task: 10004
Bug: 10006
Story: 10001
Feedback: 10200
New Feature: 10005
Support: 10500
Improvement: 10002

=== Priority types
Blocker: 1
High: 2
Medium: 3
Low: 4
Lowest: 5
Informational: 10000
Critical impact: 10101
Significant impact: 10102
Limited impact: 10103
Minimal impact: 10104

=== Field types
CMK_HOST_FIELD: 10325
CMK_SVC_FIELD: 10000

Further information on Jira can be found here.

2.2. Setting-up the notifications in Checkmk

You have already learned how to set up alerts in the article notifications. To use Jira notifications select the notification method Jira (Enterprise only).

In the Jira URL field enter the URL of your Jira instance, e.g. jira.server.your-domain.com. At User Name and Password enter the user and password for access.

Now you need the previously determined IDs in the fields Project ID and Issue type ID. Enter the IDs of the custom fields created in Jira under Host custom field ID and Service custom field ID.

In order to be able to link directly to Checkmk in the generated issues, enter the URL of your Checkmk instance under Monitoring URL – for example, https://cmkserver/site.

You can use the Priority ID option to define the priority with which the issues are created in Jira.

The description that is generated in the Issues for host and service problems can be changed using the Summary for host notifications and the Summary for service notifications options.

Optionally, you can check the Label box to define whether during the Jira issue generation you want to include Label with the transfer.

With ‘OK’ notifications, if you wish to have a Resolution entered into the Issue, you can define this resolution via Activate resolution with following resolution transition ID. Jira has the following options:

• 11 - 'To Do'
• 21 - 'In Progress'
• 31 - 'Done'

set optional timeout for connections to JIRA. You can use set optional timeout for connections to JIRA to configure the timeout for connections to Jira. If you do not define anything here a default timeout of 10 seconds will be assumed.