Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Documentation Plugins Jira data source Jira query editor

Jira query editor

Grafana provides a query editor for Jira. For general documentation on querying data sources in Grafana, including options and functions common to all query editors, refer to Query and transform data.

Jira query editor options

The following is a list of Jira-specific query editor options:

• Select field - Select Jira issue fields, such asEpic Name, Summary, Sprint Name, and Story point estimate. Click the down arrow or anywhere in the field for a list of available options.

• Limit - Limits the amount of issues returned by the query. The default is 50.

• Filter(JQL) - Add a valid JQL query. For more information on JQL, refer to Use advanced search with Jira Query Language (JQL). Pressing Command/Ctrl + Enter keys can be used to run the query.

Example query:

JQL Copy

project='TEST' and assignee ='Joe Smith'

The query finds all of Joe Smith’s issues in the TEST project.

Filter, view and sort issues

The Jira data source queries Jira for issues, which can represent bugs, user stories, support tickets, or other tasks in Jira. Select a field to view and use JQL to filter and/or sort your issues.

You can enter any valid JQL expression to filter and/or sort your issues based on any of their fields such as Project Name, Issue Type, Assignee Name, or Sprint Name with the Atlassian query language JQL. For more information on working with JQL, refer to Search Jira like a boss with JQL and Use advanced search with Jira Query Language (JQL).

You can display your data in a table or use Grafana transformations to manipulate issue data, run calculations, or turn the data into a time series graph. For more information, refer to Apply Transformations

Transformations to augment JQL

While Grafana provides many Transformations to choose from, the following provide powerful augmentation to give JQL some of the power and features of SQL. For more information on transformations and types of transformations, refer to Transform data and Transformation functions.

The following transformation are useful when working with the Jira data source:

• Add field from calculation - Similar to SQL expressions, this transformation allows adding new fields to your dataset based on calculations from other fields. The fields used in the calculation can be from a single query or from queries you’ve joined together. You can also chain together calculations and perform calculations from calculated fields. Refer to Add field from calculation for more information.

• Extract fields - As some fields are returned in “stringified JSON” format (JSON returned as a string), this transformation allows you to parse those JSON fields and create new fields by providing the JSON path to the data you need. See Extract fields for more information.

• Group by - This transformation provides a key feature that is not part of the standard Jira JQL syntax: the ability to group your data. Use this transformation to group by Sprints or other Issue fields, and aggregate by group to get metrics like velocity and story point estimates vs actual completed in a Sprint. Refer to Group by for more information.

• Outer Join - Similar to SQL joins, this transformation lets you join 2 or more queries together by common fields. This provides a way to combine datasets from queries and use other transformations to calculate values from multiple queries or datasets. Refer to Outer join for more information.

Time series query

To show time series data, choose a date field along with a numeric field, then switch to the graph visualization.

Example: Sprint Start Date, Story point estimate

The numeric field can be calculated by using the Group By transformation, which allows grouping by Sprint Start Date and summarizing the Story point estimate, creating a visualization of Story Points over time per sprint.

Linked issues

The linked issues field returns JSON as a string, or “stringified JSON”. You will need to apply the Extract fields transformation to get the data you need. Because Jira returns linked issues in 2 different paths (“blocks” or “is blocked by”, for example), you will need to duplicate the query to handle each of the paths separately and then merge the 2 results into a single table.

1. Add a Query
   • Select Fields: Key, Linked Issues
   • Add the JQL Filter: project = 'YOUR_PROJECT'
2. Add the same query as above one more time
3. Add transformation Extract fields
   • Source = Linked issues
   • Format = JSON
   • Add path
     • Field = inwardIssue.key
     • Alias = Linked issue key
   • Add transformation filter so that transformation only applies to query A
4. Add another transformation Extract fields
   • Repeat everything from step 3, but use the path outwardIssue.key and apply the transformation to query B.
5. Add transformation Filter data by value
   • Filter type = Include
   • Conditions = Match any
   • Add condition:
     • Field = Linked issues
     • Match = Is equal
     • Value = Leave the field empty
   • Add another condition:
     • Field = Linked issues
     • Match = Regex
     • Value = inwardIssue
   • Add transformation filter so that transformation only applies to query A
6. Add another transformation Filter data by value
   • Repeat everything from step 5, but use outwardIssue in the condition and apply transformation to query B.
7. Add the Merge transformation
8. Add the Organize fields transformation
   • Hide the field Linked issues with JSON data
   • As the Merge transformation might have had an impact on field names, you can rename other fields if necessary.

Using Transformations from Grafana to answer common questions

You can use transformations to visualize, aggregate, group, and join datasets, along with many other types of transformations to transform simple results into answers for complex questions.

Example 1: How do I show Velocity per Sprint?

1. Select Fields: Sprint Name, Story point estimate
2. Add JQL Filter project = "Your Project" AND type != epic AND status = done order by created ASC
3. Add Group By transformation
   • Sprint Name | Group By
   • Story Point Estimate | Calculate | Total
4. Select the Bar Gauge visualization

Example 2: How do I show what was Completed vs. Estimated in a Sprint?

1. Add a Query
   • Select Fields: Sprint Name, Sprint Start Date, Story point estimate
   • Add JQL Filter: project = 'Your Project' AND type != epic
2. Add a second Query
   • Select Fields: Sprint Name, Sprint Start Date, Story point estimate
   • Add JQL Filter: project = 'Your Project' AND type != epic AND status = done
3. Add Group By transformation
   • Sprint Name | Group By
   • Sprint Start Date | Group By
   • Story point estimate | Calculate | Total
4. Select the Graph visualization

Example 3: What is the Average time to complete issues in my project?

1. Add a Query
   • Select Fields: Created, Status Category Changed
   • Add JQL Filter: project = 'Your Project' AND type != epic AND status = done
2. Add Transformation: Add field from calculation
   • Mode = Reduce Row
   • Calculation = Difference
3. Add Transformation: Add field from calculation
   • Mode = Binary Operation
   • Operation = Difference / 86000000 (1000 * 3600 * 24 to get days
   • Alias = Days
4. Add Transformation: Organize fields
   • Hide Difference field
5. Add Transformation: Filter data by value
   • Filter Type = Include
   • Conditions = Match any
     • Field = Days | Match = Is Greater | Value = 1
6. Add Transformation: Reduce
   • Mode = Series to Rows
   • Calculations = mean
7. Select the Stat visualization