Versions Compared

Old Version 36

changes.mady.by.user Radhika Vijji.

Saved on

compared with

New Version 37

changes.mady.by.user David Fischer (Appfire)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Introduction

Searchers are optionally configurable devices of (also known as Search templates) are assigned to custom fields (both Standard and Advanced) that to control how you can search for issues with a given value in the field either in the Issue Navigator or when used in a gadget on the dashboard. Searching 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.


Panel

On this page:

Table of Contents
maxLevel2


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, it does not provide searchers that are 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. JMCF handles this limitation effortlesslyAll JMCF searchers support statistics.


Tip

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

of

provided by JMCF

add-on

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.

Panel
titleTwo-dimensional gadget displaying the issues due


Panel
titlePie-chart displaying the duration of issues in "In Progress" status

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 the statistics gadgets.

Applicable to

This search template is applicable to:

Use cases

  • Search Epics with Story points (of all Stories) greater than 50

    Expand
    titleSteps


    Panel
    • Create a Calculated (Scripted) Number custom field type, Total Story Points.
    • Click on Configure for the custom field in the Custom Fields administration page.

    • Click on Edit Groovy Formula and write the following formula.

      Code Block
      def totalSP = 0
issue.stories.each{
  totalSP += it.get("Story Points")
}
return totalSP


    • Click on Save.
    • Perform a re-index as suggested.



  • Group tickets by Business value (Jira custom number field)

    Expand
    titleSteps


    Panel
    • Click on Configure for the Business Value field in the Custom Fields administration page.

    • Change the Search Template to Number range searcher (statistics-compatible).

    • Click on Save.

    • Perform a re-index as suggested.
    • On the dashboard configure a Pie-chart with Business Value as the statistics type.



  • Group

    Epic

    Epics by number of Story Points of all stories

    associated to

    in the Epic

    Expand
    titleSteps


    Panel
    • Click on Configure for the Story Points in the Custom Fields administration page.

    • Change the Search Template to Number range searcher (statistics-compatible).

    • Click on Save.

    • Perform a re-index as suggested.
    • On the dashboard configure a two-dimensional gadget with Story points and Epic link as the dimensions and grouping by Epic link.



  • Group tickets by code fix rejection count

    Expand
    titleSteps


    Panel
    • Create a Calculated (Scripted) Number custom field type custom field, Fix rejected
    • Click on Configure for the custom field in the Custom Fields administration page.
    • Input the transition name Reject in the Transition field.
    • Click on Save.
    • Perform a re-index as suggested.
    • On the dashboard configure a two-dimensional gadget with Fix rejected and Developer of the issue as the dimensions, grouping by Fix rejected.



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 and or year, respectively. 

Applicable to

This search template is applicable to:

Use cases

  • Search tickets with

    the

    a date of resolution less than 2 days ago

    Expand
    titleSteps


    Panel

    • Create a Calculated (Scripted) Date/Time custom field type type custom field, resolvedInResolved On.

    • Click on Configure for the custom field in the Custom fields administration page.

    • Click on Edit Groovy Formula and write the following formula:

      Code Block
      issue.get("resolutiondate")


    • Click on Save
    • Change the Search Template to Date range searcher (Statistics by month).
    • Perform a re-index as suggested.



  • Group requests by the Change completion date

    Expand
    titleSteps


    Panel
    • Click on Edit for the Change completion date field in the Custom Fields administration page.
    • Perform a re-index as suggested.
    • On the dashboard configure a Pie chart with Change completion date as the Statistic type.



  • Group tickets

    due each

    by Due week

    Expand
    titleSteps


    Panel

    • Create a Calculated (Scripted) Date/Time custom field type, Due.

    • Click on Configure for the custom field in the Custom fields administration page.

    • Click on Edit Groovy Formula and write the following formula:

      Code Block
      issue.get("duedate")


    • Click on Save.
    • Change the Search Template to Date range searcher (Statistics by week).
    • Perform a re-index as suggested.
    • On the dashboard configure a Pie chart with Due as the Statistic type.



  • Group tickets by Sprint end date

    Expand
    titleSteps


    Panel

    • Create a Calculated (Scripted) Date/Time custom field type, "Sprint End Date".

    • Click on Configure for the custom field in the Custom Fields administration page.

    • Click on Edit Groovy Formula and write the following formula

      Code Block
      for (Object sprint : issue.get("Sprint")) {
  if (sprint.isActive())
    return sprint.getEndDate().toDate();
}


    • Click on Save
    • Perform a re-index as suggested.
    • On the dashboard configure a two-dimensional gadget with Sprint End Date and Sprint as the dimensions, grouping 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. For example: 

Search for issues of a specific Project Category

  • Group activities (tickets) by Sponsors (Jira custom single line text field)

  • Group requests by the help-desk the Reporter belongs to
  • Group requests by the time zone of the Reporter

    • Applicable to

    This search template is applicable to:

    Use cases

    • Search for issues of a specific Project Category

      Expand
      titleSteps


      Panel

      • Create a Calculated (scripted) Text/Html custom field type, Project category.

      • Click on Configure for the field in the Custom Fields administration page.

      • Click on Edit Groovy Formula and write the following formula.

        Code Block
        issue.get("project")?.projectCategory?.name


      • Perform a re-index as suggested.



    • Group activities (tickets) by

      Sponsors

      Sponsor (Jira custom single line text field)

      Expand
      titleSteps


      Panel

      • Create a Jira single-line text field, Sponsor.

      • Click on Edit for the field in the Custom Fields administration page.
      • Change the Search Template to Exact text searcher (Statistics compatible).
      • Perform a re-index as suggested.
      • On the dashboard configure a Pie chart with Sponsor as the Statistic type.



    • Group requests by the time zone of the Reporter

      Expand
      titleSteps


      Panel

      • Create a Calculated (scripted) Text/Html custom field type, TimeZone.

      • Click on Configure for the field in the Custom Fields administration page.

      • Click on Edit Groovy Formula and write the following formula.

        Code Block
        import com.atlassian.jira.timezone.TimeZoneManager
// access timeZone of the reporter
def userTimeZone = getComponent(TimeZoneManager).getTimeZoneforUser(issue.reporter).getID()


      • Perform a re-index as suggested.
      • On the dashboard configure a Pie chart with TimeZone as the Statistic type.

      Group tickets by the help-desk the Reporter belongs to

      Expand
      titleSteps
      if(!issue.assignee) return null; userUtil = ComponentAccessor.getUserUtil(); groups = userUtil.getGroupsForUser(issue.assignee.name); groups?.first()?.name
    • Perform a re-index as suggested.
    • On the dashboard configure a Two-dimensional gadget with Project and Help-desk fields as the dimensions grouping by Help-desk
      • Panel
      Code Block



    Duration Searchers (Statistics-compatible)

    JMCF provides Duration searcher (24x7 durations) and Time Tracking Duration (Time Tracking Formatsearcher (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 with the custom field value with the 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:

    Use cases

    • Search for issues with time in current status greater than 3 days

      Expand
      titleSteps


      Panel

      • Create a Time in status field, "TimeInCurrentStatus"

      • Click on Configure for the field in the Custom Fields administration page.
      • Select the status as "Current Status" under Status(es)
      • Save the configuration.
      • Select the Duration searcher (24x7 durations)
      • Perform a re-index as suggested.



    • Group tickets by the duration they have been Flagged for

      Expand
      titleSteps


      Panel

      • Create a Calculated (Scripted) Duration custom field type, Flagged since

      • Click on Configure for the field in the Custom Fields administration page.

      • Click on Edit Groovy formula and write the following formula.

        Code Block
        if(issue.get("Flagged")){
  return (new Date().getTime() - issue.getFieldHistory("Flagged").last().created.getTime())/1000L
}
else{
  return null
}


      • Click on Save.
      • Select the Duration searcher (24x7 durations)
      • Perform a re-index as suggested.
      • On the dashboard configure a Pie chart with Flagged since as the Statistic type.



    Configuring a search template

    to

    for a custom field

    Generally, you can configure a search template for a custom field of Jira (not Locked) and JMCF by 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:

    1. Log in to JIRA as an administrator.
    2. Go to the Administration icon  and click on it.
    3. Click on Issues - > Custom fields.
    4. Locate the custom field in the Custom fields administration page and click on the cog wheel.
    5. Click on Configure
    6. Click on Edit Search Template.
    7. Select a Search template
    8. Click on Save
    9. Perform a re-index as suggested.


    Note
    • 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.