今日分享

1. JQL 句型結構複習
2. JQLFunctions 函數

JQL 句型結構複習

昨天我們有談過 JQL 通常用於進階式的搜尋，大家還記得 JQL 組合元素嗎？
我們以 project = "TEST" AND assignee = currentuser() 為例，這句話的意思是，需要進階搜尋出 project key 為 TEST 中，Assignee 是 當前使用者的 issues。
以下是這句 JQL 的元素拆解。

上述元素中，我們已經認識了三個，分別為 Keywords、Operators 和 Fields

想了解細節可查詢 衝流量

• Day24- 解析 JQL 讓 Automation 更進階-認識 JQL Keywords後，設定開新版本後自動加入 IN PROGRESS 的票中
• Day25 - 解析 JQL 讓 Automation 更進階 - 今天來認識 JQL operators （運算符號）
• Day27- 解析 JQL 讓 Automation 更進階 - JQL fields 是什麼？

今天要談的是 JQL Functions (￣▽￣)~*

JQL Functions 函數

Functions 是啥？我們來看看上面的 JQL 語法中，在右邊👉有個較長的名詞 看起來像亂碼的

Functions，函數，這個單詞後面通常會跟著括號（），括號中可以包含一個或多個明確的值或 Jira fields 區段。在一個子句中，函數前面是一個 Operators 運算符號，運算符號前面是一個字段。函數對特定的 Jira 數據或括號中函數的內容執行計算，以便函數搜尋的結果正確，然後再由使用該函數的子句再次搜尋。
除非在搜尋查詢中指定，請注意 JQL 搜尋不會返回結果中的空區段。
比如：為了在搜索未分配給當前使用者的問題時包括空字段（例如未分配的問題），您可以輸入（assignee != currentUser() OR assignee is EMPTY）以在結果列表中包括未分配的問題。

我從 Atlassian 學習文章中找到以下共 53 個函數 （數長慎入）

• approved()
• approver()
• breached()
• cascadeOption()
• closedSprints()
• completed()
• componentsLeadByUser()
• currentLogin()
• currentUser()
• customerDetail()
• earliestUnreleasedVersion()
• elapsed()
• endOfDay()
• endOfMonth()
• endOfWeek()
• endOfYear()
• everbreached()
• futureSprints()
• issueHistory()
• issuesWithRemoteLinksByGlobalId()
• lastLogin()
• latestReleasedVersion()
• linkedissue
• linkedIssues()
• membersOf()
• myApproval()
• myPendingApproval()
• myPending()
• now()
• openSprints()
• organizationDetail()
• organizationMembers()
• parentEpic()
• paused()
• pending()
• pendingBy()
• projectsLeadByUser()
• projectsWhereUserHasPermission()
• projectsWhereUserHasRole()
• releasedVersions()
• remaining()
• running()
• standardIssueTypes()
• startOfDay()
• startOfMonth()
• startOfWeek()
• startOfYear()
• subtaskIssueTypes()
• unreleasedVersions()
• updatedBy()
• votedIssues()
• watchedIssues()
• withinCalendarHours()

請大家聽我娓娓道到～～～～～～～～並 ⋯⋯ 沒 ⋯⋯ 有！

我就"只"列舉幾個比較常用或是比較多 fields 支援的函數跟大家說明一下。

Supported fields：Created, Due, Resolved, Updated, custom fields of type Date/Time

1. currentLogin():根據當前用戶會話開始的時間進行搜索。

• 語法：currentLogin()
• 可用 operators:= , != , > , >= , < , <= WAS* , WAS IN* , WAS NOT* , WAS NOT IN* , CHANGED*
• 用法例句：查找在我的當前會話期間創建的問題 created > currentLogin()

2. lastLogin()：根據當前用戶上一個對話開始的時間進行搜尋。

• 語法：lastLogin()
• 可用的 operators：= , != , > , >= , < , <= WAS* , WAS IN* , WAS NOT* , WAS NOT IN* , CHANGED** Only in predicate
• 用法例句：查找在我的上一個會話期間創建的問題 created > lastLogin()

3. endOfDay():根據當前日期的結束執行搜尋。另外，endOfWeek()、endOfMonth()和endOfYear()；startOfDay()、startOfWeek()、startOfMonth()和startOfYear()等，其邏輯和用法也是以此類推。

• 語法：

endOfDay()
endOfDay("inc")

其中，inc 是可選的增量，格式為 (+/-)nn(y|M|w|d|h|m)。如果時間單位標識被省略，則默認為該函數的自然週期，例如 endOfDay("+1") 等同於 endOfDay("+1d")。如果省略了加減號 (+/-)，則假定為加號。

• 可用的 operators:= , != , > , >= , < , <= WAS* , WAS IN* , WAS NOT* , WAS NOT IN* , CHANGED**
• endOfDay()用法例句：尋找到期日是今天結束前的問題 due < endOfDay()
• endOfWeek()用法例句：尋找到下一周結束前到期的問題 due < endOfWeek("+1")
• endOfMonth()用法例句：尋找到下個月15日到期的問題 due < endOfMonth("+15d")
• endOfYear()用法例句：尋找到明年三月底到期的問題 due < endOfYear("+3M")

4. now()：根據當前時間執行搜索。

• 語法：now()
• 可用的 operators：= , != , > , >= , < , <= WAS* , WAS IN* , WAS NOT* , WAS NOT IN* , CHANGED
• 用法例句：找出找出逾期的問題 duedate < now() and status not in (closed, resolved)

Supported fields:Assignee, Reporter, Voter, Watcher, Creator, custom fields of type User

1. currentUser():根據目前已登錄的用戶執行搜索。

• 語法：currentUser()
• Supported operators:= , !=
• 用法例句：查找分配給我的問題 assignee = currentUser()
• 用法例句：查找向我報告但未分配給我的問題 reporter = currentUser() AND (assignee != currentUser()

2. customerDetail():根據客戶詳細信息執行搜索。

• 語法：customerDetail( )
• 此功能僅適用於 Jira Service Management的 Premium and Enterprise 方案 。要使用此JQL功能，在 Project 設置中的功能頁面上啟用“客戶服務管理”。
• Supported operators:IN , NOT IN
• 用法例句：為所有非技術聯絡人報告的客戶建立一個請求佇列 reporter not in customerDetail("Role", "Technical Contact")

3. membersOf()：用於基於特定群組成員搜索。
   語法：membersOf(Group)
   可用的 operators：IN , NOT IN , WAS IN , WAS NOT IN
   用法例句：找出負責人屬於群組 "jira-administrators" 的問題 assignee in membersOf("jira-administrators")

Supported fields:Sprint

1. closedSprints()：搜索分配給已完成的Sprint的問題。

• 一個問題可能同時屬於已完成的Sprint（S）和未完成的Sprint（S）。
• 語法：closedSprints()
• Supported operators：IN , NOT IN
• 用法例句：查找所有分配給已完成Sprint的問題 sprint in closedSprints()
• 以此類推 openSprints()用法，例如：找出所有分配給尚未完成的迭代的問題 sprint in openSprints()

2. futureSprints()：搜索分配給尚未開始的 Sprint 的問題。

• 一個問題可能同時屬於已完成的Sprint（S）和未完成的Sprint（S）。
• 語法：futureSprints()
• Supported operators：IN , NOT IN
• 用法例句：查找所有分配給尚未開始的Sprint的問題 sprint in futureSprints()

Supported fields：Issue

1. issueHistory()：查找您最近查看的問題，即出現在“問題”下拉菜單的“最近問題”部分的問題。

• 注意：issueHistory()最多返回50個問題，而“最近問題”下拉菜單僅返回5個。如果您未登錄Jira，則只會包含來自您當前瀏覽器會話的問題。
• 語法：issueHistory()
• 可用的 operators：IN , NOT IN
• 用法例句：查找我最近查看的並且分配給我的問題 issue in issueHistory() AND assignee = currentUser()

2. issuesWithRemoteLinksByGlobalId()：根據與具有指定的任何全局ID的遠程連結相關的問題執行搜索。此功能接受1到100個globalId。指定0或超過100個globalId將導致錯誤。

• 語法：issuesWithRemoteLinksByGlobalId()
• 可用的 operators：IN , NOT IN
• 用法例句：查找與具有全局ID“abc”或“def”的遠程鏈接相關聯的問題 issue in issuesWithRemoteLinksByGlobalId(abc, def)

3. linkedissue：用於搜索 Epic 和子任務。如果問題不是 Epic，則搜索將返回該問題的所有子任務。

• 語法：linkedissue = issueKey
• 可用的 operators：=, !=
• 用法例句：要查找與特定 Epic 相關連的子任務 linkedissue = epicKey-123

4. linkedIssues() ：用於搜索與某個問題相關聯的問題。您可以限定搜索特定類型的連結。

• 語法：

linkedIssues(issueKey)
linkedIssues(issueKey,CaseSensitiveLinkType)

• 可用的 operators：IN , NOT IN
• 用法例句：查找通過特定類型的連結與特定問題相關的問題 issue in linkedIssues(ABC-123,"is duplicated by")

Supported fields：AffectedVersion, FixVersion, custom fields of type Version

1. earliestUnreleasedVersion()：根據項目中最早的未發布版本進行搜索。（版本順序由版本在項目的“發行”頁面上放置的順序確定。列表底部的版本被視為“最早”。要更改版本的順序，請將其拖放到列表中的新位置。）

• 語法：earliestUnreleasedVersion(project)
• Supported operators：= , != , ~ , !~ , > , >= , < , <=, IS, IS NOT, WAS, WAS NOT
• 用法例句：查找其FixVersion為ABC項目的最早未發布版本的問題 fixVersion = earliestUnreleasedVersion(ABC)
• 上述邏輯和用法，也可以此類推至 unreleasedVersions。

2. latestReleasedVersion()：根據指定專案的最新發行版本（即最近發行的版本）進行搜索。（“最新”是由分配給版本的順序確定的，而不是根據實際的版本截止日期。）

• 語法：latestReleasedVersion(project)
• Supported operators：= , !=
• 用法例句：找出與ABC項目的最新發行版本有關的問題 affectedVersion = latestReleasedVersion(ABC) 或 fixVersion = latestReleasedVersion(ABC)
• 上述邏輯和用法，也可以此類推至 releasedVersions()。

Supported fields：SLA （僅適用於 Jira Service Management的 site）

1. breached()：返回最近的 SLA 未能達成目標的問題。

• 語法：breached()
• 可用的 operators：= , !=
• 用法例句：查找 Time to First Response 被違反的問題。

2. completed()：返回已完成至少一個週期的 SLA 的問題。

• 語法：completed()
• 可用 operators：= , !=
• 用法例句：找出 Time to First Response 至少完成一個週期的問題 "Time to First Response" = completed()

2. elapsed()：返回其SLA時鐘相對於循環開始事件的某一點的問題。

• 語法：elapsed()
• Supported operators：= , !=, > , >= , < , <=
• 用法例句：查找等待首次回應時間超過1小時的問題 "Time to First Response" > elapsed("1h")

3. everbreached()：返回錯過其SLA目標之一的問題。

• 語法：elapsed()
• Supported operators：= , !=
• 用法例句：查找未達到首次響應時間目標的問題 "Time to First Response" = everbreached()

想知道更多，請詳閱 JQL functions

今天就先練習到這裡，我們明天見囉～