275-added download_jira_issues.rmd file

vignettes/download_jira_issues.Rmd

@@ -0,0 +1,115 @@
+---
+title: "Download JIRA Issues and Comments"
+output: 
+  html_document:
+    toc: true
+    number_sections: true
+vignette: >
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteIndexEntry{Download JIRA Issues and Commentss}
+  %\VignetteEncoding{UTF-8}
+---
+
+
+```{r}
+rm(list = ls())
+seed <- 1
+set.seed(seed)
+```
+
+```{r warning=FALSE,message=FALSE}
+require(kaiaulu)
+require(data.table)
+require(knitr, quietly = T)
+require(dplyr, quietly = T)
+require(jsonlite)
+```
+
+# Introduction
+
+This example is adapted from the JirAgileR package [README.md](https://github.com/matbmeijer/JirAgileR). 
+
+As usual, the first step is to load the project configuration file. 
+
+# Project Configuration File
+
+In this notebook, we will obtain data from the issue tracker JIRA. We will use [Apache's Geronimo open source project](https://geronimo.apache.org). Refer to the `conf/` folder on Kaiaulu's git repository for Geronimo and other project configuration files. It is in this project configuration file we specify where Kaiaulu can find the jira sources from Geronimo. We will use the issue_tracker -> jira fields only. In regards to the "issues" and "issue_comments" fields, these should be set to paths where you want to store the jira data. Then, you can access this jira data later using these same paths.
+
+# your_api_token is your atlassian token that is used as your password. Your username is your atlassian username (usually your email). These can be created by navigating to the indicated directories and creating a plain text file (vim atlassian_username or vim atlassian_token) and typing in your username or token. Details on how to obtain an atlassian token can be found here: https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/
+
+```{r}
+conf <- yaml::read_yaml("../conf/geronimo.yml")
+issue_tracker_domain <- conf[["issue_tracker"]][["jira"]][["domain"]]
+issue_tracker_project_key <- conf[["issue_tracker"]][["jira"]][["project_key"]]
+save_path_issue_tracker_issues <- conf[["issue_tracker"]][["jira"]][["issues"]]
+save_path_issue_tracker_issue_comments <- conf[["issue_tracker"]][["jira"]][["issue_comments"]]
+your_api_token <- scan("~/.ssh/atlassian_token",what="character",quiet=TRUE)
+username <- scan("~/atlassian_username",what="character",quiet=TRUE)
+
+```
+
+
+# Download issues
+
+This calls a function that interacts through the JIRA REST API through the rest/api/2/issues endpoint. It authenticates requests with your username and api token (used in this case as the password). It also specifies the parameters passed to the API request including fields. maxResult is the number of issues downloaded per page, verbose when set to TRUE prints operational messages, and maxDownloadsPerHour sets an upper limit on how many issues will be downloaded within an hour before the function sleeps until the hour elapses. 
+
+```{r eval=FALSE}
+all_issues <- download_and_save_jira_issues(issue_tracker_domain,
+                           username, 
+                           your_api_token, 
+                           jql_query = paste0("project='",issue_tracker_project_key,"'"), 
+                           fields = c("summary", 
+                           "description",
+                           "creator",
+                           "assignee",
+                           "reporter",
+                           "issuetype",
+                           "status",
+                           "resolution",
+                           "components",
+                           "created",
+                           "updated",
+                           "resolutiondate"), 
+                           save_path_issue_tracker_issues, 
+                           maxResults = 5, 
+                           verbose = TRUE,
+                           maxDownloadsPerHour = 4500)
+
+# save all_issues as a json file along the path save_path_issue_tracker_issues
+# jsonlite::write_json(all_issues, save_path_issue_tracker_issues)
+```
+# Download Issue with Comments
+
+In the same manner as before, we can perform the same function call, but including the field `comment`. This will result in the same table being generated but with the additional comment information per issue (if an issue has more than one comment, the issue id is repeated for each different comment). The comment is shown on the column `comment_comments_id`. 
+
+The data of this table can be used to calculate `social smell metrics`, as it represents a form of developer communication. A notebook discussing how to use JIRA data as communication network and/or combining to mailing list data will be made available in the future. 
+
+Since this time around we requested the issue data and comments, when using the `parse_jira` function, both the issues and comments table will be available from the parser. Since the issue table was already displayed, the following show a few rows of the issue comments table:
+
+# Call the function fetch_and_save_jira_issues (defined on line 55)
+```{r eval=FALSE}
+# Call the function
+all_issues_comments <- download_and_save_jira_issues(issue_tracker_domain,
+                           username, 
+                           your_api_token, 
+                           jql_query = paste0("project='",issue_tracker_project_key,"'"), 
+                           fields = c("summary",
+                           "description",
+                           "creator",
+                           "assignee",
+                           "reporter",
+                           "issuetype",
+                           "status",
+                           "resolution",
+                           "components",
+                           "created",
+                           "updated",
+                           "resolutiondate",
+                           "comment"), 
+                           save_path_issue_tracker_issue_comments, 
+                           maxResults = 5, 
+                           verbose = TRUE,
+                           maxDownloadsPerHour = 4500)
+#path <- file.path(save_path_issue_tracker_issue_comments)
+jsonlite::write_json(all_issues_comments, save_path_issue_tracker_issue_comments)
+```