Use custom values in your dashboards

Rich Filters for Jira Dashboards allow you to define custom values—advanced user-defined values that can be used in rich filter gadgets. They can use custom formulas (sum, average, minimum, and maximum) when aggregating values, custom display options for the results, including label, color, and format, and JQL for further filtering. Custom values are available as columns in views and values in gadgets alongside Jira fields. 

Contents:

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

Once you've worked through the steps in this tutorial, you should have a dashboard that contains five rich filter gadgets:

• A Rich Filter Controller gadget will provide interactive filtering on your dashboard.

• A Rich Filter Simple Counters Gadget to sum custom values.

• A Rich Filter Flexi Charts gadget based on custom values.

• A Rich Filter Statistics gadget based on custom values.

• A Rich Filter Results gadget showing custom value-based columns in action.

Open

Rich filter and dashboard basic setup

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

1. If you've already worked through other tutorials in our Learning Center, you can base any gadgets you create while following this article on a previously created rich filter. Check that you have one available (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 uses the left sidebar layout. You can set this using the Change layout menu at the top of the dashboard.
   
   

   Open

   

4. Based on your rich filter, add a Rich Filter Controller gadget to your dashboard (See also: Create a simple dashboard).

5. After saving the configuration of your gadgets, make sure the controller is in the left column; you can drag and drop it if necessary.

Your first custom value

Let's start by creating a custom value based on a time-tracking field. You'll create one called "Time Spent (h)" that sums the total time spent working on your issues based on the Time Spent Jira field, which has:

• A custom label and color.

• Custom formatting in hours (many people want an option to change Jira's default time formatting).

To do this:

1. Go back to your rich filter config and select the Custom Values tab.
   
   

2. Click Create Custom Value.

3. In the resulting dialog box, enter the following values:

   1. Name: "Time Spent (h)". Also, select a custom color from the color picker to the left of the entered name value. We've chosen orange.

   2. Base value: This is the Jira field on which you are basing your custom value. Select Time Spent from the dropdown.

   3. Total formula: This is used to calculate the totals shown when aggregating this custom value in gadgets (for example, the values shown in statistics and charts). Select Sum total — we want to show the total number of hours.

   4. Time display format: This gives you options for displaying time tracking fields in days, hours, minutes, or seconds, in addition to Jira's display format. Select Hours.

4. Click Create.

At this point, your Custom Values tab should display a summary of your created custom values. You can edit or delete it using the pen and trash can buttons at the right-hand end of the row.

Numeric custom values

Now, let's look at a numeric custom value; here, you'll create a "Resolved Story Points" value based on the Story Points Jira field. This value uses a JQL query to provide the necessary filtering right inside the custom value itself.

1. Create a new custom value with the following configuration values:

   1. Name: "Resolved Story Points". Give it a green color.

   2. Base value: Select Story Points from the dropdown.

   3. Total formula: Select Sum total.

   4. Decimals: This allows you to choose between showing no decimal portion in your values, a maximum number of decimal places, or an exact number of decimal places (with trailing zeros if required). Leave this at the default value.

   5. JQL: This is where you can enter a JQL query to filter the issues to which this custom value applies. Since we want to show resolved story points, this custom value should apply only to resolved issues. To achieve this, insert "resolution is not EMPTY" into this field.

2. Click Create.

Display your custom value totals in counters and statistics gadgets.

Now you've created some custom values, you need to use them somewhere.

First, you'll use a Rich Filter Simple Counters gadget to display useful totals.

1. Add a Rich Filter Simple Counters gadget to your dashboard (See also: Create a simple dashboard).

2. If required, move the gadget to just below your controller gadget by dragging and dropping it.

3. Configure the following fields in the gadget config form:

   1. Rich filter: Set this to your rich filter.

   2. Values: From the Pick a value... dropdown, select the Jira Issue Count value and your custom Time Spent (h) and Resolved Story Points values.
      
      

4. Click Submit. Your Rich Filter Simple Counters gadget should look like this:

Now, let's use a Rich Filter Statistics gadget to break down the same data further and show each assignee's custom values.

1. Add a Rich Filter Statistics gadget to your dashboard.

2. Move the gadget to the right-hand column by dragging and dropping it.

3. There are several fields you should configure in the gadget config form:

   1. Rich filter: Set this to the same rich filter as your other gadgets.

   2. Breakdown by > Statistic type:  Select Assignee from the dropdown.

   3. Values: Again, select Issue Count value, Time Spent (h), and Resolved Story Points.
      
      

4. Click Submit. Your Rich Filter Statistics gadget should look like this:
   
   

Before we move on, let's briefly consider what we just did. We defined a notion of "Time Spent (h)" and started using that instead of the native Time Spent field. This is preferable because it provides a custom time display in hours and a custom label and color. We then defined a notion of "Resolved Story Points" that provided a useful filter on top of the native Story Points field and used that in our gadgets.

This has started to give you a glimpse into the power of custom values — you can define a custom value to suit your needs and then use it everywhere. And you can do all this without being a Jira administrator. Let's continue.

Duration-based custom values

Let's explore creating more advanced custom values based on computed durations provided by rich filters. We'll create new custom values based on the calculated duration value of the Issue age / resolution time. Issue age / resolution time brings two closely related values together in one. If an issue isn't resolved, the value will be Issue Age — i.e., the time that has passed since the issue was created. If it is resolved, the age will stop increasing on the resolution date, and the value will become a static resolution time value — i.e., the time between the created date and the resolution date.

We'll now create two new custom values based on Issue age/resolution time:

• Age will contain the age of issues, whether they have been resolved or not. You'll display this in a Rich Filter Results gadget view later on.

• The Average Resolution Time will contain the resolution time of issues; hence, it will only be shown for resolved issues. This can display each assignee’s average issue resolution time in your Rich Filter Statistics gadget.

Let's do this:

1. Go back to your rich filter config's Custom Values tab.

2. Create a new custom value with the following configuration values (as illustrated in the picture above):

   1. Name: "Age". Give it a blue color.

   2. Base value: Select Issue age / resolution time.

   3. Total formula: Select Average Value.

   4. Duration display format: Select Days.

3. Create another custom value with the following configuration values:

   1. Name: "Avg Resolution Time". Give it a gray color.

   2. Base value: Select Issue age / resolution time.

   3. Total formula: Select Average Value.

   4. Duration display format: Select Days.

   5. JQL: Insert "resolution is not EMPTY" — we want this custom value to apply only to resolved issues.

4. Your Custom Values tab should now look like this. Check it before moving on:
   
   

Add Avg Resolution Time to your statistics

1. On your dashboard, open your Rich Filter Statistics gadget config form (as described in Easier configuration with the Rich filter menu).

2. Add your new Avg Resolution Time value in the Values section and click Submit.

3. Your Rich Filter Statistics gadget should now look like this:
   
   

Now, the gadget also shows the average resolution time for each assignee. In this case, the percentage bar is not displayed — it does not make sense for values using the average aggregation formula.

Display custom values in a results gadget.

In a Rich Filter Results gadget, let's display some custom values as columns.

To be able to do that, you'll first need to set up a View to display those columns.

1. Open your rich filter config (described in Easier configuration with the Rich filter menu).

2. Select the Views tab.

3. Add a view called "Delivery status check."

4. Inside the Delivery status check, add the columns Issue Type, Key, Priority, Summary, Assignee, Time Spent (h), Status, Resolution, and Age. We've chosen custom values that make sense to display in Rich Filter Results gadget columns.

5. Turn your attention to the Show totals row toggle switch above the columns list. Click the toggle to turn this on. A Rich Filter Results gadget will now display this view with a Total row at the bottom containing the totals for all the value columns in the view, including the custom value columns.

Your Delivery status check config should look like this:

Now it's time to show your new view inside a Rich Filter Results gadget.

1. Add a Rich Filter Results gadget to your dashboard.

2. Move the gadget to the right-hand column below the Rich Filter Statistics gadget by dragging and dropping it.

3. In the gadget config form, set the Rich filter to the same rich filter as your other gadgets, and click Submit. Your Rich Filter Results gadget should look like so:
   
   

Have a look at the columns based on your custom values. Note the Total row, which displays totals for your custom values calculated according to the Total formula setting you specified for each one.

Create a custom value based on a custom duration

Now, we will create a Due In custom value that shows how far away the deadline for each issue is. This will be based on Custom duration, a special advanced base value that allows you to select a start and an end time/date from a list of options (including the current time), with the final value being the computed duration between the two.

Let's look at how this works:

1. Go back to your rich filter config's Custom Values tab.

2. Create another custom value with the following configuration values:

   1. Name: "Due In". Give it a red color.

   2. Base value: Select Custom duration from the dropdown. This causes two additional dropdown fields to appear to allow you to specify your start and end values:
      
      

      1. Start: Select Current time.

      2. End: Select Due date.

   3. Total formula: Select Minimum value. When aggregating this custom value on multiple issues, we'd like to see the one due next: the minimum Due In value.

   4. Duration display format: For the chosen Start and End values, this field is fixed at Days—non-fractional.

   5. JQL: Insert "resolution is EMPTY." It makes no sense to show Due In values for issues that have been resolved.
      
      

3. Go back to your rich filter config's Views tab.

4. In the Delivery status check view, add a new Due In column and drag and drop it between the Summary and Assignee columns.

5. Go back to your dashboard and refresh it. You should see your Due In column in action:
   
   

The Total row value for Due In is particularly interesting. Because you selected the Minimum Value for the Total formula, this is a useful signal of when the next task is due for completion.

Further exercises

To complete this tutorial, we'd like you to create a bar flexi chart that shows the Avg Resolution Time for each Priority.

Your finished chart should look something like this:

We'd also recommend that you add some filters to your controller to provide additional interactive filtering of the issues shown in your gadgets:

1. Add static filters as described in Get Started with Rich Filters for Jira Dashboards.

2. Add dynamic filters as described in Enhance your Jira dashboards with dynamic filters.

3. Add a Teams smart filter as described in Create a Teams smart filter.

4. Update your previous flexi chart to use your new smart filter as the Statistic type. This will allow you to display the Average Resolution Time by Team.