In this section:
- About Custom Values
- Adding New Custom Values & Custom Values' Key Attributes
- Editing Custom Values
- Duration (calculated) Custom Values
- Using Custom Values in Rich Filter Gadgets
- Using Custom Values in Time Series
1. About Custom Values
Custom values are user-defined outputs that can be 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.
2. 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.
In order to define new custom values, click on 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:
|Label||The label is mandatory and it is used to identify and display custom values in rich filter gadgets and time series.|
|Color||Optionally, you can set a custom color that will be used to display the value in some of the rich filter gadgets.|
Select the value on which your custom value is based. Your custom value can be based on:
Displayed in the table listing all the Custom Values
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 values types are:
The total formula is used when displaying totals for the custom values. The possible options are sum, average, minimum and maximum values.
Applies only to Numeric base values
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).
If you select the maximum 2 option the value will be displayed 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, then the numeric values are displayed using a thousands separator (based on user's locale).|
This setting allows you to chose 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 sub-set of issues. The custom value will be empty for the issues that do not satisfy this query.|
3. 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, there is one setting that 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 in order 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).
In order to change the Value Type, you need to create a new custom value.
|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.
4. Duration (calculated) Custom Values
When creating new custom values, you can choose 'Issue age / resolution time' as base value. As its value type indicates, 'Issue age / resolution time' is a computed duration value, based on the created and the resolved dates of your issues.
Here is how the 'Issue age / resolution time' value is computed:
- for resolved issues – the value is the number of days between the resolution date and the created date (resolution time)
- for unresolved issues – the value is the number of days between now and the created date (issue age)
Like any other custom value, duration custom values can be used in rich filter gadgets and time series.
You can combine the 'Issue age / resolution time' base value with JQL sub-queries in order 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 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 – which, from a functional point of view, can be called Lead Time.
5. Using Custom Values in Rich Filter Gadgets
Once defined, the custom values can be used in rich filter gadgets the same way built-in values are. The gadgets display the custom values taking into account their attributes – label, color, total formula, value display (for time tracking fields) and JQL filter.
Below we provide the list of rich filter gadgets that can display custom values:
- The Rich Filter Simple Counter gadget
Have a look at The Rich Filter Simple Counter Gadget documentation page to see how to configure the gadget
The Rich Filter Smart Counters gadget
Have a look at The Rich Filter Smart Counters Gadget documentation page to see how to configure the gadget
If the smart filter has a color tag type, then each value is displayed using the colors as defined in the smart filter clauses. If the smart filter does not have a color tag type, then the color of the custom value (if defined) is used to display the values.
The Rich Filter Statistics gadget
Have a look at The Rich Filter Statistics Gadget documentation page to see how to configure the gadget
- The Rich Filter Two Dimensional Statistics gadget
Have a look at The Rich Filter Two Dimensional Statistics Gadget documentation page to see how to configure the gadget.
The Rich Filter Results gadget
Have a look at The Rich Filter Results Gadget documentation page to see how to configure the gadget.
When displaying custom values in rich filter results, if the view is configured to display totals for value rows, then the Total formula is used when computing the total displayed in the footer of the view.
The Value display setting can be very handy if you wish to display your time tracking fields in days, hours, minutes or seconds. The same setting is applied when exporting the custom values to Excel!
6. Using Custom Values in Time Series
Once defined, the custom values can also be used in Time Series – if you're not already familiar with the Time Series, you should first have a look at our Configuring Time Series section.
When creating or editing time series, you can chose to use your custom values as value.
The time series will have the same value type as the custom values they are based on. For instance, if your custom value is of type Numeric, then your time series too will 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 as tables with the Rich Filter Statistics gadget.