Configuring Custom Values
Contents:
About Custom Values
Custom values are user-defined outputs used in rich filter gadgets and time series, just like the built-in values. The custom values add new options for value display (label, color, formatting) and support for total formulas (sum, average, min, max). They can be based on issue count, numeric & time tracking field values, or computed duration (resolution time & issue age). Also, the scope of the custom values can be further refined using JQL sub-queries.
Find below an example of a Rich Filter Statistics gadget that shows, for each issue type, the following custom values: the sum of the story points of the resolved issues, the sum of the time spent for support issues, the average time spent (displayed in hours), the average resolution time and the maximum issue age.
Adding New Custom Values & Custom Values' Key Attributes
You can add new and see existing custom values and their key attributes in the Custom Values section of your rich filter.
To define new custom values, click the Add custom value button at the top-right of the page. The Add a custom value dialog will be displayed.
The key attributes of a custom value are:
Attribute | Description |
|---|---|
Label | The label is mandatory. It is used to identify and display custom values in rich filter gadgets and time series. |
Color | Optionally, you can set a custom color to display the value in some rich filter gadgets. |
Base value | Select the value on which your custom value is based. Your custom value can be based on:
|
Value type | The value type is automatically computed based on the Base value you have chosen. The value type helps you to easily understand the compatibility with Time Series (see Using Custom Values in Time Series below). The possible value types are:
|
Total formula | The total formula is used when displaying totals for the custom values. Possible options are sum, average, minimum, and maximum values. |
Decimals | The number of decimals to be displayed when formatting numeric values: Maximum 3, Maximum 2, Maximum 1, None, Exactly 3, Exactly 2, Exactly 1. What's the difference between maximum 2 and exactly 2 decimals? If you select the exactly 2 option the value will always be displayed with 2 decimals. This is achieved by rounding to 2 decimals if more than 2 are available (e.g., 23.4567 → 23.46) or padding with zeros up to a total of 2 decimals if fewer than 2 are available (e.g., 23.4 → 23.40). Selecting the maximum 2 option will display the value with 0, 1, or 2 decimals. This is achieved by rounding to 2 decimals if more than 2 are available (e.g. 23.4567 → 23.46) and leaving the value as it is if 2 or fewer decimals are available (e.g., 23.4 → 23.4). |
Show thousands separator | If this checkbox is checked, the numeric values are displayed using a thousand separator (based on the user's locale). |
Value display | This setting allows you to choose how to display time-tracking values. The available options are:
|
JQL filter | You can optionally use a query to restrict the definition of this custom value to only a subset of issues. The custom value will be empty for the issues that do not satisfy this query. |
Editing Custom Values
The Custom Values section of your rich filter also allows you do to the following operations:
To do the following: | Do this: |
|---|---|
Edit a Custom Value | Click the edit icon at the right of any custom value. A dialog appears. Make your changes and click on the Save custom value button. Note that once a custom value is created, one setting cannot be changed anymore – the Value Type. This means that if you have selected Issue Count as the base value, you cannot change it anymore. If you had selected, for example, a number field as the base value, then the value type would be Numeric. You could then update the Base value and select another number field, but you could nod choose Issue Count anymore (the value type would have to remain Numeric). This is necessary to ensure the consistency of custom values with time series once used in the Rich Filter Time Series Chart gadgets (see Using Custom Values in Time Series below). You need to create a new custom value to change the Value Type. |
Delete a Custom Value | Click the delete icon at the right of any custom value. |
Reorder the Custom Values list | Hover over the vertical “grid” icon of the custom values, then drag and drop up or down to the new position. This order is applied when displaying the custom values in the settings of the rich filter gadgets and the time series where they can be used. |
Duration (calculated) Custom Values
Calculated custom values are a special case of custom values having a computed base value. Rich Filter for Jira Dashboards provides two calculated custom values that represent time duration:
Issue age / resolution time - predefined duration value calculated as the time elapsed between the resolution time (or now for unresolved issues) and the created date
Custom duration - duration value calculated as the time elapsed between any two date/date time fields or between a date/date time field and now
These options are further detailed in the sections below.
Issue age / resolution time
As its value type indicates, Issue age / resolution time is a computed duration value based on the issue created and resolved dates.
Here is how the Issue age / resolution time value is computed:
for resolved issues – the value represents the number of days between the resolution date and the created date (resolution time)
for unresolved issues – the value represents the number of days between now and the created date (issue age)
Like any other custom value, issue age values can be used in rich filter gadgets and time series.
Lead Time
You can combine the Issue age / resolution time base value with JQL sub-queries to build custom values that show only the resolution time or only the issue age. For instance, if you wish to see the lead time of your resolved issues, you can add the JQL query resolution that is not empty to your custom value definition and use the average total formula. Your custom value will show the average resolution time of your resolved issues – called the Lead Time.
Custom duration
Custom duration is a computed duration value, calculated as the time elapsed between any two date/date-time fields or between a date/date-time field and now. To create a custom value based on a custom duration, select the Custom duration option in the Base value drop-down menu. Next, select the Start time and End time, which can be a date/date-time field or the Current time.
Using custom values in Rich Filter Gadgets
Once defined, custom values can be used in rich filter gadgets the same way built-in values are. The gadgets display the custom values considering their attributes – label, color, total formula, value display (for time tracking fields) and JQL filter.
Below is the list of rich filter gadgets that can display custom values:
The Rich Filter Simple Counter gadget
Learn more: Rich Filter Simple Counter Gadget
The Rich Filter Smart Counters gadget
Learn more: Rich Filter Smart Counters Gadget.
If the smart filter has a color tag type, each value is displayed using the colors defined in the smart filter clauses. If the smart filter does not have a color tag type, the color of the custom value (if defined) is used to display the values.
The Rich Filter Statistics gadget
Learn more: Rich Filter Statistics GadgetThe Rich Filter Two Dimensional Statistics gadget
Learn more: Rich Filter Two Dimensional Statistics Gadget.
The Rich Filter Results gadget
Learn more: Rich Filter Results Gadget
Using custom values in time series
Once defined, the custom values can also be used in Time Series. If you're unfamiliar with Time Series, look at our Configuring Time Series section.
When creating or editing time series, you can use your custom values as value.
The time series will have the same value type as the custom values on which they are based. For instance, if your custom value is Numeric type, then your time series will also have the same value type.
Like any other time series, the time series based on custom values can be displayed as line charts with the Rich Filter Time Series Chart gadget or tables with the Rich Filter Statistics gadget.