Our new Appfire Documentation Space is now live!
Take a look here! If you have any questions please email support@appfire.com
Custom statistics compatible searchers provided by JMCF
Introduction
Searchers (also known as Search templates) are assigned to custom fields (both Standard and Advanced) to control how you can search for issues based on these fields. They also control how the fields are handled in statistics gadgets on dashboards.
Searching requires an index to have already been built. Lucene is able to achieve fast search responses because, instead of searching the text directly, it searches an index instead. Indexes are updated when an issue changes or when the entire Lucene index is rebuilt. A custom field searcher defines both what should be added to each Lucene Document in the index, and also the Lucene query to run against the index when searching for issues. Searchers also define what appears when results are grouped and the auto-completion prompts used when entering search values.
On this page:
Limitations of searchers provided by Jira
After you create a custom field (Standard or Advanced) in Jira, you can also configure a Search template to be applied to the custom field. Jira provides useful searchers like Free Text Searcher, Multi Select Searcher, Number Searcher
and others relevant to the custom field type created. However, many of the built-in searchers are not statistics-compatible. Statistics compatible searchers are searchers that allow you to create statistics (Pie-charts or Two-dimensional gadgets) on the dashboard by the custom field value. All JMCF searchers support statistics.
With JMCF add-on installed in your instance, JMCF statistics compatible searchers will be available for Jira Standard custom fields too!
For example, you want to show the total number of Story Points as one of the dimensions in the Two-dimensional gadget on the dashboard. You cannot do this using the native search templates provided by Jira because they are not statistics-compatible. However, with JMCF in your instance, you can select the custom searcher, Number Range Searcher (statistics-compatible)
, in the Search Template of the Story Points field and use it in statistics.
Searchers provided by JMCF
Along with being able to use a searcher to define how to search for issues in the Issue Navigator with a given value in the field, you can also enable and format their display in the gadgets like Two-dimensional gadget or the Pie-chart gadget to group results.
Number Range Searcher (Statistics-compatible)
When you select the Number Range Searcher (Statistics-compatible) as the Search template for a custom field of Number type provided by Jira or JMCF, you can search for issues with the custom field value of a given range and value, and use it in statistics gadgets.
Applicable to
This search template is applicable to:
- Number type custom field of Jira
- Calculated (scripted) Number Field of JMCF
- Transition Count Field of JMCF
Use cases
Search Epics with Story points (of all Stories) greater than 50
Group tickets by Business value (Jira custom number field)
Group Epics by number of Story Points of all stories in the Epic
Group tickets by code fix rejection count
Date Time Range Picker (Statistics by day/week/month/quarter/year)
When you select the Date Time Range Picker (Statistics by day/week/month/quarter/year) as the Search template for a custom field of Date/Time type provided by Jira or JMCF, you can search for issues with the custom field value in a given range and use in statistics gadgets by day, week, month, quarter or year, respectively.
Applicable to
This search template is applicable to:
- Date Picker type custom field of Jira
- Date Time Picker type custom field of Jira
- Calculated (Scripted) Date/Time Field of JMCF
- Last Field Value Change Date/Time Field of JMCF
- Transition Date/Time Field of JMCF
- Status entered on Date/Time Field of JMCF
Use cases
Search tickets with a date of resolution less than 2 days ago
Group requests by the Change completion date
Group tickets by Due week
Group tickets by Sprint end date
Exact Text Searcher (Statistics-compatible)
When you select the Exact Text Searcher (Statistics-compatible)
as the Search template for a custom field of text type provided by Jira or JMCF, you can search for issues with the exact text in the custom field value and use it in the statistics gadgets.
Applicable to
This search template is applicable to:
- Text Field (single-line) type custom field of Jira
- Text Field (multi-line) type custom field of Jira
- Calculated (scripted) Text/Html Field of JMCF
- Calculated (scripted) Wiki Text Field of JMCF
- Parent Status Field of JMCF
Use cases
Search for issues of a specific Project Category
Group activities (tickets) by Sponsor (Jira custom single line text field)
Group requests by the time zone of the Reporter
Duration Searchers (Statistics-compatible)
JMCF provides Duration searcher (24x7 durations) and Time Tracking Duration searcher (work time durations). When you select one of these as the Search template for a custom field of duration type provided by JMCF, you can search for issues by duration string and the field can be used in the statistics gadgets.
With the Duration searcher (24x7 durations), durations are treated as calendar durations, where one day is 24 hours and one week is 7 days.
With the Time Tracking Duration searcher (work time durations), durations are treated as work time durations, where the number of hours in a day and the number of days in a week are based on Jira's Time Tracking setting.
In both cases, durations are stored internally as a number of seconds, and will be converted to duration strings according to the selected searcher.
Applicable to
This search template is applicable to:
- Calculated (scripted) Duration Field of JMCF
- Time in Status Field of JMCF
Use cases
Search for issues with time in current status greater than 3 days
Group tickets by the duration they have been Flagged for
Display the aggregate time spent on the stories of the Epic
Configuring a search template for a custom field
Generally, you can configure a search template for a custom field by editing the custom field. Starting from JMCF 2.1, you can configure the Search template for any JMCF custom field from the Configure screen as well. This page offers better:
- Search template selection
- explanation of what the search template does
- description of each Search template
- identification (through theicon) of Statistics-compatible searchers
To modify the search template for a JMCF custom field from the Configure screen:
- Log in to JIRA as an administrator.
- Go to the Administration icon and click on it.
- Click on
Issues - > Custom fields.
- Locate the custom field in the Custom fields administration page and click on the cog wheel.
- Click on
Configure
- Click on
Edit Search Template.
- Select a Search template
- Click on
Save
- Perform a re-index as suggested.
- Note that the selected Search template is a global option for the field. Any change will be applied to all contexts and configuration schemes of this field.
- For a Calculated Duration field, the Search Template also determines how durations are displayed, and how duration strings returned by the formula are parsed.