Use custom ratios in your dashboards

Owned by Dan Mihalache
Last updated: May 07, 2024 by Praveena Manohar
13 min read

Rich Filters for Jira Dashboards enables you to define custom ratios. These advanced user-defined ratios provide power and flexibility that can be pre-packaged and used in gauge, statistics, flexi charts, and time series gadgets. When defining a custom ratio, you can specify custom base values, including JQL filter queries for the numerator and denominator, and custom display options for the results, including label, color, and format. This article tells you all you need to know about using custom ratios.

Contents:

Prerequisites

Final result

Once you've followed the steps in this tutorial, you can see your issues, such as completion rate and work ratios, broken down by interesting measures like team, priority, and project.

The dashboard will contain:

  • All the rich filter gadget types that can display issue data based on custom ratios:

    • Rich Filter Simple Gauges gadget

    • Rich Filter Smart Gauges gadget

    • Rich Filter Flexi Charts gadget

    • Rich Filter Statistics gadget

    • Rich Filter Two-Dimensional Statistics gadget

    • Rich Filter Time Series Chart gadget

  • A Rich Filter Controller gadget containing quick filters to refine your dashboard view dynamically.

A Jira dashboard containing a controller, plus six other rich filter gadgets that feature custom ratios

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.

    Jira dashboard edit mode with no gadgets added, and the Change layout left sidebar option highlighted

     

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

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

Custom ratios versus "on the fly" ratios

We’ve already discussed the ratios in the “Use rich filter counters and gauges in your dashboards” page. We define ratios "on the fly" in Rich Filter Simple Gauges and Rich Filter Smart Gauges by selecting a filter for the gauge level and an aggregate value.

Custom ratios are similar in concept to the ratios created on the fly in gauge gadgets, but they provide a lot more power and flexibility:

  • They are created as standalone entities in your rich filter config. After being defined once, they can be reused in multiple places.

  • They can be used in various gadget types, including gauges, statistics, and charts.

  • You can create ratios of a wide variety of different value types.

  • You can specify JQL queries for the ratio level (numerator) and total (denominator).

  • You can set custom display options for the results, including label, color, and format.

Your first custom ratios

Let's create a custom ratio so you can see how they work.

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

  2. Go to the Custom Ratios tab and click Create Custom Ratio.

  3. You'll create a custom ratio of completed story points versus total story points in the resulting dialog box. Enter the following values:

    1. Name: This label for your custom ratio will denote it when you use it inside gadgets. For this example, enter "Completion rate."”

    2. Color: Use the color picker to give your custom ratio a nice green color.

    3. Numerator: This defines the ratio level: the number on the top.

      1. You can choose between Issue Count and numeric and time tracking fields for Base value. You want to define a ratio of story points, so select Story Points

      2. For the numerator's JQL filter, enter "status in (Resolved, Closed)". You define a ratio of resolved/closed story points versus the total number of story points.

    4. Denominator: This defines the ratio total: the number on the bottom.

      1. For Base value, choose the Same as the numerator for this example; we'll see examples of the other choices later. An explanation of the different available choices follows:

        1. The numerator is the same as the denominator, which is obvious; in this case, it will set the base value to Story Points.

        2. A constant, which means the denominator will always be the same, is useful to show progress against a set target.

        3. Another compatible field type. If the numerator and denominator are the same type, you can select different value fields for them. For example, if the numerator is based on story points—a numeric field—then the denominator can be based on story points or any other numeric field.

      2. Leave the denominator's JQL filter blank. In this case, we don't want to add additional filtering for the denominator — we want it to include all the story points.

    5. Display format: This allows you to choose the display format of your ratio. The options are Percentage or Ratio; if you choose Ratio, you'll be shown an additional Decimals field, which allows you to choose several decimal places to show in your ratio with choices ranging from 0 to 3. Leave Percentage selected.

  4. Click Create.

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

Now, we'd like you to create more custom ratios to get more practice and demonstrate some of the other options discussed above.

  1. Work ratio defines a ratio of the time you spent resolving issues versus the original time estimate you gave for resolving those issues. This is very useful for monitoring whether the estimates given are too low or high or investigating inefficiencies in your process that may be increasing the time spent.

    1. Name: "Work ratio". Give it a dark blue color.

    2. Numerator:

      1. Base value: Time Spent.

      2. JQL: Leave blank.

    3. Denominator:

      1. Base value: Original estimate. Here, we are computing a ratio with different base values for the numerator and denominator. The two are both time-tracking fields and are therefore compatible.

      2. JQL: Leave blank.

    4. Display format: Percentage.

  2. Target completion will define a ratio that shows how many story points' worth of issues have been resolved in the previous three months versus a target number. This is useful for showing progress and trends on work targets.

    1. Name: "Target completion". Give it a lighter blue color.

    2. Numerator:

      1. Base value: Story Points.

      2. JQL: Enter "resolutiondate > startOfMonth(-90d)".

    3. Denominator:

      1. Base value: Choose Constant and, in the Type a number field that appears, enter 200. This will be our story point target for three months.

      2. JQL: Leave blank.

    4. Display format: Percentage.

Your Custom Ratios tab should now look like this:

Using custom ratios in a Rich Filter Simple Gauges gadget

Now that you've created these custom ratios, let's use them in the dashboard.

First, you'll use a Rich Filter Simple Gauges gadget to display your Completion rate and Work ratio so you can monitor them at a glance.

  1. Add a Rich Filter Simple Gauges 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 the same rich filter as your controller.

    2. Gauge filters and values: From the Pick a filter dropdown, choose your Completion rate and Work ratio custom ratios.

       

    3. Click Submit. Your Rich Filter Simple Gauges gadget should look like this:

Using custom ratios in a Rich Filter Smart Gauges gadget

Now, you'll create a Rich Filter Smart Gauges gadget that shows how close your teams are to meeting their target completion. Smart gauges are very similar to simple gauges, the difference being that they use a smart filter to provide a custom breakdown rather than being based on individual base values.

  1. First, add a Teams smart filter to your rich filter, as described in Create a Teams smart filter.

  2. Add a Rich Filter Smart Gauges gadget to your dashboard.

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

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

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

    2. Smart filter: Choose your Teams smart filter.

    3. Show None: Make sure this checkbox is unchecked. We are not interested in target completion for issues not assigned to a team.

    4. Computation mode: Select the Use smart clauses as gauge totals radio button.

    5. Gauge filter and value: Choose your Target completion custom ratio.

    6. Click Submit. Your Rich Filter Smart Gauges gadget should look like this:

Using custom ratios in flexi charts

Custom ratios are also usable in Rich Filter Flexi Charts gadgets, providing useful summaries of your ratio breakdowns. In this section, you will create a bar chart showing each assignee's top priority ratio. The top priority ratio shows the ratio of highest and high priority issues. It is useful to know the percentage of top-priority issues that are assigned to each team member — ideally, you want the high-priority issues shared out evenly so that no one team member is put under too much pressure and you don't end up with a single point of failure.

First, let's create the Top priority ratio:

  1. Return to your rich filter config, and open the Custom ratios tab.

  2. Create a new custom ratio as follows:

    1. Name: "Top priority ratio". Give it an orange color.

    2. Numerator:

      1. Base value: Issue Count.

      2. JQL: Enter "priority in (Highest, High)".

    3. Denominator:

      1. Base value: Choose the same as the numerator.

      2. JQL: Leave blank.

    4. Display format: Percentage.

Now for the flexi chart:

  1. Go back to your dashboard and add a Rich Filter Flexi Charts gadget.

  2. Move the gadget to the bottom of the left-hand column by dragging and dropping it.

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

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

    2. Chart type: Select Bar.

    3. Breakdown by:

      1. Statistic type: Choose Assignee.

      2. Sort by: Select Total.

    4. Value: Choose your Top priority ratio custom ratio.

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

Displaying custom ratios in statistics

You can also display custom ratios broken down into one or two dimensions in rich filter statistics gadgets.

First, you'll create a one-dimensional breakdown of your Completion rate, Work ratio, and Target completion custom ratios by Priority. This is useful for verifying that your teams are prioritizing higher-priority work over lower-priority work, checking that the work ratio is not too high, and seeing what priority work contributes most towards the completion target.

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

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

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

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

    2. Breakdown by > Statistic type: Choose Priority.

    3. Values: Select your Completion rate, Work ratio, and Target completion custom ratios.

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

Now, let's look at a two-dimensional breakdown example. Here, you'll create a statistics table that breaks down the Work ratio by both Project and Priority.

  1. Add a Rich Filter Two-Dimensional Statistics gadget to your dashboard.

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

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

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

    2. Working query: In this example, we want you to display this metric for a subset of available projects only; to filter for these, you'll use a working query (see Customize issue views and gadget scope for more information). Enter JQL similar to "project in ("Fox Service Desk", "Raven Service Desk", "Seal Service Desk")". We chose service desk projects in our case, but you can choose different projects that are appropriate for your data.

    3. Horizontal breakdown > Statistic type: Choose Project.

    4. Vertical breakdown > Statistic type: Choose Priority.

    5. Value: Select your Work ratio custom ratio.

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

Custom ratios in time series

Finally, for this article, we wanted to show you that custom ratios can be used in time series (see Display date/time statistics and charts on your dashboard for more information about time series). This particularly useful combination allows you to see how a ratio evolves over time.

Let's demonstrate with an example. You are going to create three different time series, then display them in a Rich Filter Time Series Chart gadget:

  • Work ratio: This uses the Work ratio custom ratio as the base value, showing how the time spent completing work matches the original estimates for that work. The time series is based on Resolved, showing the work ratio of resolved issues over several aggregation periods. Ideally, the work ratio should stay near 100%; otherwise, there is a problem with your estimations, or your process is inefficient in some way.

  • Top priority ratio: This uses the Top priority ratio custom ratio as the base value, which shows the ratio of issues that are the highest and highest priority. The time series is based on Created, so it shows the top priority ratio of created issues over several aggregation periods. Ideally, this should stay consistent and at an acceptable level; otherwise, your prioritization needs to be adjusted.

  • Due completion rate: This uses the Completion rate custom ratio as the base value, showing the completed story point ratio. The time series is based on the Due date, so it shows the rate of issues due in each aggregation period that are completed. Ideally, this should stay at 100%; otherwise, some work was not completed by its due date and is overdue.

Let's begin by creating the required time series:

  1. Go back to your rich filter config and open the Time series tab.

  2. Create the following time series:

    1. Work ratio:

      1. Name: "Work ratio"; give it a mid-blue color.

      2. Series: Choose Resolved.

      3. Base value: Select your Work ratio custom ratio.

      4. JQL: Leave blank.

    2. Top priority ratio:

      1. Name: "Top priority ratio"; color it orange.

      2. Series: Choose Created.

      3. Base value: Select your Top priority ratio custom ratio.

      4. JQL: Leave blank.

    3. Due completion rate:

      1. Name: "Due completion rate"; color it pink.

      2. Series: Choose the Due date.

      3. Base value: Select your Completion rate custom ratio.

      4. JQL: Leave blank.

  3. Your Time series tab should look like the following. Check that it is correct before moving on.

Now, let's display them in a time series chart:

  1. Return to your dashboard and add a Rich Filter Time Series Chart gadget.

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

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

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

    2. Aggregation periods: Select Weeks.

    3. Time range: Select the Number of weeks.

    4. Number: Enter 12.

    5. Direction: Select Past.

    6. Aggregation type: Choose Cumulative total. This ensures that the ratio shown for each aggregation period is the average and all that came before it, not only the individual period.

    7. Time series: Add your Work ratio, Due completion rate, and Top priority ratio time series to the list using the Pick a time series... dropdown.

  4. Click Submit. Your Rich Filter Time Series Chart gadget should look like this:

In general, these trends look healthy, except for the due completion rate, which is starting to trend downward, indicating that some issues were not completed on time and are overdue.

Further exercises

To complete this tutorial, we'd like you to create some quick filters to provide additional interactive filtering of the issues shown in your gadgets. Your controller will already display the Teams smart filter you created earlier. Now you should:

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

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

Remember that applying a quick filter in your controller will filter all gadgets based on the same rich filter as the controller. For example, the image below shows part of a Jira dashboard with three rich filter gadgets, all being filtered by active quick filters in the controller. The dashboard is being filtered by Assignee and Priority.