How to Create Jira User Story Cards Programatically

• Download source - 7.4 MB

Introduction

The company I work for uses Jira v6.0.1 as an issue tracker. We also use a plugin called Greenhopper 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 put in our 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.

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 for 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 get 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's exactly what we need.

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's look at 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 request call and, if successful (HTTP 200), it 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

Attached to this tip, you can find a complete working application where you can see all of this at work. 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's quite easy to access Jira and read/create issues programmatically. In this tip, 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.

If you have questions, just leave a comment and I'll try to reply as soon as possible.

References

• Jira REST APIs full reference
• Jira REST APIs quickstart

Thank you for reading!

Regards,
Gustavo Martins