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.