Getting Started

JIRA Extension Points

If you are familiar with JQL Functions from JIRA Server then some of the concepts here are a little different.

It is not possible in JIRA Cloud for an add-on to alter the results of a JQL search either during or after a search is being performed.

ScriptRunner for JIRA Cloud augments each issue in your JIRA instance with some additional metadata and provides a number of JQL "aliases" that you can use within your JQL queries to access this metadata. This metadata is stored within your JIRA instance.

The 'Issue Updated' field on your issues is NOT affected by the metadata that we store against each issue.

See ScriptRunner Enhanced Search for more powerful search functionality provided by ScriptRunner for JIRA Cloud.

Getting Started with JQL Aliases

The metadata that we store against each issue is automatically updated asynchronously whenever an issue is updated. This means that your search results may be out-of-date for a second or two after you edit an issue.

When ScriptRunner for JIRA Cloud is installed, or when you want to opt into this feature, an administrator must perform an initial synchronization. Although an administrator initiates the synchronization process, issues are accessed as the ScriptRunner Add-on user.

Search results will be incorrect if the ScriptRunner Add-on user does not have permission to:

  • view and edit all issues (edit permission is required to store the additional metadata)

  • view all comments, including those restricted to a particular group/role

  • view all worklogs, including those restricted to a particular group/role

You can do the initial synchronization on the JQL Aliases Sync page found in the Add-ons Administration section of JIRA:

JQL Aliases Sync page

If you close this page while the sync is in progress, it will stop.

Syncing can be resumed at a later date by visiting this page and clicking on the Sync All Issues button. Search results for queries that use these aliases will be incorrect until an initial sync has been completed.

Here is a list of the metadata that we store against each issue:

  • a list of the link types (e.g. Blocks) for linked issues

  • the number of issue links

  • a list of link names (e.g. "is cloned by") for linked issues

  • number of attachments on the issue

  • list of file extensions from attachments

  • the date on which the first attachment was added to the issue

  • date on which the last (most recent) attachment was added to the issue

  • list of username that added attachments to the issue

  • number of subtasks of the issue

  • list of project roles that worklogs were restricted to

  • list of user groups that worklogs were restricted to

  • number of comments on the issue

  • date of the first comment on the issue

  • date of the last (most recent) comment on the issue

  • list of all dates on which comments were added to the issue

  • list of usernames that have added comments to the issue

  • list of project roles that comments have been restricted to

  • list of user groups that comments have been restricted to

  • the username of the person who last (most recent) made a comment on the issue

  • the project role that the last (most recent) comment was restricted to

  • the user group that the last (most recent) comment was restricted to

JQL Functions

As mentioned at the top of this page, it is not possible to integrate directly into the standard search functionality that JIRA Cloud provides.

The ScriptRunner Enhanced Search functionality provides the ability to run advanced JQL functions in your JIRA filters in a similar way to ScriptRunner for JIRA Server.

JQL Aliases

Each alias here has an explanation and an example. See the comparison table below for a direct comparison with ScriptRunner for JIRA Server.

These JQL aliases will not work until an initial metadata synchronization has been performed. See the getting started section above.

These JQL Aliases can be used in the Issue Search screen when searching in Advanced mode. Here’s an example of using the numberOfComments JQL Alias.

JQL Aliases in Issue Search screen

Linked Issues

This alias is used to retrieve issues that have a certain number of issue links.

status = Open AND numberOfLinks = 3

We can use numeric comparison operators like >, <, !=, <= and >= as well as =.

numberOfLinks > 5 AND numberOfLinks <= 10

issueLinkType

This alias can be used to search for issues based on the type of issue links that they have. The link type is the name that describes the link, regardless of its direction e.g. Blocks, Cloners, Duplicates.

project = SALES AND issueLinkType = 'Blocks'

We can also use the JQL keyword in to search for issues that have any of the specified link types:

assignee = currentUser() AND issueLinkType in ('Blocks', 'Duplicate')

The JQL operators != and not in also work with this alias.

This alias can be used to search for issues that have links in a particular direction. This alias can be compared against a link name e.g. "is blocked by", "duplicates", "relates to"

type = Improvement AND hasLinks = "relates to"

In the same way as issueLinkTypes, you can use the operators: =, !=, in and not in

Attachments

numberOfAttachments

This alias can be used to find issues that have a certain number of file attachments.

status = Closed AND numberOfAttachments > 3

This alias can be used with the numeric comparison operators.

attachmentType

This alias can be used to search for issues that have a particular file type attached to them. File types are determined by the file extension e.g. a file called screenshot.png has a file type of 'png'

numberOfAttachments > 0 AND attachmentType = 'jpg'
issuetype = Invoice AND attachmentType in ('pdf', 'docx', 'xls')

This alias can use the =, !=, in and not in operators.

firstAttachmentDate

The firstAttachmentDate alias can be used to find issues based on the date that the first attachment was added:

project = STORAGE AND firstAttachmentDate < now()
project = STORAGE AND firstAttachmentDate >= '2016-04-01'
project = STORAGE AND firstAttachmentDate = '2000-01-01'

As you can see from the first example, we can use relative date functions that come built-in to JQL. We can also use the regular numeric comparison operators.

lastAttachmentDate

The lastAttachmentDate alias can be used to find issues based on the date that the most recent attachment was added:

project = STORAGE AND lastAttachmentDate > startOfMonth()

In the same way as firstAttachmentDate, this alias can use the numeric comparison operators and the relative date JQL functions.

fileAttachedBy

This alias can be used to find issues that have a file attached by a particular user. You must use the username of the user you are interested in.

reporter = currentUser() AND fileAttachedBy = "jbloggs"

This alias can also be compared using the !=, in and not in operators.

Subtasks

numberOfSubtasks

The numberOfSubtasks alias can be used to search for issues with a certain number of subtasks.

issuetype = Task AND numberOfSubtasks > 10

This alias can also use the numeric comparison operators.

Worklogs

worklogVisibleRole

This alias can be used to find issues that have time logged against them that is restricted so it is only visible to other users in a specific project role.

timespent > 8h AND worklogVisibleRole = 'Project Administrator'

This alias can also use the !=, in and not in operators.

worklogVisibleGroup

The worklogVisibleGroup alias can be used to find issues that have time logged against them that is restricted so it is only visible to other users in a user group.

project = DEV AND worklogVisibleRole = 'jira-developers'

This alias can also use the !=, in and not in operators.

Comments

numberOfComments

The numberOfComments alias can be used to find issues with a particular number of comments:

resolution = 'Wont Fix' AND numberOfComments > 0

This alias can be used with the numeric comparison operators.

firstCommentedDate

The firstCommentedDate alias can be used to search for issues based on the date of the first comment.

created > startOfDay() AND firstCommentedDate = now()
priority = High AND firstCommentedDate < startOfWeek()

This alias can be used with the JQL relative date functions and also the numeric comparison operators.

lastCommentedDate

The lastCommentedDate alias can be used to search for issues based on the date of most recent comment.

assignee = currentUser() AND lastCommentedDate < startOfMonth()
status = 'In Progress' AND lastCommentedDate = '2016-10-14'

This alias can be used with the JQL relative date functions and also the numeric comparison operators.

commentedOn

This alias can be used to find issues that had a comment made on them on a particular date.

commentedOn = '2016-02-14' AND project = VALENTINE
project = APOLLO AND assignee = narmstrong AND commentedOn in ('1969-07-20', '1969-07-21')

The commentedOn alias can be used with the following operators: in, not in, != AND =

commentedBy

The commentedBy alias can be used to search for issues that have comments on them made by a particular user. You must specify a username:

reporter = currentUser() AND commentedBy = 'jsmith'

This alias can be used with the following operators: in, not in, != AND =

commentVisibleRole

The commentVisibleRole alias is used to find issues that have comments on them that are restricted to only be visible to users within a particular project role.

project = SUPPORT AND commentVisibleRole = 'Service Desk Team'
priority = Highest AND commentVisibleRole in ('Project Administrator', 'Developer')

This alias can be used with the following operators: =, !=, in and not in

commentVisibleGroup

The commentVisibleGroup alias is used to find issues that have comments on them that are restricted to only be visible to members of a particular group.

project = TOPSECRET AND commentVisibleGroup = 'Secret Agents'

This alias can be used with the following operators: =, !=, in and not in

lastCommentBy

This alias can be used to search for issues based on the user who made the most recent comment. You must provide a username:

reporter = 'jsmith' AND lastCommentBy = currentUser()
assignee = currentUser() AND lastCommentBy in ('jbond', 'jbauer')

This alias can be used with the following operators: =, !=, in and not in

lastCommentVisibleRole

This alias can be used to search for issues based on whether the most recent comment was restricted to only be viewed by members of a particular project role:

project = SUPPORT AND lastCommentVisibleRole = 'Developers'

This alias can be used with the following operators: =, !=, in and not in

lastCommentVisibleGroup

This alias can be used to search for issues based on whether the most recent comment was restricted to only be viewed by members of a particular user group:

priority = Low AND lastCommentVisibleGroup = 'Management'

This alias can be used with the following operators: =, !=, in and not in

Comparison with ScriptRunner for JIRA Server

The table below contains equivalent JQL queries from ScriptRunner for JIRA Server and JIRA Cloud. Differences between the two systems are highlighted.

JIRA Server JQL JIRA Cloud JQL Description
issueFunction in hasComments(3)
numberOfComments = 3

Issues have exactly 3 comments

issueFunction in hasComments('+5')
numberOfComments > 5

Issues have more than 5 comments

issueFunction in hasComments('-5')
numberOfComments < 5

Issues have less than 5 comments

issueFunction in commented("after -7d")
lastCommentedDate > startOfDay("-7d")

Issues with comments added within the last 7 days

issueFunction in commented("on 2012/12/31")
commentedOn = '2012-12-31'

Issues with comments created on 31st December 2012

issueFunction in commented("by jbloggs")
commentedBy = jbloggs

Issues with comments authored by user jbloggs

issueFunction in commented('by currentUser()')
commentedBy = currentUser()

Issues with comments authored by the current logged in user

issueFunction in commented("roleLevel Developers")
commentVisibleRole = Developers

Issues with comments restricted to the Developers role

issueFunction in commented("groupLevel jira-administrators")
commentVisibleGroup = 'jira-administrators'

Issues with comments restricted to the jira-administrators group

issueFunction in commented("before startOfWeek()")
firstCommentedDate < startOfWeek()

Issues with comments added before the start of this week

issueFunction in commented('after startOfMonth(-1) before endOfMonth(-1) by currentUser()')
lastCommentedDate > startOfMonth('-1') AND lastCommentedDate < endOfMonth('-1') AND commentedBy = currentUser()

Issues with comments added after the start of last month and comments added before the end of last month and comments authored by the current user

issueFunction in commented('inGroup jira-users')

not available

Issues with comments by a user in the jira-users group

issueFunction in commented('inRole Administrators')

not available

Issues with comments by a user with the Administrators role

issueFunction in lastComment('by jbloggs')
lastCommentBy = jbloggs

Issues with the most recent comment authored by user jbloggs

issueFunction in lastComment('after startOfWeek()')
lastCommentedDate > startOfWeek()

Issues with the most recent comment created since the start of the week

issueFunction in lastComment('before 2016-01-01')
lastCommentedDate < '2016-01-01'

Issues with the most recent comment created before 1st January 2016

issueFunction in lastComment('on 2015-02-01')
lastCommentedDate = '2015-02-01'

Issues with the most recent comment created on the 14th February 2015

issueFunction in lastComment('inRole Developers')

not available

Issues with the most recent comment authored by a user with the Developers role

issueFunction in lastComment('inGroup jira-administrators')

not available

Issues with the most recent comment authored by a user in the jira-administrators group

issueFunction in lastComment('roleLevel Developers')
lastCommentVisibleRole = Developers

Issues with the most recent comment restricted to only the Developers role

issueFunction in lastComment('roleGroup jira-users')
lastCommentVisibleGroup = jira-users

Issues with the most recent comment restricted to only the jira-users group

issueFunction in lastUpdated('by asmith')

not available

Issues that were updated most recently by user asmith

issueFunction in lastUpdated('inRole Administrators')

not available

Issues that were updated most recently by a user with the Administrators role

issueFunction in lastUpdated('inGroup jira-software-users')

not available

Issues that were updated most recently by a user in the jira-software-users group

issueFunction in hasAttachments()
numberOfAttachments > 0

Issues that have attachments

not available

numberOfAttachments > 10

Issues that have at least 10 attachments

issueFunction in hasAttachments("docx")
attachmentType = "docx"

Issues that have attachments with the 'docx' file extension

issueFunction in fileAttached('after -4w')
lastAttachmentDate > startOfDay('-4w')

Issues that have attachments uploaded since 4 weeks ago

issueFunction in fileAttached('before lastLogin()')
firstAttachmentDate < lastLogin()

Issues that have attachments uploaded before the current users last login

issueFunction in fileAttached('on startOfWeek()')

not available

Issues that have attachments uploaded at the start of the week

issueFunction in fileAttached('by jbloggs')
fileAttachedBy = jbloggs

Issues that have attachments uploaded by user jbloggs

issueFunction in workLogged('inRole Developers')

not available

Issues that have work logged against them by a user with the Developers role

issueFunction in workLogged('inGroup service-desk-users')

not available

Issues that have work logged against them by a user in the service-desk-users group

issueFunction in workLogged('roleLevel Developers')
worklogVisibleRole = Developers

Issues that have work logged against them restricted to the Developers role

issueFunction in workLogged('groupLevel service-desk-users')
worklogVisibleGroup = 'service-desk-users'

Issues that have work logged against them restricted to the service-desk-users group

issueFunction in workLogged('by jsmith')

provided by JIRA: worklogAuthor = jsmith

Issues that have work logged by user jsmith

issueFunction in workLogged('on 2011-06-30')

provided by JIRA: worklogDate = 2011-06-30

Issues that have work logged on the 30th June 2011

issueFunction in workLogged('after startOfWeek()')

provided by JIRA: worklogDate > startOfWeek()

Issues that have work logged since the start of this week

issueFunction in workLogged('before startOfMonth()')

provided by JIRA: worklogDate < startOfMonth()

Issues that have work logged before the start of this month

issueFunction in dateCompare(subquery, date comparison expression)

See JQL Functions for more information

issueFunction in hasSubtasks()
numberOfSubtasks > 0

Issues that have subtasks

not available

numberOfSubtasks >= 10

Issues that more than or equal to 10 subtasks

issueFunction in subtasksOf(subquery)

See JQL Functions for more information

issueFunction in parentsOf(subquery)

See JQL Functions for more information

issueFunction in hasLinks()
numberOfLinks > 0

Issues that have links to other issues

not available
numberOfLinks = 5

Issues that have 5 links to other issues

issueFunction in hasLinks("is blocked by")
hasLinks = "is blocked by"

Issues that are blocked by other issues

issueFunction in hasLinkType("Duplicates")
issueLinkType = "Duplicates"

Issues that have a Duplicates issue link (either inbound or outbound)

issueFunction in linkedIssuesOf(subquery)

available via ScriptRunner Enhanced Search

See JQL Functions for more information

issueFunction in epicsOf(subquery)

not available

Can be achieved using linkedIssuesOf

issueFunction in issuesInEpics(subquery)

not available

Issues in epics that match the subquery

issueFunction in linkedIssuesOfRecursive(subquery, linkName)

available via ScriptRunner Enhanced Search

See JQL Functions for more information

issueFunction in linkedIssuesOfRecursiveLimited(subquery, depth, linkName)

available via ScriptRunner Enhanced Search

See JQL Functions for more information

issueFunction in linkedIssuesOfRemote(remoteLink, searchTerm)

not available

Issues with remote links that match the search term

issueFunction in expression(Subquery, expression)

See JQL Functions for more information

project in projectMatch(regularExpression)

See JQL Functions for more information

fixVersion in versionMatch(regularExpression)

See JQL Functions for more information

component in componentMatch(regularExpression)

See JQL Functions for more information

issueFunction in issueFieldMatch(subquery, fieldName, regularExpression)

See JQL Functions for more information

issueFunction in issueFieldExactMatch(subquery, fieldName, regularExpression)

See JQL Functions for more information

issueFunction in recentProjects()

not available

Issues in the current user’s recently view projects

issueFunction in myProjects()

not available

Issues in the current user’s projects

issueFunction in aggregateExpression()

not available

See JQL Functions for more information

fixVersion in earliestUnreleasedVersionByReleaseDate(projectKey)

not available

Issues with a fixVersion that matches the unreleased version with the earliest release date

issueFunction in addedAfterSprintStart(boardName, sprintName)

not available

Issues that were added to a sprint after it started

issueFunction in removedAfterSprintStart(boardName, sprintName)

not available

Issues that were removed from a sprint after it started

issueFunction in incompleteInSprint(boardName, sprintName)

not available

Issues that were not completed in a sprint

issueFunction in completeInSprint(boardName, sprintName)

not available

Issues that were completed in a sprint

issueFunction in nextSprint(boardName)

not available

Issues that are in the next sprint for a given Agile board

issueFunction in previousSprint(boardName)

not available

Issues that are in the previous sprint for a given Agile board

issueFunction in inSprint(boardName, sprintName)

not available

Issues that are in a given sprint