A lot of teams in Kainos are using Jira for their development process management and defects management. Jira allows you to track your stories and bugs through your highly configurable process flow from report to release. Jira is very flexible tool, you can have custom process flow and add custom fields to reflect your business needs. Out of the box you will find also simple reports on your team performance. But what if you would like to track some development metrics that are based on custom fields? Or you have many teams and you’d like to aggregate the data and automatically generate reports for all of them with the same format?

It is not a problem! Jira gives you API that allows to retrieve all data needed to create any reporting you need. In this short article I would like to explain how to create simple reporting using JIRA API and R language for data manipulation. In this article I’d like to show you how to create report that will visualize backlog changes in time and additionally dynamics of defects reported for specific team. The result chart you can find below.

Weekly reported defects with cumulative sum of defects in backlogIn a medium or big project where couple of agile teams needs to work together to achieve expected results Jira not only tracks work items in all teams but also play a role of knowledge base on every epic, story and bug reported. To divide issues among teams, it is worth to add custom field named “Team”. It will give you possibility to easily create board for each team and see only items that are assigned to this specific team. Adding “Team” field is not a problem and I recommend to refer to Jira documentation to see how to do it. It won’t be covered in this article.

I’m always interested in application quality so first thing I’m checking in the project is how many defects are reported and in which area. It’s also good to know how many of them were fixed.

First of all we need to plan what data will be necessary to create this report. Following fields will be useful:

  • Team
  • Created date – when the bug was reported
  • Closed date – when the bug was closed

How to retrieve this data from Jira? It is time to use Jira REST API! All information stored in Jira is accessible via REST API (at least everything I was looking for J). Full documentation you can find here: https://docs.atlassian.com/jira/REST/latest/ . I will focus only on calls used in this example.

First of all we need a list of bugs that were reported or updated in specific period of time. The easiest way to obtain the data is to use JQL (JIRA Query Language) to filter issues. In this example JQL query will look as follows:

Type = bug AND (createdDate > "2015-10-01" OR status changed after "2015-10-01") ORDER BY created ASC

Above translates to: give me all issues with type bug that were created after October 1st or those which status were changed after October 1st and sort them by creation date. If you are familiar with SQL then JQL should not be difficult to master.
I was using Powershell as scripting language, so call to Jira REST API looks like this:

$url = 'https://{jiraUrl}/rest/api/2/search?jql=type in (bug, "Automated test sub-task") AND (createdDate > "2015-10-01" OR status changed after "2015-10-01") and (labels NOT IN (ticket_tidy_up) OR labels IS EMPTY) ORDER BY created ASC &startAt=' + $startAt
$response = Invoke-RestMethod -Uri ($url) -Headers @{"Authorization" = "Basic " +
[System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($username + ":" + $password ))} -Method GET

$issues = $response.issues

Jira won’t send you all the data in one batch, by default data is sent in 50 items batches. You should check the total variable to check if you need to perform more calls to retrieve all items. Next step is parsing the data. It’s worth to create your own data structure and populate it with the data from Jira. In this example we will need following fields:

Field Description
team Team fixing bug.
key Issue id.
created Date when issue was created.
updated Date when issue was updated for the last time.
status Current issue status.

This is how you’ll create object in Powershell to store above values:

$item = New-Object PSObject -Property @{
key = $issue.key
updated = $issue.fields.updated
created = $issue.fields.created
status = $issue.fields.status.name
team = GetTeam($issue)
}

All fields are generic Jira fields so there is no problem with their retrieval. You need to put more work to retrieve “Team” value from custom field. First you should check what is the number of the custom field you would like to retrieve data from. Easiest way is to type name of this field in advanced search box in Jira:
customFieldIn this example scrum team have number 11001. Scrum team field is multi select box but I will take only first value from array. Below example of Powershell function that will take issue and return team.

function GetTeam($issue)
{
if($issue.fields.customfield_11001 -is [system.array] -and $issue.fields.customfield_11001.count -gt 0)
{
$team = $issue.fields.customfield_11001[-1].value
}else
{
$team = $issue.fields.customfield_11001.value
}
return $team
}

When all items are downloaded and parsed we should export the data in format that will be usable in visualization step. CSV should work fine. I used Export-CSV cmdlet to export all items. First line won’t be needed so it is removed:

$items | Export-CSV $filename
(Get-Content $filename | select -Skip 1) | Set-Content $filename

Now when you have information from Jira in file it is time to think about visualizing the data for better understanding. This topic will be covered in next article.

In next article you can find information on how to visualize created dataset using R language: Agile teams reporting using Jira API and R language – part 2