Scheduled JQL Actions — 使い方

このアプリでできること

保存した JQL を定時に実行し、ヒットした課題に対して処理を行います。担当者をメンションしたコメントの投稿、優先度の設定、ラベルの追加と削除、遷移名を指定したステータスの変更ができます。

Jira Automation のルールを作ることも消費することもありません。Automation は実行回数がサイト全体の月間上限に数えられ、上限に達するとサイト上のすべての自動化が止まります。このアプリはその枠の外で動くので、Automation の実行枠を本来必要な用途に残せます。

Jira の設定画面、アプリの一覧から「Scheduled JQL Actions」を開きます。サイト管理者だけが開けます。

ルールを作る

「Create rule」を選び、4つを決めます。

JQL

処理の対象になる課題を決める検索式です。Jira の課題検索で書けるものはそのまま使えます。保存時に Jira へ問い合わせて検証するので、構文が誤った式は保存できません。

スケジュール

毎日、平日のみ、または指定した曜日から選びます。

時刻（UTC）

実行する時刻を UTC で指定します。選択中はローカル時刻での相当時刻が併記されるので、自分で換算する必要はありません。指定した「時」のどこかで動きますが、分単位の時刻は保証されません。

アクション

コメント、フィールド更新、ステータス遷移のいずれかです。次の章で説明します。

保存したルールは有効な状態で始まります。削除せずに止めたいときは「Disable」、再開は「Enable」です。ルールは50件まで保存できます。

3つのアクション

1つのルールにつき1つのアクションが、ヒットしたすべての課題に対して実行されます。

コメント

担当者をメンションしたコメントを投稿します。担当者には Jira が通常のメンションで送るのと同じ通知が届くので、受信側のメール設定を変える必要はありません。担当者が未設定の課題には、メンションなしでコメントが付きます。

フィールド更新

優先度の設定、ラベルの追加、ラベルの削除ができます。

ステータス遷移

ワークフローの ID ではなく遷移名で指定するので、ワークフローが異なる複数のプロジェクトに対して同じルールを使えます。

遷移名は大文字と小文字を無視した完全一致で判定します。Jira は遷移名を閲覧者の表示言語に翻訳して見せますが、アプリはワークフローに定義された名前を読みます。遷移のルールを保存すると、JQL がヒットする先頭の課題に対して名前を照合し、実際に存在する候補を並べて表示するので、食い違いはルールが動く前に分かります。

動かす前に試す

ドライランは、何件の課題が対象になるかを、実際には手を触れずに確認します。権限の検証を含めて本番と同じ経路を通るので、表示された結果がそのまま本番の結果になります。実行ログにもドライランとして記録が残ります。

「Run now」はスケジュールを待たずにその場で実行します。ドライランの結果を確認してから使ってください。どちらもルール一覧から実行できます。

事故を防ぐ仕組み

1回の実行でできることを、4つの仕組みが制限しています。

クールダウン

同じ課題に対して再び処理するまでの最短間隔を、最大14日まで指定できます。毎回処理してほしいときは 0 にします。

1回あたり100件の上限

1回の実行で処理するのは最大100件です。それを超えてヒットした場合は上限に達したことがログに記録されます。JQL の書き間違いで一度に大量の通知が飛ぶことはありません。

ルール作成者の権限

課題を処理する前に、そのルールを作った管理者の権限を確認します。その人自身がコメントできない課題は処理せずに飛ばします。作成者が見られない課題にルール経由で手を出すことはできません。

自動停止

3回続けて失敗したルールは自動的に無効化され、一覧に表示されます。壊れたルールが黙って失敗し続けることはありません。

実行ログを読む

「Execution log」タブに、実行の記録が新しい順に並びます。ヒット件数、処理した件数、失敗した件数、飛ばした件数が分かります。各行の「Details」で詳細を開けます。

課題を飛ばしたときは、どの課題をなぜ飛ばしたかがログに残ります。理由は、クールダウンが明けていない、Jira Service Management の課題である、ルール作成者に権限がない、その課題に指定の遷移名が存在しない、などです。

実行ログは90日間保持され、その後は自動的に削除されます。

できないこと

Jira Service Management には対応していません

サービスリクエストへのコメントは、申請した顧客から見える場合があります。社内向けのつもりの文面を顧客に送ってしまう事故を避けるため、実行時にサービス管理の課題を判定して処理せず、理由をログに残します。

スケジュールは時間単位まで

プラットフォームが分単位や cron 形式のスケジュールを提供していないため、このアプリも対応しません。指定した「時」のどこかで実行されます。

Slack・Teams・独自メールへの通知はありません

通知は Jira のメンションを通じて行われます。Atlassian のインフラ外への通信は一切行わず、第三者のサービスも使いません。

表示は英語のみ

管理画面も、アプリが投稿するコメントも英語です。

思ったとおりに動かないとき

ログに no transition named "..." と出る

ルールに書いた遷移名が、その課題で利用できる遷移のどれとも一致していません。ルールを保存したときに表示される警告に、実際に存在する候補が並びます。Jira の画面では遷移名が表示言語に翻訳されている一方、ワークフロー上の名前は別である場合があることに注意してください。

ルールは動いたのに何も変わらない

実行ログで該当の実行を開き、スキップの理由を確認してください。多いのは、クールダウンが明けていない、Jira Service Management の課題である、作成者にその課題への権限がない、の3つです。

勝手に無効化されている

3回続けて失敗したため自動的に停止しています。ログに出ている原因を直してから、あらためて有効化してください。

上限に達したと表示される

JQL が100件を超えてヒットし、先頭の100件だけを処理しました。条件を絞り込むか、複数回の実行で消化させてください。

問い合わせ

ルール名と、分かれば実行ログの Run ID を添えてご連絡ください。サポートは開発者本人が対応し、2営業日以内の返信を目標にしています。