This page relates to the Cloud version of Rich Filters for Jira Dashboards. Please see the documentation index for Server & Data Center versions.

Customize issue views and gadget scope

This article explains how to use a couple of features provided by Rich Filters for Jira Dashboards to create custom issue displays for multiple purposes or roles. Views allow you to customize the columns displayed when listing issues in Rich Filter Results gadgets. Working queries enable you to refine the scope of individual gadgets by applying a permanent JQL query at the gadget level.


Final result for this tutorial

When you've worked through all the steps in this tutorial, you should have:

  • Two Rich Filter Results gadgets with tabs available to display separate views, each gadget displaying a different set of issues.
  • A Rich Filter Controller gadget containing filters that can be used to filter the issues shown in both results gadgets.

Dashboard showing two results gadgets - Canceled and Not canceled - with a controller gadget with active filters, filtering the results gadgets

Rich filter and dashboard basic setup

In this section, you'll set up a basic rich filter and dashboard to work with.

  1. If you've already worked through other tutorials in this series, you can base any gadgets you create while following this article on a previously-created rich filter. Check that you have one available to use (find existing rich filters under Apps > Rich Filters). If not, follow the instructions in Get started with Rich Filters for Jira Dashboards to create a new rich filter before continuing.
  2. Create a new dashboard (Dashboards > Create dashboard).
  3. Make sure it is using the Two columns layout. This is usually the default setting, but you can select it if required using the Change layout menu at the top of the dashboard.

    Newly created dashboard with Change layout option selected and two columns option highlighted
  4. Add a Rich Filter Results gadget to your dashboard and configure it to be based on your rich filter (Create a simple dashboard explains how to do this).
  5. After saving the configuration of your gadget, move it to the right-hand column of your dashboard by dragging and dropping it.
  6. Click Done to exit dashboard edit mode.

If you want a more detailed explanation of creating a new dashboard, see Create a simple dashboard.

Create a custom view of an issue list

You won't want to see the same columns in your results at all times. For example, a manager might want to see a simplified view for status checking, while two different team members might rely on different sets of fields to do their jobs. You can create a different rich filter view for each purpose.

First of all, let's create a more useful default view to show some issue details along with who reported them.

  1. Go to your rich filter config screen.
  2. Select the Views tab and click Create view in the top-right corner.

    The views config screen, currently with no views added, and with the create view button highlighted in the top right corner

  3. In the resulting dialog box, enter the Name "Requester", then click Create.
  4. In the resulting Requester view config screen:
    1. Add the Issue Type column.
      1. Click the Add a column… dropdown menu.
      2. Start typing "Issue Type" to filter for it in the available options.
      3. Select the Issue Type option that appears to add it to the list.
    2. Add the columns Key, Priority, Summary, Reporter, and Status in the same way as above.

      Config screen for a view called Requester, with 6 columns added - Issue Type, Key, Priority, Summary, Reporter, and Status

  5. Click the Views tab to go back to the main views config screen and you will find your Requester view available there (useful if you want to edit it later on).
  6. To see your new view in your Rich Filter Results gadget, go back to your dashboard and click the Optimized refresh button in the controller.

Add a second view

Now let's add a second view to allow you to look at Jira issues according to their delivery status.

  1. Go back to the Views tab of your rich filter config screen, as before.
  2. Add another view called "Delivery" with the columns Issue Type, Key, Priority, Summary, Assignee, Status, and Resolution.
  3. Go back to your dashboard and refresh it. The Rich Filter Results gadget should now show a separate tab for each view — select them to move between the two.

    A rich filter results gadget showing two different view tabs - requester and delivery

Choose the views to display inside your gadget

You might not want to access all views in all Rich Filter Results gadgets, all of the time. For each results gadget, you can select a particular set of views relevant to its intended use.

To configure this:

  1. Go to your dashboard and click the Edit button at the top-right corner, if the dashboard is not already in edit mode. 
  2. Go to your results gadget and select Configure from the  menu in the top-right corner.

    A rich filter results gadget with the configure menu option highlighted from the three dot menu in the top right corner

  3. In the Views section of the resulting gadget form, you'll see that Show all views is currently selected, hence all the views being shown.

    A rich filter results gadget config view, with the Views options highlighted - show all views and customize shown views

  4. To show only a subset, click the Customize shown views radio button — this will cause an Add a view dropdown to appear. As with other dropdowns in rich filters, you can type in some text to filter the available options before selecting the ones you want.
  5. Select Requester from the dropdown, and then select Delivery. You'll see them both appear in a vertical list.

    A rich filter results gadget config view, with the customize shown views option selected, and two views added to display - requester and delivery

  6. Try dragging and dropping the two views (you can also Tab to a view to focus it, press Space, and then use the up and down cursor keys to adjust its position). Change the order here to change the order in which the view tabs appear in the Rich Filter Results gadget.
  7. Click the trash can icon next to one of the views, and click Submit. You'll see that the gadget now only shows one single view, with no tabs.
  8. Update the config form so that the Rich Filter Results gadget shows both views again.
  9. After saving the configuration of your gadget, click Done to exit dashboard edit mode.

Easier configuration with the Rich filter menu

In the previous section, we showed you how to configure your Rich Filter Results gadget. This was quite an involved process — entering dashboard edit mode, entering the config form for the gadget by selecting Configure from the  menu in the top-right corner, updating your config details, clicking Submit to exit the config, and clicking Done to exit edit mode. Entering and exiting dashboard edit mode both trigger a reload of all your gadgets, which makes it take even longer.

Rich filters provides an easier way to update your config information. In every rich filter gadget, you can click the rich filter four squares icon to access the Rich filter menu.

This menu provides two very useful options for much quicker configuration:

Rich Filter Results gadget with Rich filter menu open at the bottom-left showing options of Configure gadget, Open rich filter config, and Download support file

  • Configure gadget: Opens the config form for that gadget, without having to enter dashboard edit mode.
  • Open rich filter config: Opens the config screen for the rich filter the gadget is based on, in a new tab.

We advise you to use this menu in the future to edit your configs wherever possible (as you'll see later, renaming and gadget color highlighting are currently only available through dashboard edit mode).

Use working queries to limit the scope of displayed issues in rich filter gadgets

It is possible to apply a specific additional JQL query to each rich filter gadget, which will add a permanent filter to the issues processed by the gadget — i.e. the gadget's scope — changing the data displayed in just that gadget. This is a powerful and versatile mechanism for customizing your gadgets. In Rich Filter Results gadgets, this allows you to customize the set of issues shown in each gadget, for different purposes. 

This is called a Working query, edited in the config form for each gadget. In this example, we will create a Rich Filter Results gadget showing canceled issues, and another one showing non-canceled issues.

You can set a working query on any rich filter gadget, with the exception of the Rich Filter Controller and Text Panel gadgets.

Create a "not canceled" results gadget

  1. Open the config form of the Rich Filter Results gadget you already have in your dashboard.
  2. Find the Working query field near the top. This is where your working query JQL goes.
  3. Enter "resolution in (EMPTY, Fixed, Done)". This JQL filtering condition will always be combined (ANDed) with the base JQL filter that feeds the gadget. This gadget will display only issues having no resolution or the resolution Fixed or Done (this is what we consider to mean "not canceled" in this example).

    part of a rich filter results gadget showing a working query entered as described in the above text
  4. Click Submit.
  5. Rename the gadget to "Not canceled" so its purpose is easy to understand. This is done via the Rename option available in the gadget's ... menu, available in dashboard edit mode.

    A rich filter results gadget with the rename menu option highlighted from the three dot menu in the top right corner

The Rich Filter Results gadget will now show only the not canceled issues (i.e. issues with resolution either EMPTY (Unresolved) or Fixed or Done). You'll be able to check this by switching to the Delivery view and looking at the Resolution column.

A rich filter results gadget with a label of not canceled, and two views - Requester and Delivery. Delivery is selected.

We define canceled issues as issues that have a non-empty resolution different from Fixed and Done. Depending on your Jira configuration, you might have different resolutions and conventions.

Create a "canceled" results gadget

  1. Add another Rich Filter Results gadget to your dashboard, based on the same rich filter as the first one.
  2. Make sure it is in the left-hand column; drag and drop it if needed.
  3. Add the working query "resolution not in (EMPTY, Fixed, Done)".
  4. Click Submit.
  5. Rename it to "Canceled"
  6. Give it a different highlight color so that it stands out from the other one. This is done via the HIGHLIGHT COLOR options available in dashboard edit mode, accessed as shown below.

A rich filter results gadget with the highlight color options highlighted from the three dot menu in the top right corner

You should end up with two Rich Filter Results gadgets that look like this:

Two results gadgets labeled canceled and not canceled, showing different issue lists, each with two available views, requester and delivery

Note that Rich Filters for Jira Dashboards also provides a dedicated feature for managing customized lists of issues, specific to Rich Filter Results gadgets. This is called Queues and is covered elsewhere.

If you use the "ORDER BY" clause in a working query, this will take precedence over the "ORDER BY" clause of the base filter, allowing you to customize the default sorting of issues for that gadget.

Further exercises

In order to add further power to the dashboard, in our final example we added a Rich Filter Controller gadget in the left-hand column, above the Canceled results gadget. To complete the tutorial, we'd like you to do the following:

  1. Add a Rich Filter Controller gadget to your dashboard using the Add a Gadget side panel.
  2. Drag and drop it to the top of the left-hand column of the dashboard if it isn't already placed there.
  3. In the controller config form, set the Rich filter to the same rich filter that your other gadgets are based on, and click Submit.

If you are using a rich filter from a previous tutorial, you may already have some filters available on your controller. If you created a fresh new rich filter for this tutorial:

Try applying some filters in the controller — you'll see that both Rich Filter Results gadgets update live to add these extra filtering criteria over the top of the working queries active in each one. Controllers filter the information shown in all the gadgets based on the same rich filter as them.

 Dashboard showing two results gadgets - Canceled and Not canceled - with a controller gadget with active filters, filtering the results gadgets

Next steps

You are advised to work through the Fundamentals articles in order, but each one works as a standalone topic, so you can jump to specific topics of interest if that suits you better.

You can use the rich filter you created in this article as a starting point for other tutorials.