This documentation relates to version 1.7 of the Rich Filters Add-on for JIRA. Documentation for previous versions is available via the documentation index.
Dynamic Filters allow the users to further filter the collection of issues displayed by gadgets based on the current rich filter. Dynamic filters are based on JIRA fields (built-in or custom) and allow filtering issues by field values. Once configured, the dynamic filters are displayed in Rich Filter Controller Gadgets as buttons with drop-down menus (for option/user/label/etc fields), text search boxes (for text-based fields), or date search boxes with calendar drop-downs (for date fields). When a dynamic filter is activated in a Rich Filter Controller Gadget, all the other gadgets in the same dashboard and which are based on the same rich filter apply the selected criteria (the required JQL is automatically generated).
Dynamic Filter Types
As mentioned, there are three types of dynamic filters, depending on the type of field they are based on:
Option dynamic filters are used for fields that can take predefined values, such as check-boxes, select lists (single or multi select), status, priority, labels, user pickers, etc. Controller gadgets display these as buttons with drop-down menus, which allow selecting among the options available for each field.
When activated, dynamic filters limit the results to only those issues that match the selected options. If more than one option is selected, the filters will pass issues that have any of the selected values. (In JQL syntax, the selected options are
ORed together, then the result is
ANDed with the other JQL parts)
The options displayed are chosen only based on issues returned by the base JIRA filter – it doesn’t show options that are defined by the field configurations but do not occur among your issues, increasing the relevance of the filter.
For example, this is very useful if you add a dynamic filter for the Assignee field. The drop-down menu displays only users who have at least one issue assigned.
Text dynamic filters are used for string and text fields, such as the issue summary and description. Text filters don’t use a menu: instead, they just display a text box. The required JQL is automatically generated to filter only issues that contain the entered text.
JIRA has two different text searchers, one for exact string search and one for full-text search. Dynamic filters will use one or the other, depending on how your field is configured. Advanced search features such as prefix and wildcard queries are supported. See JIRA’s documentation for the syntax.
Besides issue fields, there are two extra text dynamic filters that you can add in your rich filters: one is labeled Issue Text, and allows searching at the same time the summary, environment, description, the comments of an issue, as well as all custom text fields; the other is labeled Issue Comments, and searches exactly what the name suggests.
- Date dynamic filters are used for date/time fields, such as created, updated, resolution date and custom date fields. Date filters allow the user to filter only issues with date field values on, before, after or between two dates.
Each dynamic filter has two date inputs – Since and Until:
- If Since is filled, then only issues having values on or after the inserted value are displayed;
- If Until is filled, then only issues having values on or before the inserted value are displayed;
- If both Since and Until are filled, then only issues having values between Since and Until (inclusive) are displayed.
The inputs Since/Until can be picked from a calendar or entered manually as an absolute date (“yyyy/MM/dd” or “yyyy-MM-dd”) or time relative to the present (e.g. “5d”, “4w 2d”).
If you need to search for issues on a single date, enter that date in both Since and Until at the same time.
In order to insert 'now' in Since/Until, one option is to use the value '0d'.
Supported fields and compatibility with 3rd party add-ons
We support dynamic filters for most of the built-in JIRA issue fields and custom fields: Project, Summary, Issue Type, Status, Priority, Resolution, Affects and Fix Version(s), Component(s), Labels, Environment, Description, Assignee, Reporter, Due Date, Created, Updated, Resolved, Sprint and Epic Link (for JIRA Software), Select List (single/multiple choices and cascading), Checkboxes, Radio Buttons, Labels Custom Field, User Picker (single/multiple users), Group Picker (single/multiple groups), Project Picker, Text Field (single/multi line), URL Field, Date Picker and Date Time Picker.
We also support dynamic filters for all custom fields added by 3rd party add-ons that use one of JIRA's built-in custom field searchers: Single/Multi/Cascading Select Searcher, Labels Searcher, Group Picker Searcher, Project Dropdown Searcher, Exact Text Searcher, Free Text Searcher, Date Range Picker, Date Time Range Picker.
Moreover, we do our best effort to support dynamic filters for some of the custom field searchers added by popular 3rd party add-ons. If one of the custom searchers you're using is not yet supported, contact our support service and we'll do our best to help you.
Troubleshooting dynamic filters based on 3rd party searchers
In order for the dynamic filters to work for custom fields based on searchers added by 3rd party add-ons, the minimum requirement is that the searcher needs to have implemented a Statistics Mapper. A quick test would be to see if the field can be used as a statistic criteria in a 'Issue Statistics' built-in JIRA gadget. Also, it is important to make sure the field and searcher are correctly configured. Make sure the options are displayed correctly in the 'Issue Statistics' JIRA gadget.
The performance of the dynamic filter (display/search speed) depends entirely on the configuration and implementation of the 3rd party custom field. When used as a dynamic filter, the field will have exactly the same performance as when used in JIRA's built-in Issue Navigator and 'Issue Statistics' gadget.
Editing Dynamic Filters
- Navigate to the desired rich filter.
- Open the Dynamic Filters section.
- Edit the dynamic filters as described in the following table and screenshot:
|To do the following:||Do this:|
|Add a Dynamic Filter||
Click on the Pick a field... button at the bottom of the page. A drop-down menu is displayed, showing all supported fields. Either scroll down or use the search to find the field you want, then click on the “plus” icon on the right, or press
|Delete a Dynamic Filter||
Click the delete icon at the right of the dynamic filter.
|Reorder the Dynamic Filters||
Hover over the vertical “grid” icon, then drag and drop the dynamic filter up or down to its new position.
When the dynamic filters of this rich filter are displayed by Controller gadgets, by default the dynamic filters are displayed in the order configured in this section.
|Change the options order of a Dynamic Filter||
This applies only to option (single-select or multiple-select) fields.
By default, the order of the options shown by dynamic filters in Controller gadgets is the alphabetical order. Hover over the dynamic filter and click on Edit.
You can then chose between Alphabetical and Natural (the order of the options as defined by JIRA administrators).
This can be very useful. For example, if you have a single-select field called Size with options S, M, L, XL, then the alphabetical order is not very intuitive. It makes more sense to use the natural order in this case.