Checkmk
to checkmk.com

If you use the Jira software for project management, software development or for tracking bugs, with the commercial editions you can send notifications from Checkmk to Jira and create or update Issues there. This works for the products Jira Work Management (formerly Jira Core), Jira Software and Jira Service Management (formerly Jira Service Desk).

The following options are supported:

  • Create issues for host and service problems.

  • Create issues with a defined Priority.

  • Create issues with a defined Label.

  • Set links to host/services in Checkmk from the generated Jira issues.

  • Set a Resolution in the issue when OK conditions occur.

To set up the connection between Checkmk and Jira, first create some new fields in Jira and define some Jira-IDs.

Next configure the notification method for Jira in Checkmk, entering the Jira IDs that have been created and read. You will gain more flexibility if you also use custom user attributes. Instead of entering the Jira IDs directly in the notification method, you can define some Jira IDs as custom user attributes. This makes it easy for individual users to create issues in a variety of JIRA projects.

Important

This is a machine translation based on the English version of the article. It might or might not have already been subject to text preparation. If you find errors, please file a GitHub issue that states the paragraph that has to be improved.

プロジェクト管理、ソフトウェア開発、バグの追跡に Jira ソフトウェアを使用している場合、 商業版 を使用すると、Checkmk から Jira に通知を送信し、そこで課題を作成または更新することができます。 これは、Jira Work Management(旧 Jira Core)、Jira Software、Jira Service Management(旧 Jira Service Desk)の各製品で機能します。

以下のオプションがサポートされています:

  • ホストおよびサービスの問題に関する課題を作成します。

  • 定義された優先度でイシューを作成します。

  • 定義済みのラベルを使用して問題を作成します。

  • 生成された Jira 課題から Checkmk のホスト/サービスへのリンクを設定します。

  • OK の条件が発生した場合に、問題の解像度を設定します。

Checkmk と Jira の接続を設定するには、まず Jira に新しいフィールドを作成し、Jira ID を定義します。

次に、Checkmk で Jira の通知方法を設定し、作成して読み込んだ Jira ID を入力します。 カスタムユーザー属性も使用すると、さらに柔軟性が高まります。 通知方法に Jira ID を直接入力する代わりに、Jira ID をカスタムユーザー属性として定義することができます。 これにより、個々のユーザーがさまざまな JIRA プロジェクトで簡単に課題を作成できるようになります。

1. Jira の設定

Jira と連携する場合、Checkmk は、どの通知がすでに問題を作成済みで、どの通知がまだ作成されていないかを把握する必要があります。 これを可能にするには、Jira に 2つのいわゆるカスタムフィールドを作成する必要があります。1 つはホストの問題に関する通知用、もう 1 つはサービスに関する問題用です。

ホストの問題とサービスの問題を正しく識別するには、これらの問題の ID が一意である必要があります。 Jira インスタンスが1 つのCheckmk サイトからの通知のみを受信する場合、Checkmk サイトの監視コアが一意性を確保するため、この条件は満たされます。 分散監視では、分散通知が設定されている場合、複数の Checkmk サイトから通知が送信される場合があります。 Jira インスタンスが複数の Checkmk サイトから通知を受信する場合、遅くともホストの問題の ID が別の Checkmk サイトによってすでに使用されている時点で、一意性は失われる可能性が高くなります。 このような構成では、一意の割り当てを再び可能にする、Checkmk サイト用の別のカスタムフィールドが必要になります。

Checkmk で設定するには、作成したカスタムフィールドの Jira ID と、さらにいくつかのフィールドの Jira ID が必要です。したがって、合計で以下の情報が必要になります。

  • プロジェクト ID

  • イシュータイプID

  • 優先度ID(オプション)

  • ホストカスタムフィールド ID

  • サービスカスタムフィールド ID

  • サイトカスタムフィールド ID (オプション)

  • (ワークフロー) 移行 ID (オプション)

これらの ID の大部分は、Jira の REST API を使用して、以下のスクリプトで読み込むことができます。 Jira 管理者は、Jira の GUI を使用して、API およびスクリプトでは取得できない ID も取得することができます。

1.1. Jira でカスタムフィールドを設定する

Jira でカスタムフィールドを作成する方法については、Jira のドキュメントをご確認ください。 これには、Jiraいわゆるイシュー画面へのフィールドの割り当ても含まれます。

Checkmk に必要なフィールドを作成する際には、フィールドのタイプに関して以下の点に注意してください。 フィールドの名前は自由に指定できます。 ただし、次の表に示すフィールド名は、次のセクション「外部スクリプトを使用して Jira ID を決定する」Jira ID を読み込むスクリプトと一致しています。

カスタムフィールド フィールドタイプ 名前

ホストカスタムフィールド

Number field

CMK_HOST_FIELD (例)

サービスカスタムフィールド

Number field

CMK_SVC_FIELD (例)

サイトカスタムフィールド (オプション)

Text field (single line)

CMK_SITE_FIELD (例)

また、Checkmk が問題を作成するために使用する Jira ユーザー、つまりCheckmk 通知ルールに入力されているユーザーが、これらのカスタムフィールドの読み取りおよび書き込みアクセス権を持っていることを確認してください。

1.2. 外部スクリプトを使用して Jira ID を決定する

Jira REST API を使用する次のスクリプトを使用して、ID をまとめて照会することができます。

JIRA_USERNAMEJIRA_PASSWORDPROJECT_KEYhttps://jira.server.your-domain.de を、それぞれ該当する値に置き換えてください。PROJECT_KEY は、管理者権限がなくても Jira GUI から確認できます。

Important

Jira Cloud 製品を使用している場合、スクリプトはパスワードではなく API トークンで認証されます。 API トークンの作成に関する背景情報と手順は、Jira のドキュメントをご覧ください Jira では、生成された API トークンをクリップボードにコピーし、JIRA_PASSWORD として次のスクリプトに貼り付けることができます。

example_script.py
#!/usr/bin/env python3

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

user = "JIRA_USERNAME"
password = "JIRA_PASSWORD"
project_key = "PROJECT_KEY"
jira_instance = "https://jira.server.your-domain.de"
custom_field_1 = "CMK_HOST_FIELD"
custom_field_2 = "CMK_SVC_FIELD"
custom_field_3 = "CMK_SITE_FIELD" # don't edit if field is not used

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_key)
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":
        infotext = ""
        for project in json_response:
            if project["key"] == project_key:
                infotext += "%s\n\n" % project.get("id", "Project ID not found")
        if not infotext:
            infotext += "Project ID not found, project name existing?\n\n"
    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() or \
                    line["name"].lower() == custom_field_3.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)

スクリプトの出力は、次のようなものになります。

=== IDs for project MY_PROJECT ===
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: 11400
CMK_SVC_FIELD: 11401
CMK_SITE_FIELD: 11403

1.3. GUI を使用して Jira ID を決定する

スクリプトを実行する代わりに、Jira GUI から ID を読み出すこともできますが、そのためには管理者アカウントで Jira にログインする必要があります。 Jira の製造元である Atlassian は、この手順をプロジェクト ID を例にして、自社の説明書に記載しています

他のフィールドおよび課題のタイプの ID は、Jira 管理者 GUI でそれぞれのエレメントを編集することで読み出すことができます。 ID は通常、ブラウザのアドレスバーに表示される最後の値です。

2. Checkmk の設定

通知に関する記事で、Checkmk 通知の一般的な設定方法についてはすでに説明しました。

Jira 通知を使用するには、Checkmk で以下の手順に従ってください。

  1. カスタムユーザー属性を使用する場合は、次の Jira ID に対して作成することができます。 プロジェクト ID (jiraproject)、課題タイプ ID (jiraissuetype)、優先度 ID (jirapriority)、および遷移 ID (jiraresolution)。 属性のName として入力した名前は、括弧で囲んで表示されます。Setup > Users > Custom user attributes > Add attribute でユーザーカスタム属性を作成します。

    A custom attribute for the Jira Project ID.

    Jira 用に作成したこれらのカスタムユーザー属性すべてについて、[Make this variable available in notifications ] チェックボックスがオンになっていることを確認してください。
    ユーザーのプロパティで、このユーザーが担当する Jira ID をこれらの属性に入力できます。
    各カスタムユーザー属性について、次の手順で作成する通知ルールでは、関連付けられている Jira ID のフィールドを空のままにしておきます。 これらのフィールドには、カスタムユーザー属性が入力されます。

  2. Jira用の新しいパラメーターを作成するには、Setup > Events > Notifications > Parameters for notification methods > Parameters for Jira > Add parameter.

    The notification method settings for Jira.
  3. JIRA URL フィールドに、Jira インスタンスの URL を入力します (例:jira.server.your-domain.com)。

  4. Authentication エリアには、アクセス用の Jira アカウントのアクセスデータ(Jira Cloud 製品の場合は名前/パスワードまたはトークン)を保存します。

  5. Project ID およびIssue type ID には、Jira で事前に識別した ID が必要です。この例では、プロジェクト ID は「10401」、課題タイプ「バグ」は「10006」です。

  6. Host custom field IDService custom field ID 、および(オプションで)Site custom field ID には、Jira で作成したカスタムフィールドの ID を入力します。

  7. 生成された問題から Checkmk に直接リンクできるようにするには、Monitoring URL に Checkmk サイトの URL を入力します。例:https://mycmkserver/mysite

その他のオプション設定として、以下の設定が可能です:

  • Priority ID で、Jira で問題を作成する優先度を定義できます。ここでは、スクリプトで読み込まれる「優先度タイプ」のうち、「1」から「5」までのいずれかを入力できます。

  • Summary for host notifications およびSummary for service notifications オプションを使用して、問題でホストおよびサービスの問題に対して作成される説明を変更できます。

  • Label オプションを使用して、Jira で問題を作成する際にラベルを渡すかどうかを定義できます。値を入力せずに Label を有効にすると、monitoring が設定されます。
    Checkmk は、ラベルの値を Jira の「labels 」フィールドに書き込みます。これは、Jira アプリケーションにこのフィールドが存在する場合にのみ機能します。Jira Software ではこのフィールドが存在しますが、Jira Service Deskでは存在しません。

  • Attach graphs 現在のステータスに関連するグラフを新しい課題に追加します。

  • Checkmk でOK にステータス変更を通知する際に、Jira の課題にもResolution を入力したい場合は、Activate resolution with following resolution transition ID で定義することができます。
    ここで正しい ID を決定するには、Jira の管理者権限も必要です。Issues エリアに戻り、Workflows をクリックします。次に、使用している Jira プロジェクトの標準ワークフローの行にあるView をクリックします。フローチャートが表示されたら、Text をクリックして表示を変更します。Transitions (id) 列に、目的の ID が表示されます。

  • Set optional timeout for connections to JIRA で、Jira への接続のタイムアウトを設定できます。ここに何も入力しない場合、デフォルト値の 10 秒が適用されます。

次の [Contact selection ] ボックスを使用する場合は、次の点に注意してください。

  1. 連絡先を選択する場合は、通知が1 つの連絡先のみに送信されるようにしてください。たとえば、1 人のユーザーを選択してください。 チケットシステムなどの通知方法では、連絡先の選択は通知の送信先を指定するだけです。 ただし、通知は選択したユーザーには送信されず、チケットシステムに送信されます。 連絡先グループ、オブジェクトのすべての連絡先などによる連絡先選択では、通常、1 つのイベントに対して複数の同一の通知が生成され、チケットシステムに 2 回、3 回、あるいはそれ以上送信されることにご注意ください。

  2. 最初の条件が満たされているにもかかわらず、同じ方法に対して複数の通知ルールでユーザーが使用されている場合、その場合はそれぞれ最後のルールのみが適用されます。 したがって、これらの通知ルールごとに個別の機能ユーザーを作成することをお勧めします。

  3. カスタムユーザー属性を使用する場合、連絡先選択のトピックは多少異なります。これは、異なるユーザーに異なる Jira ID を割り当てることを目的としているためです。 したがって、この場合、通常は、カスタム属性を割り当てたユーザー、つまり複数の連絡先に通知することをお勧めします。 これらのユーザーが異なる Jira ID を使用している場合、同一の通知は生成されません。

新しい通知方法をテストする方法については、通知ルールに関する記事をご覧ください。

3. 診断オプション

Checkmk で通知ルールを設定しても Jira にチケットが届かない場合は、関連するログファイル~/var/log/notify.log を確認してください。 Jira は通常、このファイルに非常に有用なエラーメッセージを表示します。このメッセージは、問題の診断に役立ちます。 以下に、その例をいくつかリストします。

エラーメッセージ:問題を作成できません、JIRA 応答コード 400、フィールド「ラベル」を設定できません。

Jira 製品にラベルがない可能性があります。 Checkmk の通知ルールで、Label のチェックボックスをオフにして、ラベルの使用を無効にしてください。

エラーメッセージ:課題を作成できません、JIRA 応答コード 400、b’project is required'。

このエラーメッセージは、問題のフィールド(ここでは「プロジェクト ID」)の通知ルールで入力した ID が間違っていることを示しています。

エラーメッセージ:https://jira.server.your-domain.de/browse/ISSUE-123 を解決できません、JIRA 応答コード 500、b’Internal server error'。

Jira のチケットが Checkmk によって自動的にクローズされる、あるいは別のステータスに変更されるはずなのにこのエラーメッセージが表示される場合は、入力した移行 IDが間違っている可能性があります。 移行 ID は、Activate resolution with following resolution transition ID フィールドの通知ルールに記載されています。 原則として、この ID を Jira の web インターフェイスで再度確認してください。

このページでは