The Adaptavist Group LogoDocumentation

Work with Filters

Find and manage saved Jira filters using HAPI, including searching by name or owner.

Finding filters

With HAPI, you can retrieve all filters with a given name or return a specific filter using a name and owner combination or the filter id. Once you have the filter, you can use it with our issue search methods, as demonstrated below.

Find a filter you own by name

You can find a filter that you own as follows:

def myFilter = Filters.getMyFilterByName('My Filter')

Find a filter by name and owner

You can find a filter shared with you from another user as follows:

def user = Users.getByName('johndoe')
def johnsSharedFilter = Filters.getByName("John's Filter", user)

Find all filters with a given name

You can find a list of filters with the same name and then further filter that list to return only the filters you want. For example, find all the filters shared with all logged-in users:

// Get all filters with a given name and find only those shared with any logged-in user
def sharedWithAnyLoggedInUsers = Filters.getByName('A Shared Filter').findAll { filter ->
	filter.permissions.authenticated
}

Find all filters

You can retrieve all the filters accessible to you as follows:

def allFilters = Filters.getAll()

You can then filter the result to return only the filters you care about. For example, you could get all filters shared with a specific group:

import com.atlassian.jira.sharing.type.ShareType
        
def allFilters = Filters.getAll()
        
// Find filters shared with a specific group
allFilters.findAll { filter ->
	filter.getPermissions().any { permission ->
		permission.getType() == ShareType.Name.GROUP 
			&& permission.getParam1() == Groups.getByName('abc-group').name
	}
}

Finding a filter by ID

You can find a filter by ID as follows:

Note: To get the filter ID, go to Issues → Manage filters, open the filter you want, and the filter ID is in the URL (for example /jira/browse/SSPA-1?filter=10000)
def myFeaturesFilter = Filters.getById(10001)

Searching with a filter

You can search for issues using a filter. For example, you have already created a JQL query and saved it as a filter. You now want to run the filter and use the issue.update method to set a comment on all returned issues.

Note: In this example we're returning all issues of a saved filter. Where the example says "do something with each issue", you can, for example, update all returned issues using the issue.update method.
def filter = Filters.getMyFilterByName('My Private Filter')
            
Issues.search(filter).each { issue ->
	// do something with each issue
}

Counting issues with a filter

You can count the number of issues returned by a filter. For example:

def user = Users.getByName('johndoe')
def filter = Filters.getByName("John's Shared Bugs Filter", user)
             
def issueCount = Issues.count(filter)

Checking if an issue matches a filter

You can check if an issue matches your filter. The script returns true if the issue is included in the issues returned by your filter. For example:

def user = Users.getByName('janedoe')
def filter = Filters.getByName("Jane's Shared Filter", user)

def issue = Issues.getByKey('ABC-1')
issue.matches(filter)

Search documentation

Start typing to search the docs.