Determine what displays on a Jira board using filters
15 min
Intermediate
By the end of this lesson, you'll be able to:
- Describe how board filters determine a board’s content
- Create sub-filters for kanban boards
- Use quick filters and custom filters to limit displayed cards
- Grant users permission to view or edit filters used as board data sources
Control what appears on your board
Each board has a filter that determines the work items displayed on that board. The board filter uses Jira Query Language (JQL) to show work items that meet specific criteria.
👇You configure board filters the same way you configure other filters in Jira.
Board filters behave differently depending on their space type.
A team-managed board can only include work items from the space it’s in. Because of that, you can’t configure the board filter. The board will always show all work items in the space that have a status included on the board.
A company-managed board can include work items from a single space or multiple, including team-managed spaces.
To configure a board filter in a company-managed space:
- From your board, select More actions (represented by •••), then Board settings.
- Under Board filter, either select a different filter or select Edit filter query to configure the current filter.
Let’s explore some examples!
👇Click the tabs below to see how you would write a filter query for each scenario.
Team A has a board. A new engineering space called ENG is created from the scrum space template. The board filter is automatically configured to show all the work items in the ENG space.
👉 Here’s how you would write the filter query: spaceJira = ENG ORDER BY Rank ASC
If you want to rank your work items on a company-managed board or backlog, you need to include ORDER BY Rank ASC in your board filter.
The term "project" is changing to spaceJira. You can still use the term project in the JQL query until the transition to spaceJira is complete.
👉 For example: spaceJira = ENG ORDER BY Rank ASC would give the same result as project = ENG ORDER BY Rank ASC
Manage who can view company-managed board filters
As a company-managed board admin, you can manage which users can view your board by adjusting the permissions for your board filter. If a user doesn’t have permission to view your filter, they won’t be able to view work items in the board.
To edit board filter permissions in a company-managed space:
- In Board settings, under Board filter, select Edit filter query.
- Next to the filter name, select Filter details.
- Next to Permissions, select Edit permissions.
👇 Click the icons below to learn more about editing permissions.
1
2
3
4
To see the work items on a board in a team-managed space, users need permission to view that space’s work items. Space admins grant this permission through a space role.
Configure the sub-filter
In addition to the board filter, company-managed kanban board admins can configure a sub-filter. Company-managed kanban boards have a default sub-filter that shows work items that either don't have a fixed version or have an unreleased version, but you can edit this.
The sub-filter query enables you to show a subset of the work items encompassed by the board filter. A sub-filter can only ever show fewer work items than the board filter.
To edit a sub-filter:
- From your board, select More actions (represented by •••), then Board settings.
- Under Board sub-filter, click in the field to edit the query.
- Click the checkmark to save your changes.
Board reports will always reflect all work items in the board filter, regardless of the sub-filter.
Create quick filters
Company-managed space boards include quick filters that allow users to limit which work items are displayed. Board admins configure the filters using JQL and they appear as buttons on the board.
👇 In this example, a company-managed space uses quick filters to show only Recently Updated work items or work items Assigned to Me. These filters appear as buttons on the board.
Every board comes with two default quick filters: Assigned to me and Recently updated.
👇 Take a look at the JQL query for each of the default quick filters.
Quick filter | JQL | Description |
|---|---|---|
Assigned to me | assignee = currentUser() | Displays work items assigned to the current user |
Recently updated | updatedDate >= -1d | Displays work items updated in the last day |
Board admins can remove these quick filters and create new ones. To create or edit a quick filter, in board settings, go to Quick Filters.
👉For example: A complex board displays work items across multiple spaces. Create quick filters to show work items from specific teams and spaces.
👇 Here’s an example of quick filters based on the component field.
If users select multiple quick filters when viewing the board, only work items that meet all quick filter criteria will appear.
Create custom filters
Team-managed space boards include a very similar feature called custom filters. Space admins configure the filters using JQL and they appear as checkboxes on the board.
👇 In this example, a team-managed space uses custom filters to show only the Highest priority work items or Lowest priority work items. They appear as checkboxes on the board.
To create or edit a custom filter, in board settings, go to Custom filters.
Understand how filters and queries affect a board
The Engineering team uses a company-managed kanban board. Take a look at their filter configurations below. Then, click the boxes below to see if you can determine what will display on their board.
Filter Query | spaceJira = ENG ORDER BY Rank ASC |
Kanban board sub-filter | assignee is not EMPTY |
Hide completed work items older than | 2 weeks |
Quick Filter 1 | resolution != "Cannot Reproduce" |
Quick Filter 2 | resolution is Empty |
👇 Click the boxes below to see what work items will display on the board.
How was this lesson?
next lesson
Configure Jira board columns and statuses
- Match your board to your workflow
- Configure columns
- Configure statuses