matbmeijer/jiragiler

User-friendly :small_blue_diamond:JIRA API wrapper. Track projects & issues from within R

JirAgileR

Objective

The JirAgileR R package has the mission to bring the power of the project management tool 🔧 JIRA to R. By doing so, users benefit from the best capabilities of both platforms. More specifically, the package is a wrapper around JIRA’s REST API, allowing users to easily analyze JIRA projects and issues from within R. The underlying powertrain of the API is the Jira Query Language (JQL). You can find more information about it here. You can find a cheatsheet here.

Source: R For Data Science - Hadley Wickham

The focus of this package lies in the following workflow aspects:

• Import
• Tidy

Hence, for easy transformation and manipulation, each function returns a data.frame with tidy data, following main rules where each row is a single observation of an issue or a project, each column is a variable and each value must have its own cell. Thus, it integrates well with both the dplyr and data.table R libraries. This also allows for an easy integration with tabular data.

More information about the package can be found at the following link: https://matbmeijer.github.io/JirAgileR/.

Functionalities as of 08 of June, 2021

1. Extract all project names with their basic information (e.g. Name, ID, Key, Type, Category etc.).
2. Retrieve all issues specific to a user defined JIRA query with hand-picked fields and all the associated information. Currently, the package supports the following JIRA fields:
   • aggregateprogress
   • aggregatetimeestimate
   • aggregatetimespent
   • assignee
   • comment
   • components
   • created
   • creator
   • description
   • duedate
   • environment
   • fixVersions
   • issuelinks
   • issuetype
   • labels
   • lastViewed
   • priority
   • progress
   • project
   • reporter
   • resolution
   • resolutiondate
   • status
   • summary
   • timeestimate
   • timespent
   • updated
   • versions
   • votes
   • watches
   • workratio
   • parent

Note

• To get all the information about the supported JQL fields visit the following link. The package supports extracting comments, yet as one issue may contain multiple comments, the data.frame is flattened to a combination of issues and comments. Thus, the information of an issue may be repeated the number of comments each issue has.

Roadmap

• 🔲 Define integrated Reference Classes within the package
• 🔲 Include plotting graphs 📊
• 🔲 Ability to obtain all available JIRA fields of a project
• ✅ Added get_jira_dashboards() function to retrieve JIRA dashboards
• ✅ Added get_jira_permissions() function to retrieve JIRA user permissions
• ✅ Added get_jira_groups() function to retrieve JIRA groups
• ✅ Added get_jira_server_info() function to retrieve JIRA server information
• ✅ Remove data.table dependency
• ✅ Ability to save domain, username & password as secret tokens in environment 🔐
• ✅ Include pipes to facilitate analysis
• ✅ Improve package robustness
• ✅ Include http status error codes
• ✅ Give user visibility of supported fields

Installation

You can install the CRAN release version of JirAgileR following this R command:

install.packages("JirAgileR")

You can also install the latest release of this package from Github with the following commands in R:

if (!require("devtools")) install.packages("devtools")
devtools::install_github("matbmeijer/JirAgileR")

Examples

This is a basic example which shows you how to obtain a simple table of issues of a project and create a tabular report. Most of the times, you will need a username and your password to authenticate in your domain. Possible fields to obtain (which will populate the data.frame columns) can be found here.

library(JirAgileR, quietly = T)
library(knitr, quietly = T)
library(dplyr, quietly = T)

# Save credentials to pass them only one time
save_jira_credentials(domain = "https://bugreports.qt.io")

# Get full list of projects in domain
get_jira_projects() %>% 
  select(key, name)  %>% 
  kable(row.names = F, padding = 0)

key	name
COIN	Coin
QBS	Qbs (“Cubes”)
QTBUG	Qt
QT3DS	Qt 3D Studio
AUTOSUITE	Qt Automotive Suite
QTJIRA	Qt Bugtracking interface
QTCREATORBUG	Qt Creator
QDS	Qt Design Studio
QTEXT	Qt Extensions
QTMCU	Qt for MCUs
PYSIDE	Qt for Python
QTIFW	Qt Installer Framework
QTMOBILITY	Qt Mobility
QTPLAYGROUND	Qt Playground Projects
QTWEBSITE	Qt Project Website
QTQAINFRA	Qt Quality Assurance Infrastructure
QTCOMPONENTS	Qt Quick Components (Deprecated, use QTBUG)
QSR	Qt Safe Renderer
QTSOLBUG	Qt Solutions
QTVSADDINBUG	Qt Visual Studio Tools
QTWB	Qt WebBrowser
QTSYSADM	Qt-Project.org Sysadmin (defunct)

# Retrieve the issues from a single project - in this case the project QTWB from bugreports.qt.io. See documentation to define which fields to see
get_jira_issues(jql_query = "project='QTWB'",
                fields = c("summary","created", "status")) %>% 
  select(key, summary, created, status_name, status_description, status_statuscategory_name) %>%
  head(2) %>%
  kable(row.names = F, padding = 0)

key	summary	created	status_name	status_description	status_statuscategory_name
QTWB-60	webkit-qtwe bkit-23/Source/WTF/wtf/dtoa/bignum.cc:762: suspicious increment ?	2021-05-12 22:56:00	Reported	The issue has been reported, but no validation has been done on it.	To Do
QTWB-58	win7 touchscreen can’t click html-select dropdown list	2021-04-08 09:09:00	Reported	The issue has been reported, but no validation has been done on it.	To Do

Disclaimer

• This package is in no way affiliated to the Atlassian Corporation Pl company, the creator and mantainer of the JIRA SERVER API.

Code of Conduct

Please note that the JirAgileR project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

License

MIT © Matthias Brenninkmeijer

jiragiler's Issues

Error: API did not return json Issue

when I try connect my jira server with JiraAgilR tool, it commes
"Error: API did not return json Issue".
I think this issues maybe comes from api miss adressed in my server.
My jira server can access rest api like this :
http://my.server.com/issue/rest/api/2/issue/ISSUENO-4867

But this tool only fixed rest api like this :
http://my.server.com/issue/rest/api/issue/ISSUENO-4867

so how can I configure rest api address freely.

Historic data

Would it be possible to use the expand = changelog functionality in the API to get field history? It's useful to understand when things like due dates change over time, but currently I can only get the data as it exists today for the issues.

Column names and values do not match when "comment" field is used and as.data.frame = TRUE

It seems using the default parameter as.data.frame = TRUE causes column names do not match values, nor the function get_jira_issues to respect the fields chosen by the user (parameter fields=) when the comment field is used. However, turning the parameter to as.data.frame = FALSE, which returns the json, properly return the data.

I got this issue with the example from the README.md.

Using API Key for private projects?

I'd like to use this package to get data from our work account. I have an api key that works great with the httr package - don't see a place for that in the functions here.

Error: Error Code 403 - Client error: (403) Forbidden

Hi. I 'm just trying your example, only changing your domain by mine and other domain that I also have accesss, and the result is always the same : "Error: Error Code 403 - Client error: (403) Forbidden". Do I have to set up something in the atlassian account?

library(JirAgileR, quietly = T)
library(knitr, quietly = T)
library(dplyr, quietly = T)

Save credentials to pass them only one time

save_jira_credentials(domain = "xxxxx" ,
username="xxxxx",
password = "xxxxx",
)

Get full list of projects in domain

get_jira_projects() %>%
select(key, name) %>%
kable(row.names = F, padding = 0)

Just started using it

Hi, Why Am I getting an Error: API no response from json

Minor documentation suggestions re: resolutiondate and get_jira_projects()

Mostly just here to say thanks for a super useful package! This gives me/my team a lot more flexibility and saves us time not having to futz around with Jira's clunky default reporting/UI.

I could mostly follow along with the extant docs, but tangoed with a few things that might be worth mentioning more explicitly (or help other newcomers):

1. In get_jira_projects(), it says "Calling the function too many times might block your access and you will have to access manually online and enter a CAPTCHA at jira.yourdomain.com/secure/Dashboard.jspa", which I assume was the reason for the 403 Forbidden errors I hit. In my case, there was no CAPTCHA, but signing out of Jira and signing back in in my browser session seemed to work (gleaned from https://community.atlassian.com/t5/Answers-Developer-Questions/How-long-does-the-captcha-last-when-triggered-with-the-rest-API/qaq-p/546974).

2. The classes for the date fields created, updated, and resolutiondate from get_jira_issues() are POSIXct, POSIXct, and numeric, respectively. I converted resolutiondate via as.POSIXct(resolutiondate, origin = "1970-01-01 00:00.00 UTC") which seemed to produce reasonable results for my date math, but I'm not sure how to be sure (is there a definitive source for Jira's origin?)

R version 3.6.2 (2019-12-12)
Platform: x86_64-w64-mingw32/x64 (64-bit)
Running under: Windows 10 x64 (build 15063)

Matrix products: default

locale:
[1] LC_COLLATE=English_United States.1252  LC_CTYPE=English_United States.1252   
[3] LC_MONETARY=English_United States.1252 LC_NUMERIC=C                          
[5] LC_TIME=English_United States.1252    

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base     

other attached packages:
[1] DT_0.12           JirAgileR_0.0.1.3 kableExtra_1.1.0  dplyr_0.8.4      

loaded via a namespace (and not attached):
 [1] Rcpp_1.0.3        pillar_1.4.3      compiler_3.6.2    tools_3.6.2       digest_0.6.23     jsonlite_1.6.1   
 [7] evaluate_0.14     tibble_2.1.3      lifecycle_0.1.0   viridisLite_0.3.0 pkgconfig_2.0.3   rlang_0.4.4      
[13] rstudioapi_0.10   curl_4.3          xfun_0.12         httr_1.4.1        stringr_1.4.0     knitr_1.28       
[19] xml2_1.2.2        vctrs_0.2.2       htmlwidgets_1.5.1 hms_0.5.3         webshot_0.5.2     tidyselect_1.0.0 
[25] glue_1.3.1        R6_2.4.1          rmarkdown_2.1     readr_1.3.1       purrr_0.3.3       magrittr_1.5     
[31] scales_1.1.0      htmltools_0.4.0   assertthat_0.2.1  rvest_0.3.5       colorspace_1.4-1  stringi_1.4.5    
[37] munsell_0.5.0     crayon_1.3.4     

Removed from CRAN

Package ‘JirAgileR’ was removed from the CRAN repository.

Formerly available versions can be obtained from the archive.

Archived on 2022-10-03 as check issues were not corrected despite reminders.

A summary of the most recent check results can be obtained from the check results archive.

Please use the canonical form https://cran.r-project.org/package=JirAgileR to link to this page.

Error fetching resolutiondate

When i append "resolutiondate" to searchfields to fetch from Jira i get an error.

GetJiraData <- function() {
  searchFields <- c("project", "key", "status", "resolution", "created", "resolutiondate", "timeoriginalestimate", "timeestimate", "timespent")
#... Plus the other required fields
  jiraIssues <- JiraQuery2R(domain = domain, query=jqlQuery, fields = searchFields, user = username, password = password, maxResults = 10000)
}
issues <- GetJiraData()

returns

 Error in data.table::rbindlist(ext_info, fill = T) : 
  Class attribute on column 6 of item 3 does not match with column 6 of item 1. 

I am using RStudio Version 1.2.1578 on Windows 10.

Add field «Sprint» to list of available fields

Hello Matthias, your package is very helpful and awesome!
Is it possible to add the "sprint" field to the list of available fields in the foreseeable future?

Error encountered in get_jira_dashboards()

Hi, I encountered tyhe following error.

get_jira_dashboards()

generates the error

Error in rbind(deparse.level, ...) : 
  numbers of columns of arguments do not match

Troubleshooting, I found the offending line in the code here:
Error Line using rbind

When I changed

  df <- do.call(rbind, issue_list)

to

  df <- dplyr::bind_rows(issue_list)

it works.
However need to include import of dplyr package

Adding customfields

Hello,

I have used my own un-published solutions for Jira in R for years and I'm happy to finally see a clean public library for it.

One major hurdle are of course the custom fields. I am ready to help and wanted to throw a few potential solutions:

• Adding an option to expose the entire raw JSON object to let the user pick the fields. From memory this is what the python module does.

• Being able to locally define supported fields

• Flattening the JSON object as much as possible to return everything in a data.frame. I seem to remember {jsonlite} or {httr} has solid options.

• Using the /field API and store the result locally. This could allow JjirAgileR learn about the structure of the Jira instance.
  I would need to test it further but it seems to describe which field is a date, an array etc. A different endpoint also returns the possible value of a field. This can be used to build the levels of a factor.