Documentation for JIRA 4.0. Documentation for other versions of JIRA is available too.

Skip to end of metadata
Go to start of metadata

How to create a custom preset filter

This 'how to' guide will demonstrate how to create your very own custom preset filter using the Web UI plugin module.

Firstly a preset filter is a link to the JIRA issue navigator with pre-defined filter attributes. These links appear on Browse Project page and on the project portlets.

Creating a new preset-filter is easy and simple to add to your JIRA plugins. All you need to do is define a new web-item module in your atlassian-plugin.xml with the section attribute set to 'system.preset.filters'. JIRA will automatically add a new filter link to both the browse project page and the project portlets. The following web-item template is the minimal required to create a preset filter. (Please refer to the Web UI Plugin Module for further details on defining a web-item such as restricting when the filter is available)

The above attribute values (enclosed in '[' and ']') are explained in Web UI Plugin Module. The main challenge of making a preset filter is generating the [FILTER_URL]. For example the following relative URL repesents the standard JIRA preset filter Outstanding

This may seem cryptic or cumbersome to create/modify manually and require you to know exactly what the field and its values are. The best approach to generating these links is to use the Issue Navigator to filter the issues as normal. Once you have finished filtering the issues, you simply copy the link provided by the permlink (by right clicking on it and copying the links target, this may depend on the browser you are using).

Step by Step Example: 'All closed issues in current project'

This example will demonstrate how to create a new preset filter called Closed which finds all issues in Closed status for a given project.

  1. Start off with the minimal web-item module defined above
  2. Change the attribute values to desired values (excluding the [FILTER_URL] for now)
  3. Now to generate the filter url
    1. Goto the Issue Navigator and set the following search fields as follows:
      • Project: select any one single project (this is to get the fields id)
      • Status: Closed
        then click on View (or View & Hide) button
    2. Right click on the permlink and copy its target link (You can also click on the permlink and copy from the address bar) to get the absolute URL. You should get something like the following:
    3. We will need to escape reserved characters such as the ampersand '&' with '&'
    4. (Optional) To make your preset-filter work on any JIRA instance (different host/context path), it is better to make the absolute URL from the previous step into a relative one. This step involves simply removing everything before /secure/IssueNavigator.jspa.
      The relative URL would be:
    5. This URL will give us the closed issues for the project with the id 10000. To make this dynamic we replace 10000 with $helper.project.id which will get the current project's id (please refer to Web UI Plugin Module for further details). So our final [FILTER_URL] is given by:
  4. The final web-item would look something like this:
Icon

There are more attributes and elements that can be defined for the web-item module to provide additional features such as internationalisation and ordering of the filters. Please refer to the Web UI plugin module for details

You can now just add that to your atlassian-plugin.xml and it will appear on both the Browse Project page and on the project portlets as follows:

Compiling and installing the preset filter as a plugin in JIRA

The above steps showed how to make a single plugin module, this however is not the complete plugin. A JIRA plugin is a single JAR (Java ARchive) file with atleast a plugin descriptor (an XML file called atlassian-plugin.xml). This XML file includes one or more of the plugin module's and contains additional information specifying the overall plugin's details such as its name, description, version, etc'.

  1. The following sample can be used as a template to create the atlassian-plugin.xml file.
    Modifying the attributes of the template and adding the preset filter plugin module where marked, the final file will look like the attached: atlassian-plugin.xml.
  2. Now the atlassian-plugin.xml needs to be packaged as a single JAR file. There are various ways of doing this, two simple ways are:
    • In a command line with jar installed, run the following command (with atlassian-plugin.xml in the current directory):
      OR
    • Add the atlassian-plugin.xml file to a ZIP file (eg. using WinZip/WinRAR), then rename the ZIP file with a .jar extension (ie. rename file.zip to file.jar)
      The final jar file should look something like preset-filter-example-plugin.jar
  3. To install the JAR file:
    1. Shut down JIRA
    2. copy the jar file into '.../atlassian-jira/WEB-INF/lib/'
    3. Start up JIRA.
    4. Go to 'Administration > Plugins' and confirm that the plugin is listed and enabled (look for the name specified in atlassian-plugin.xml - eg. Sample Plugin).
    5. Enjoy!
Icon

Please note that the steps outlined above are only valid for packaging basic plugins such as the preset filters. For a more comprehensive plugin, you may need to include additional resources. Please refer to the JIRA Plugin Guide and Setting up your plugin project​ for more details.

Icon

You can get a full sample plugin from the Jira Plugin Development Kit which extends the web-item defined above by internationalising it and placing the 'Closed' link under the 'All' filter.

  • No labels