今日分享

1. JQL 結構說明
2. JQL fields

跟各位不好意思，本來今天的文章是昨天要發布的，但因為昨天臨時多了一個實際動手改自動化設定的故事，我一時興趣插播在昨天，直到今天才補番 JQL 解析。

JQL 句型結構說明

JQL 通常用於進階式的搜尋，因此我們要先了解一個 JQL 組合元素。
我們以 project = "TEST" AND assignee = currentuser() 為例，這句話的意思是，需要進階搜尋出 project key 為 TEST 中，Assignee 是 當前使用者的 issues。以下是這句 JQL 的元素拆解。

在上述元素中，我們已經認識了兩個，分別為

1. operators：JQL 中的運算符是一個或多個符號或詞語，它比較左側字段的值與右側的一個或多個值（或函數），以使僅檢索到符合條件的結果。一些運算符可能使用 NOT 關鍵字。
   通過學習如何結構您的JQL查詢，可以更好地進行高級搜索。JQL中的簡單查詢（也稱為“子句”）由字段組成，後跟運算符，然後是一個或多個值或函數。詳情可見 Day25 - 解析 JQL 讓 Automation 更進階 - 今天來認識 JQL operators （運算符號）

2. Keywords：執行以下任一操作（或是以下操作的一部分）的重要單詞：

• 將兩個或多個子句連接在一起以形成復雜的JQL查詢。
• 更改一個或多個子句的邏輯。
• 更改運算子的邏輯。
• 在JQL查詢中具有明確的定義。
• 執行特定功能，以更改JQL查詢的結果。
  詳情可見 Day24- 解析 JQL 讓 Automation 更進階-認識 JQL Keywords後，設定開新版本後自動加入 IN PROGRESS 的票中

JQL fields

今天要談的是 JQL fields Ｏ(≧▽≦)Ｏ

fields，區域/地點/領域，我們在這裡先定義為區段 ，是表示 Jira 區段（或已在 Jira 中的自定義區段）的名詞。區段是用來指定你希望在 Jira 中搜索的數據元素關鍵。
以下就來說明常見的 Jira fields Type 和 fields，我也會列出 可用 operators、可用函數（明天會來聊 functions 函數）和用法例句，這樣相信會更清楚。

[USER] Field Type

• assignee：負責人，這是問題指定分配對象的區段，您可以使用此區段來查找分配給特定使用者的問題。
• 可用 operators：= , !=, IS, IS NOT, IN, NOT IN, WAS, WAS IN, WAS NOT, WAS NOT IN, CHANGED
• 可用函數：membersOf()，currentUser()
• 用法例句：要查找分配給 John Smith 的問題 assignee = "John Smith" or assignee = jsmith

[ATTACHMENT] Field Type

• Attachments：附件，搜尋具有附件或沒有附件的問題。
• 可用 operators：IS, IS NOT
• 用法例句：要查找帶有附件的問題 attachments IS NOT EMPTY

[CATEGORY] Field Type

• Category：分類，搜尋屬於特定類別專案的問題。
• 可用 operators：=, != , IS, IS NOT, IN, NOT IN
• 用法例句：要查找屬於 "Alphabet Projects" 類別的專案的問題 category = "Alphabet Projects"

[TEXT] Field Type

1. Comment：評論/回覆，使用 Jira 文字搜尋語法找包含特定文字的評論的問題。

• 可用 operators：~ , !~
• 用法例句：要查找包含詞語"My PC is quite old"的評論的問題 comment ~ "\"My PC is quite old"

2. Description：描述，用於搜索描述中包含特定文本的問題，使用Jira文本搜索語法。

• 可用 operators：~ , !~ , IS , IS NOT
• 用法例句：要查找 Description 描述中包含“Please see screenshot”的問題 description ~ "Please see screenshot"

3. summary：這是問題的摘要或標題字段，可以使用此區段來搜尋包含特定關鍵字的問題。

• 可用 operators：~ , !~ , IS , IS NOT
• 用法例句：查找摘要中包含 "Error saving file" 這些詞的問題 summary ~ "Error saving file"

4. Text:這是一個主要字段，允許您使用 Jira 文字搜索語法搜索問題的所有文句字段，例如：summary 摘要、Description 描述、Environment 環境、Comments 評論及使用“free text searcher”（自由文本搜索器）的自定義字段；這包括以下內置自定義字段類型的自定義字段：自由文本字段（無限文本）、文本字段（< 255個字符）、只讀文本字段
   可用 operators：~
   用法例句：尋找包含 "full screen" 這個詞語的所有問題 text ~ "full screen"

5. Change gating type:僅用於 Jira Service Management。搜索在變更請求中使用的變更閘控類型。"僅跟踪"請求由與變更管理流程分開運作的集成產生。這些工具不遵循批准或變更閘控策略。"僅跟踪"的變更請求僅用於紀錄目的。

• 可用 operators：= , != , IS, IS NOT, IN, NOT IN
• 用法例句：要查找"gating type" 沒有值的請求 change-gating-type is EMPTY

[COMPONENT] Field Type

• Component：元件，搜尋屬於專案特定元素的問題。您可以通過元件名稱或元件ID（即 Jira 自動分配給元件的號碼）進行搜索。
• 可用 operators：= , != , IS , IS NOT , IN , NOT IN
• 可用函數：componentsLeadByUser()
• 用途：搜索屬於專案特定元件的問題。
• 用法例句：要查找屬於"Comp1"或"Comp2"組件的問題 component in (Comp1, Comp2)

註：使用元件ID 進行搜索為佳，因為不同的專案可能具有相同名稱的元件。同時，您的 Jira Admins 有可能更改元件名稱，這可能會破壞依賴該名稱的任何已保存的篩選器。但是，元件ID是唯一且無法更改的。

[VIRSION] Field Type

1. Affected version：版本，比如搜尋分配給特定受影響版本的問題。您可以通過版本名稱或版本ID（即Jira自動分配給版本的號碼）進行搜尋。

• 可用 operators：= , != , > , >= , < , <= , IS, IS NOT, IN, NOT IN
• 可用函數：latestReleasedVersion()，earliestUnreleasedVersion()
• 用途：搜索分配給特定受影響版本的問題。
• 用法例句：要查找受影響版本（Affected Version）為 "3.14" 的問題 affectedVersion = "3.14"

2. Fix version：查找分配給特定修復版本的問題。您可以按版本名稱或版本 ID（即 Jira 自動分配給版本的編號）進行搜索。

• 可用 operators：= , != , > , >= , < , <= , IS , IS NOT, IN , NOT IN, WAS, WAS IN, WAS NOT, WAS NOT IN , CHANGED
• 可用函數：latestReleasedVersion()、earliestUnreleasedVersion()、releasedVersions()、unreleasedVersions()
• 用法例句：查找修復版本為 3.14 或 4.2 的問題 fixVersion in ("3.14", "4.2")

註：使用版本 ID 進行搜索為佳，因為不同的專案可能具有相同名稱的版本。同時，您的 Jira Admins 有可能更改版本名稱，這可能會破壞依賴該名稱的任何已保存的篩選器。但是，版本ID是唯一且無法更改的。

[DATE] Field Type

1. Due：到期日，用於搜索在特定日期（或日期範圍）到期的問題，由於到期日期僅關聯日期，不包括時間，您可以使用不同的日期格式進行搜索，或者使用“w”（周）或“d”（天）來指定相對於當前日期的日期。

• 可用 operators：=，!=，>，>=，<，<=，IS，IS NOT，IN，NOT IN。
• 支援的函數：currentLogin()、lastLogin()、now()、startOfDay()、startOfWeek()、startOfMonth()、startOfYear()、endOfDay()、endOfWeek()、endOfMonth()和endOfYear()。
• 用法例句：要查找所有截止日期在 2011 年 1 月的問題 due >= "2011/01/01" and due <= "2011/01/31"

2. Created：搜尋在特定日期（或日期範圍）創建的問題，或在特定日期之前或之後創建的問題。請注意，如果未指定時間組件，則將假設為午夜。請注意，搜索結果將相對於您配置的時區（默認為 Jira 服務器的時區）。
   您可以使用以下格式之一：
   "yyyy/MM/dd HH:mm"
   "yyyy-MM-dd HH:mm"
   "yyyy/MM/dd"
   "yyyy-MM-dd"
   或使用"w"（周）、"d"（天）、"h"（小時）或"m"（分鐘）來指定相對於當前時間的日期。默認為"m"（分鐘）。請務必使用引號（"）；如果省略引號，則所提供的數字將被解釋為自紀元（1970年1月1日）以來的毫秒數。

• 可用 operators：= , != , > , >= , < , <= IS , IS NOT , IN , NOT IN
• 可用函數：currentLogin()、lastLogin()、now()、startOfDay()、startOfWeek()、startOfMonth()、startOfYear()、endOfDay()、endOfWeek()、endOfMonth()、endOfYear()
• 用法例句：要查找在 2010 年 12 月 12 日下午 2:00 之前創建的所有問題 created > "2010/12/12" and created < "2010/12/12 14:00"

[ISSUE] Field Type

1. Issue key：搜尋具有特定的問題關鍵字或問題ID（即Jira自動分配給問題的編號）

• Supported operators：= , != , > , >= , < , <= , IN, NOT IN
• 可用函數：issueHistory()、linkedIssues()、votedIssues()、watchedIssues()
• 用法例句：要搜尋 issue key 為 "ABC-123"的問題 issueKey = ABC-123

2. Issue link：搜尋已連結或未連結到問題的問題。您可以限制搜尋到特定類型的連結。

• 可用 operators：= , != , IN , NOT IN
• 用法例句：要搜尋任何帶有ABC-123 issue link 的問題 issueLink = ABC-123

3. Parent：在公司管理的專案中，搜尋特定問題的所有 subtask 子任務或在團隊管理的專案中搜尋特定 Epic 史詩的所有 subtask 子任務。您可以按問題關鍵字或 Key ID（即Jira自動分配給問題的號碼）進行搜尋。

• 可用 operators:= , != , IN , NOT IN
• 用法例如：搜尋作為問題 TEST-1234 的子任務的問題 parent = TEST-1234

[LABEL] Field Type

• Labels：搜索已標記有標籤或標籤清單的問題。您還可以搜索沒有任何標籤的問題，以輕鬆識別哪些問題需要標記，以便它們出現在相應的迭代、隊列或報告中。
• 可用 operators:= , !=, IS, IS NOT, IN, NOT IN
• 用法例句：查找没有指定標籤的問題，包括没有標籤的問題 labels not in ("x") or labels is EMPTY

[PRIORITY] Field Type

• Priority：這是問題的優先順序區段。您可以使用它來查找具有特定優先次序的問題，例如高、中、低等。
• 可用 operators：= , != , > , >= , < , <= IS , IS NOT, IN , NOT IN , WAS, WAS IN, WAS NOT, WAS NOT IN , CHANGED
• 用法例句：找出 priority 是 Hign 的問題 priority = High

[PROJECT] Field Type

• Project：用於指定特定專案的區段，可以使用此區段來縮小搜索範圍，僅搜尋特定專案中的問題。
• Supported operators：= , != , IS , IS NOT, IN , NOT IN
• 可用函數：projectsLeadByUser()、projectsWhereUserHasPermission()、projectsWhereUserHasRole()
• 用法例句：搜尋屬於具有專案 Key 是 "ABC" 的問題 project = "ABC"

[STATUS] Field Type

• Status：此區段表示問題的當前狀態，如 TO DO 待處理、IN PROGRESS 進行中、DONE 已解決等。您可以使用此區段來查找處於特定狀態的問題。
• Supported operators:= , != , IS , IS NOT, IN , NOT IN , WAS, WAS IN, WAS NOT, WAS NOT IN , CHANGED
• 用法例句：搜尋目前具有或先前具有 "Open" 狀態的問題 status WAS Open

[USER] Field Type

1. Creator：創建者，用於搜尋由特定使用者創建的問題，您可以根據使用者全名、ID或 email 搜尋，不過問題的 Creator 不會更改，因此您無法搜尋過去的 Creator（例如WAS）。

• 可用 operators：=，!=，IS，IS NOT，IN，NOT IN。
• 可用函數：membersOf()、currentUser()。
• 用法例句：要查找由 Jill Jones 創建的問題 creator = "Jill Jones" or creator = "jjones"

2. Approvals：批准，僅用於 Jira Service Management，搜尋已獲批准或需要批准的請求。這可以進一步通過使用者進行精準搜尋。

• 可用 operators：=
• 用法例句：要查找需要或曾經需要當前使用者批准的請求 approval = myPending()

[Custom field] Field Type

• Custom field（自定義區段）：用於搜索具有特定值的特定自定義區段的問題。可以根據自定義區段名稱或自定義區段ID（即 Jira 自動分配給自定義字段的號碼）進行搜索。請注意，通過自定義字段ID進行搜索比通過自定義字段名稱更安全。自定義字段支持不同類型的操作符和函數，具體取決於自定義字段的配置。
• 用法例句：要查找“location”自定義區段值為“New York”的問題 location = "New York"

[Custom field] Field Type

• Customer Request Type（客戶請求類型）：僅適用於Jira Service Management，可以根據請求類型名稱或請求類型描述（根據請求類型配置屏幕中的配置）進行搜索。請注意，客戶請求類型的Lucene值是portal-key/request-type-key。儘管服務項目門戶創建後無法更改，但項目金鑰可以更改，而請求類型金鑰在創建後無法更改。
• 可用 operators：= , !=，IN , NOT IN
• 用法例句：要查找 Customer Request Type 顧客請求類型為“Request a new account”或“Get IT Help”的問題"Customer Request Type" IN ("Request a new account", "Get IT Help")

⋯⋯ 等等
這些是 Jira 中常見的 fields，您可以使用它們來構建 JQL 搜尋，以便根據您的需求進行進階搜尋，且 fields有大小寫之分，要確定正確拼字以達到目的。

上述學習參考來源 JQL fields

今天就聊到這裡啦～