はじめに
最近JiraのJQLをよく使うためメモとして記します。
内容は別の媒体で書いたもののコピーです。
https://note.com/shift_tech/n/n3a1fcd7d0ce4
プロジェクト管理ツールは様々なツールがありますが、今やJiraはアジャイル開発において必要不可欠なツールになっていると思っております。 個人的にですが、アジャイル開発の案件ではほぼ使われているんじゃないかと思います。
今回は基礎的な部分も交えて、実際に実務で使えるシチュエーション別に紹介していきたいと思います。
こちらを見れば今日からすぐに実践で使えると思います。
想定読者
・Jiraの課題を自由自在に検索したい方
・普段ベーシック検索しか使わず、JQLでの検索に踏み込めない方
JQLとは
「Jira Query Language」の略で、Jiraで特定の課題を検索するための、強力で柔軟な方法です。
JIRA課題の検索は「ベーシック検索」と「JIRAクエリ言語（JQL）検索」の二種類があります。今回は後者の「JIRAクエリ言語（JQL）の紹介です。
参考までに、下記がJira上の「ベーシック検索」と「JIRAクエリ言語（JQL）検索」の実行画面です。
ベーシック検索では、基本的な項目(プロジェクト、チケットタイプ、担当者等)のほか、＋Moreで項目を追加したりして基本的な検索が可能です。
「Switch to JQL」のリンクを押下後にJQLの実行画面に切り替わります。
初期表示では「order by(表示順の指定)」しか表示されておりませんが、この後に紹介するコードを条件にいれていただければと思います。
ちなみにベーシック検索後にJQL検索に切り替えて編集もできますので、慣れないうちはオススメします。
詳細はATLASSIAN社の記事を見ていただければと思います。
はじめてのJQL 第1回：Jiraでの検索の概要とJQLの基礎
またこちらの資料には下記のように記載があります。
「Jira Query Language」の略で、Jiraで特定の課題を検索するための、強力で柔軟な方法です。
ACEリーダーの高橋さんによると「JQLを制するものがJiraを制す」と言われるほど、使いこなせると非常に便利な機能です。
国民的バスケ漫画の一言を彷彿とさせますね。
JQLのリファレンス ※ブクマ推奨
前提として、SQL同様にJQLもできることが多いため公式リファレンスが存在します。
私もできる、できないを調査する際にはこちらのサイトを確認しているためブックマーク推奨です。
基本的にはこちらのリファレンスを組み合わせることで幅広く検索が可能です。
ケース別のJQL紹介
1. 複数課題、担当者の指定したいケース
IN,NOTINを利用します。
シンプルにけっこう利用するケースがあるため紹介しておきます。
■例題1
担当者(assignee)がQiita1、Qiita2、Qiita3のいずれかがアサインされた課題を検索
assignee in (Qiita1,Qiita2,Qiita3)
■例題2
Sprint1～3に含まれないSprintの課題を検索
sprint not in ("Sprint 1","Sprint 2","Sprint 3")
2. 正確なワードが思いだせず、あいまい検索したいケース
検索したいフィールド名の後に” ~”を使い、検索したいワードをセットします。検索にはワイルドカード検索: ? および *が利用可能です。
■例題1
Summary (概要) に【Dev】【Stg】という語句の完全一致が含まれる検索
summary ~ "\"【Dev】【Stg】\""
■例題2
チケットのコメント、説明(Text)に【Dev】および【Stg】という単語が含まれる課題をすべて検索
text ~ "【Dev】【Stg】"
3. 未入力・設定を検索したいケース
EmptyまたはNullを利用します。
■例題
期限が設定されていないすべての課題を検索
→他にも担当者が設定されていない、不具合の原因が入力されていない等で利用できます。
duedate = empty
または
duedate is empty
4. 日付を条件にしたいケース
日付関係は多いですが、よく使うものだけ抜粋いたします。
■例題1
2022年1月25日より後に作成されたものを検索したい
→25日より前は「<」、25日のものは「=」で普通に検索できます。
created > "2022/1/25"
■例題2
5日以内に作られた課題を検索
created >= "-5d"
■例題3
1/25-1/27の間でチケットに更新があったものを検索
updated During(“2022/1/25”,”2022/1/27”)
■例題4
Due dateが過ぎているチケットを検索
duedate < now()
これ以外にも日付関係はstartOfDay()、endOfMonth()など開始・終了を日、週、月単位で指定が可能です。詳しくはリファレンスをご確認ください。
5. ステータスの変更を検知したいケース
CHANGEDを使います。ここではステータスとしていますが、担当者、修正バージョン、優先度等のフィールドでも利用可能です。
■例題1
担当者が変更されたチケットを検索
assignee CHANGED
■例題2
チケットのステータスが"In Progress" から "close"に変更されたチケットを検索
status CHANGED FROM "In Progress" TO "close"
さらに日付指定を追加することも可能
status CHANGED FROM "In Progress" TO "close" During(“2022/1/25”,”2022/1/27”)
6. 過去に〇〇さんが担当者だったチケットを探すケース
WAS IN ,WAS NOT INを使います。
※一部制約があるためこちら参照ください。
https://jira.atlassian.com/browse/JRASERVER-28091
■例題1
Qiita太郎さんが過去に担当者だったチケットを検索
assignee WAS ="Qiita太郎"
■例題2
Qiita太郎 または Qiita次郎が過去に解決したチケットを検索
→Byは初登場ですが「誰が」を指定する際に利用します。
status WAS "Resolved" BY (Qiita太郎,Qiita次郎)
7. 現在のスプリント、未来のスプリントの課題を検索
openSprints()、futureSprints()、closedSprints()を使います。
開始済みかつ未完了、完了済み、未実施のスプリントに割り当てられている課題を検索します。
■例題
完了済みのスプリントに割り当てられているすべての課題を検索:
sprint in closedSprints()
8.複数条件のJQL結果を統合したいケース
複数条件を返したい場合、こちらのように対象のJQLを()で括り、ORで繋ぐことで可能になります。
■例題
Qiita太郎が"Open"から"In Progress"にステータス変更、Qiita次郎が"In Progress"から"Closed"にステータス変更したチケットを検索
(status CHANGED FROM "Open" TO "In Progress" BY "Qiita太郎") OR (status CHANGED FROM "In Progress" TO "close" BY "Qiita次郎")
終わりに
ここまでいろいろと紹介させていただきましたが、正直ベーシック検索でも物足りますし、JQLはあくまで「目的」ではなく「手段」でしかないので状況に合った柔軟な使い方をしていただければと思います。