How to create Jira user story cards programatically

Introduction

The company I work for uses Jira v6.0.1 as an issue tracker. It also uses a plugin called Greenhopper (Jira Agile) that gives agile extensions to Jira. Although it provides a variety of ways to visualize user stories we wanted to print the user stories to create a physical board without much hassle. Unfortunately this feature is provided by yet another paid plugin.

For this reason I wrote a simple web application that connects to Jira and, based on a search expression, displays the user cards that match the search. You can easily copy them to Word and print them from there.

1

How to access Jira

Jira provides a REST API that allows us to query issues, create issues, etc. If you have a Jira installation that you can access, you can reach the API at http(s)://Your.Jira.Site/rest/api/2/search. If you access it through the browser and if it works correctly you should see a JSON response that contains Jira issues.

Now that we can access the API, we want to be able to search specific issues. Jira provides the ability to supply a search query in the request URL in the form http(s)://Your.Jira.Site/rest/api/2/search?jql=xxxxxx, where the value of the jql parameter is the search query. This query parameter has a specific syntax and the best solution I found to compose it is to perform a search in Jira and copy it from the URL. Just navigate to the search page, select some search criteria and press the search button. If you inspect the URL you will find the jql query in there, and that is exactly what we need.

2

How to access the API through code

The code below is in C# but could be any other language, as long as it can make HTTP requests.

I created two server side methods. One initializes the HttpClient object and the other creates a list of issues. Let's start by the method PrepareHttpClient(...).

private HttpClient PrepareHttpClient(string username, string password, string jiraUrl)
{
    var client = new HttpClient { BaseAddress = new Uri(jiraUrl + "/rest/api/2/search") };

    byte[] cred = Encoding.UTF8.GetBytes(username + ":" + password);
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(cred));
    client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

    return client;
}

This method creates an HttpClient instance that will be used to make the API request. We define the address to which we are going to make the request and the appropriate request headers.

This method is used by another method that actually makes the request and processes the return value. Let us look at the method GenerateCards(...).

public ActionResult GenerateCards(string username, string password, string url, string queryString)
{
    HttpClient client = PrepareHttpClient(username, password, url);
    HttpResponseMessage response = client.GetAsync(queryString).Result;

    var issues = new List<Issue>();
    if (response.IsSuccessStatusCode)
    {
        dynamic jsonResponse = JsonConvert.DeserializeObject(response.Content.ReadAsStringAsync().Result);
        dynamic issuesList = jsonResponse.issues;

        for (int i = 0; i != issuesList.Count; i++)
        {
            issues.Add(new Issue { Id = issuesList[i].key.ToString(), Name = issuesList[i].fields["summary"].ToString(), Description = issuesList[i].fields["description"].ToString(), Priority = issuesList[i].fields["priority"]["id"].ToString(), StoryPoints = issuesList[i].fields["customfield_10073"] });
        }
    }

    return Json(issues);
}

This method makes the HTTP request and, if successful (HTTP 200), creates a list of issues. For each card I'm retrieving its key, summary, description, priority and a custom field that contains the number of story points given to the user story. This data will be used in the web page.

The sample application

You can find the sample application I built up on GitHub.
The files you should focus on are the view Index.cshtml and the controller HomeController.cs. For creating the sample application I used Visual Studio 2013 and ASP.NET MVC 4, with support from jQuery, Bootstrap and Newtonsoft.Json.

The application needs some user input to be able to access the Jira issues:

  • Username: your Jira account username
  • Password: your Jira account password
  • Jira url: the base url of your Jira installation. Something like https://jira.yourOrganization.com
  • Querystring: the jql URL parameter described above. If no value is provided the server is going to query all issues, which may take a while

Conclusion

It is quite easy to access Jira and read/create issues programatically. In this post I described how to connect to Jira's REST API and search for issues for the purpose of automating the creation of user story cards.

You can find a working Visual Studio 2013 solution in the CodeProject article I created in http://www.codeproject.com/Tips/683523/How-to-create-Jira-user-story-cards
Alternatively, you can get it from my GitHub repository at https://github.com/gustavorhm/JiraCardGenerator

If you have any questions I'll be happy to answer them.

References

Jira REST APIs full reference

Jira REST APIs quickstart

comments powered by Disqus