Overview: JIRA Query Builder
With JIRA, you can track and visualize a variety of data using the Query Builder tool in Databox. In this article, we will outline the basics of the JIRA Query Builder and work through an example based on one specific use case.
IN THIS ARTICLE
1. Custom Query Overview
dimensionsparameter breaks down metrics by common criteria, such as
project. The metric output is then recategorized based on the selected dimension value. You can insert the word "by" before the dimension to create the title (i.e., "Value Points by Project").
If a query has no
dimensionselected as a parameter, the returned metric will provide aggregate values, such as overall Story Points in the given date.
ORboolean logic. Filtered queries restrict the rows that are included or excluded in the result. Each row in the result is tested against the filter. If the filter matches, the row is retained. If it doesn't match, the row is dropped.
When you click on the Value field of the filter, a drop down of selections will appear based on the dimension/ metric parameter you have selected. Because of limitations in JIRA's API, we can only list the first 15 dimensions as filter value options. For a workaround, check out the bottom of this article.
The " Data Preview" allows you to see all values that we're pulling in for the query you have created. At the bottom, you can find the total values bolded. To see data previews for different date ranges, click on the different tabs at the top of the preview.
In this example, we'll go through one basic use case that highlights how to use the Query Builder to access JIRA data.
Let's say we are working on a project for a client and we want to track all of John Stone's Value Points that have been completed. To get a better understanding of those Value Points, we want to split up this data based on the project he was working on.
Value pointsso we search and select it from the dropdown menu..
Created. We only want to report on this for one date range ("Last week"), and we will compare with the "previous period."
+icon and select a parameter that you want to filter the data by. In this example, our first filter will recognize that the Status equals
doneand the second filter will only include data where the assignee is
When your query is ready, click " Save query." This creates a new custom metric in Databox that is accessible in the Designer tool.
After you select the correct JIRA source in the Designer, you'll be able to find your new custom metric in the Custom tab of the metric dropdown list.
This will now populate the visualization type on your databoard with the custom query values .
What do you do if the filter is not listed in the Value dropdown list?
There is a limitation in JIRA's API that only allows Databox to display the first 15 result values in the filter dropdown menu. Because of this, you may sometimes be looking for a parameter that is not naturally available.
Let's say we want to filter by "Assignee is Mark Freeman," but "Mark Freeman" isn't showing up in the list of Assignee value options. As a workaround, you will first want to run the query with "Assignee" as the optional Dimension (next to the metric). This will display all available results for the parameter "Assignee."
Next, copy the name of the missing assignee (in this case, Mark Freeman), create a new filter and paste the name directly into the value field where the dropdown menu would normally appear.
Select the value "Mark Freeman" from the blue dropdown item that is now displayed. This will allow you to setup the query with more than just the first 15 value results. Continue building your query and at the end you will successfully be able to filter by the value that you want.