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.

Prerequisites

• A basic understanding of Jira dashboards and rich filters, as explained in Get started with Rich Filters for Jira Dashboards.
  
• A basic understanding of Jira Query Language (JQL). 

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.

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

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

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.
   
   
   
   
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.
   
   
   
   
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.
   
   
   
   
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  icon to access the Rich filter menu.

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

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

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).
   
   
   
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.
   
   
   

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.

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.

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

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 creating some static filters, as shown in Add some static filters to your controller.
• Try creating some dynamic filters. You can find out how in Enhance your Jira dashboards with dynamic filters.

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.

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.