Qotilabs

Documentation

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

Use custom ratios in your dashboards

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

Prerequisites

Final result for this tutorial

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

  • Examples of 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 dynamically refine your dashboard view.

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 to work with.

  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 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 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. Add a Rich Filter Controller gadget to your dashboard based on your rich filter (Create a simple dashboard explains how to do this).
  5. After saving the configuration of your gadgets, make sure the controller is in the left column; drag and drop it if required.

Custom ratios versus "on the fly" ratios

We already touched on the topic of ratios in Use rich filter counters and gauges in your dashboards. In that article 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 a value to aggregate on.


A Rich Filter Simple Gauges gadget showing ratios of resolved issues to all issues, and resolved story points to all story points


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 several different 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 both 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 (as described in Easier configuration with the Rich filter menu).
  2. Go to the Custom ratios tab and click Create custom ratio.


    A rich filter config screen showing the custom ratios tab, with no custom ratios currently added. The Create custom ratio button is highlighted

  3. In the resulting dialog box, you'll create a custom ratio of completed story points versus total story points. Enter the following values:
    1. Name: This is the label for your custom ratio that will be used to 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. For Base value, you can choose between Issue Count, and numeric and time tracking fields. 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 are defining 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 Same as numerator for this example; we'll see examples of the other choices later on. An explanation of the different available choices follows:
        1. Same as numerator, which is obvious; in this case it will set the base value to Story Points.
        2. Constant, which means the denominator will always be the same number, useful if you want to show progress against a set target.

        3. Another compatible field type. You can select different value fields for the numerator and denominator as long as they are of the same type. 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. For the denominator's JQL filter, leave it blank. In this case, we don't want to add any 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 a number of decimal places to show in your ratio with choices ranging from 0 to 3. Leave Percentage selected.


      Create a custom ratio dialog box showing Numerator and Denominator base value filled in as Story Points, and a Numerator JQL query to filter by resolved and closed status

  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 a couple more custom ratios to get some more practice in and demonstrate some of the other options discussed above.

  1. Work ratio will define 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 causing an increase in 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 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:


A rich filter config screen showing the custom ratios tab, with three custom ratios added - Completion rate, Work ratio, and Target completion

Using custom ratios in a Rich Filter Simple Gauges gadget

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

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 (Create a simple dashboard explains how to add gadgets).
  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.


      Rich Filter Simple Gauges gadget config showing two gauge filters selected, Completion rate and Work ratio

    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 each of your teams is 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 of all, 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.


      Rich Filter Simple Gauges gadget config showing the Show None checkbox uncheccked, Use smart clauses and gauge totals computation mode selected, and Target completion gauge filter selected

    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 that shows the top priority ratio for each assignee. The top priority ratio shows the ratio of issues that are highest and high priority. 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. Go back 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 Same as 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 to it.
  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.

      Rich Filter Flexi Charts gadget config showing Bar selected as the chart type, Assignee as the Statistic type, and Top priority ratio as the Value

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


    Rich Filter Flexi Chart bar graph showing the Top priority ratio for each Assignee

Displaying custom ratios in statistics

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

First of all, you'll create a one-dimensional breakdown of your Completion rate, Work ratio, and Target completion custom ratios by Priority. This is useful to verify that your teams are prioritizing higher-priority work over lower-priority work, check that the work ratio is not too high, and see 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.


      Rich Filter Statistics gadget config showing a Statistic type of Priority filled in, and values of Completion rate, Work ratio, and Target completion

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


    Rich Filter Statistics gadget showing completion rates, work ratios, and target completion for each different priority

Now let's look at a two-dimensional breakdown example — here you'll create a statistics table that breaks down 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")". In our case we chose service desk projects, but you can choose different projects as 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.


      Rich Filter Two Dimensional Statistics gadget config showing a working query filled in that filters by three different projects, project and priority statistic types selected, and Work ratio value

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


    Rich Filter Two Dimensional Statistics gadget showing a breakdown of Work ratio by project and priority

Custom ratios in time series

Finally for this article, we wanted to show you that it is possible to use custom ratios in time series (see Display date/time statistics and charts on your dashboard for more information about time series). This is a particularly useful combination that 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, which shows how the time spent completing work matches up to the original estimates for that work. The time series is based on Resolved, so it is 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 highest and high priority. The time series is based on Created, so it is showing the top priority ratio of created issues over several aggregation periods. Ideally, this should stay consistent and at an acceptable level, otherwise there is something wrong with your prioritization.
  • Due completion rate: This uses the Completion rate custom ratio as the base value, which shows the ratio of completed story points. The time series is based on Due date, so it is showing the rate of issues that were 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 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.

    Rich filter config time series tab, showing three time series - Work ratio, Top priority ratio, and Due completion rate

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

  1. Go back to your dashboard and add a Rich Filter Time Series Chart gadget to it.
  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 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 for that period 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.


      Rich filter time series gadget config showing the following sections - 12 weeks in the past for aggregation periods, Cumulative total aggregation type, and Work ratio, Due completion rate, and Top priority ratio Time series

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


    Rich Filter Time Series gadget showing the trend of Work ratio, Due completion rate, and Top priority ratio, over a 12 week period

In general, these trends are looking healthy, with the exception of Due completion rate — this 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 below image 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.


Jira dashboard showing Rich filter simple gauges, statistics, and two-dimensional statistics being filtered by quick filters in a controller