CLI から JSM のキューと SLA をレポートする

atlassian-cli はコミュニティによる独立したオープンソースプロジェクトです。Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援のいずれも受けておらず、Atlassian が提供する公式 CLI（acli）でもありません。製品名は互換性を示す目的でのみ使用しています。

CLI から JSM をレポートする理由

コマンドラインからの JSM の SLA レポートとは、Jira Service Management の UI をクリックして回る代わりに、いくつかの atlassian-cli コマンドでキューの中身と SLA タイマーを取得し、jq でレポートの形に整えることです。「未解決のリクエストのうち、解決までの時間をまもなく超過しそうなものはどれか」といった問いに、ダッシュボードを作ることも有料のレポートアドオンを買うこともなく答えられる、いちばん速い方法です。

JSM に組み込まれたレポートはざっと眺めるには十分ですが、絞り込みが遅く、定期実行しにくく、差分を取ることもできません。毎朝同じ違反レポートが必要なときや、SLA のデータをスプレッドシート、Slack への投稿、CI のゲートに流し込みたいときは、スクリプト化できるパイプラインに軍配が上がります。CLI は Jira Service Management Cloud REST API が返すのと同じデータを扱えるため、Atlassian が追跡している情報（キューへの所属、SLA のサイクル、残り時間、違反フラグ）はすべて JSON として取得でき、好きなように切り分けられます。

このツールの位置づけについて。 atlassian-cli はコミュニティによる独立したオープンソースプロジェクトです。Atlassian が提供する公式 CLI（acli）ではなく、Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援、保守のいずれも受けていません。ベンダーによる一次サポートが必要な場合は公式の acli を使ってください。Jira、Confluence、Bitbucket、JSM をカバーし、パイプライン向けの JSON 出力を備えた 1 つの無料バイナリが欲しい場合は atlassian-cli を使ってください。違いについては後半で詳しく説明します。

サービスデスク ID とキュー ID を調べる

JSM のレポート系コマンドはすべて、2 つの数値 ID を起点にします。サービスデスク ID と、キューを扱う場合のキュー ID です。これらはポータルに表示されるプロジェクトキーとは別物なので、まず一覧して確認します。

# List all service desks you can access
atlassian-cli jsm service-desk list --limit 25

# Inspect one service desk (here, ID 10)
atlassian-cli jsm service-desk get 10

サービスデスク ID が分かったら、そのキューを一覧します。キューは、エージェントが作業の起点にする保存済みの JQL ビューです（たとえば「未割り当て」「サポート待ち」「まもなく違反」など）。

# List the queues in service desk 10
atlassian-cli jsm queue list 10

# Get one queue's definition, including its issue count
atlassian-cli jsm queue get 10 5

queue get の出力にはキュー名と現在の件数が含まれており、これだけでも有用な概況指標になります。実際のリクエストを取得するには queue issues に進みます。

キューの中身を取得する

jsm queue issues コマンドは、キューに入っているリクエストを返します。2 つの位置引数は、順にサービスデスク ID とキュー ID です。

# First 25 issues in queue 5 of service desk 10
atlassian-cli jsm queue issues 10 5 --limit 25

# Same, as CSV, written to a file for a spreadsheet
atlassian-cli jsm queue issues 10 5 --format csv > queue.csv

# As JSON, piped into jq to grab key, summary, and status
atlassian-cli jsm queue issues 10 5 --format json \
  | jq '.[] | {key: .key, summary: .fields.summary, status: .fields.status.name}'

キューは JQL ビューにすぎないため、サポートチームの「いま未解決のものは何か」をスナップショットする方法としてはこれが最もきれいです。週次の関係者向け報告には CSV でエクスポートし、次のステップで SLA データと突き合わせたい場合は JSON のまま保持してください。--limit フラグはページサイズを制御します。ページネーションは CLI が行うため、値を上げると結果が切り詰められるのではなく 1 回の呼び出しで取得する件数が増えます。

覚えておくと便利な点が 1 つあります。グローバルな --envelope フラグを付けると、一覧の出力が {"data": [...], "count": N} の形で包まれます。スクリプトが合計件数を必要とするとき、jq length をもう一度通さずに済むため、後続の処理が書きやすくなります。

リクエストごとの SLA データを取得する

キューは何が未解決かを教えてくれます。SLA は何が遅れているかを教えてくれます。JSM では、各リクエストが 1 つ以上の SLA 指標（よく使われるのは「初回応答までの時間」と「解決までの時間」）を持ち、指標ごとに進行中のサイクルがあって、残り時間と違反フラグを備えています。CLI はこれをリクエスト単位で取得できます。

# All SLA metrics on a single request
atlassian-cli jsm sla list SD-123

# One specific metric by its SLA ID
atlassian-cli jsm sla get SD-123 --sla-id time-to-resolution

# SLA metrics as JSON for filtering
atlassian-cli jsm sla list SD-123 --format json

--format json を指定すると、出力は Jira Service Management Cloud REST API と同じ形になります。各指標のオブジェクトは、breached という真偽値と remainingTime オブジェクト（ミリ秒の値と読みやすい文字列の両方を持ちます）を含む ongoingCycle を持ち、すでに完了した指標には completedCycles が付きます。フィールド名は Atlassian の API ドキュメントと一致するため、ここで書く jq の式はそのまま流用でき、検証も簡単です。

1 件のリクエストについて、違反した指標だけを取り出すには次のようにします。

atlassian-cli jsm sla list SD-123 --format json \
  | jq '.[] | select(.ongoingCycle.breached == true) | .name'

jq で SLA 違反レポートを作る

ここで両者を組み合わせます。手順はこうです。キューのキーを一覧し、ループで回し、それぞれに jsm sla list を実行して、違反した（またはまもなく違反しそうな）指標だけを残します。結果は「どのリクエストが、どのタイマーで遅れているか」を示すコンパクトなレポートになります。

#!/bin/bash
# breach-report.sh -- flag breached SLAs in a JSM queue
set -euo pipefail

SERVICE_DESK="10"
QUEUE="5"
PROFILE="prod"

# 1. Collect the request keys currently in the queue
keys=$(atlassian-cli jsm queue issues "$SERVICE_DESK" "$QUEUE" \
  --profile "$PROFILE" --format json --limit 100 \
  | jq -r '.[].key')

# 2. For each key, print any breached SLA metric
for key in $keys; do
  atlassian-cli jsm sla list "$key" --profile "$PROFILE" --format json \
    | jq -r --arg k "$key" \
      '.[] | select(.ongoingCycle.breached == true)
        | "\($k)\t\(.name)\tBREACHED"'
done

違反した指標ごとに、タブ区切りの行が 1 行ずつ出力されます（例: SD-118 Time to resolution BREACHED）。ファイルにリダイレクトしても、読みやすくするために column -t にパイプしても、ヘッダー行を付けて CSV として保存してもかまいません。まだ違反していないが際どいリクエストを拾いたい場合は、select を残り時間のしきい値に差し替えます。

# Flag metrics with under 60 minutes remaining (3,600,000 ms)
jq -r --arg k "$key" \
  '.[]
    | select(.ongoingCycle != null)
    | select(.ongoingCycle.remainingTime.millis < 3600000)
    | "\($k)\t\(.name)\t\(.ongoingCycle.remainingTime.friendly) left"'

ターミナルから JSM の SLA レポートを作る意義はここにあります。絞り込みのロジックは、上司が少し違う質問をするたびに作り直す保存済みビューではなく、自分が所有するスクリプトの中にあります。数字を 1 つ変えれば、それだけで新しいレポートになります。

コマンド早見表

JSM のレポート系コマンドが何を返し、どの ID を必要とするかをまとめます。どのコマンドもグローバルな --format、--profile、--limit フラグを受け付けます。

キューにスコープを絞らないリクエストが必要な場合（たとえば、ある顧客が起票したものすべて）は、キューではなく jsm request list --servicedesk-id 10 を使ってください。こうしたワークフローはリクエスト管理ガイドで詳しく解説しています。

定期実行して Slack に投稿する

自分で思い出して実行しなければならないレポートは、いずれ忘れられます。違反レポートのスクリプトを cron に載せて、毎朝メールボックスやチャンネルに届くようにしましょう。プロファイルさえ設定してあればコマンド自体は対話を必要としないため、自動実行の環境でも処理が止まることはありません。

# crontab -e: run the breach report every weekday at 08:30
30 8 * * 1-5 /opt/reports/breach-report.sh > /opt/reports/out/breach-$(date +\%F).tsv 2>&1

結果を Slack に送るには、違反の行数を数え、報告すべき内容があるときだけ投稿します。

report=$(/opt/reports/breach-report.sh)
count=$(printf '%s\n' "$report" | grep -c BREACHED || true)

if [ "$count" -gt 0 ]; then
  curl -s -X POST "$SLACK_WEBHOOK" \
    -H 'Content-type: application/json' \
    -d "{\"text\": \"$count breached SLA(s) in the support queue this morning.\"}"
fi

これを実行するマシンには専用の認証プロファイルを用意し、個人のトークンではなくサービスアカウントを使うようにしてください。プロファイルの設定は認証ドキュメント、ここで触れたフラグの詳細はコマンドリファレンスをご覧ください。

acli との違い

Atlassian は acli という独自の公式コマンドラインツールを提供しています。ベンダー自身の選択肢であり、ベンダーサポートが付きます。atlassian-cli はそれとは別の、独立した MIT ライセンスのオープンソースプロジェクトです。Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援、保守のいずれも受けていません。2 つは同じバイナリではなく、設定を相互に流用することもできません。

必要なものに応じて選んでください。ベンダーによるサポートが欲しく、Atlassian 自身のツールの中で作業するのが心地よいなら acli を使ってください。Jira、Confluence、Bitbucket、JSM をカバーし、上のような jq やシェルのパイプライン向けに設計された一貫した --format json の出力を持つ無料バイナリを 1 つで済ませたいなら、atlassian-cli はまさにそのために作られています。Jira Service Management などの製品名は、互換性を示す目的でのみ記載しており、提携関係を示すものではありません。

よくある質問

関連リソース