If you're into Agile software development, then most likely you or your company is using a tool that will let you manage your user stories. There are a lot of Agile project management software out there and I've had great experiences with 2 of the most popular - JIRA and Pivotal Tracker.
In this blog, I will share with you a sample project that I created that will let you hook up to your project in Pivotal Tracker. I will go through the basics of connecting to the Pivotal Tracker API v5, getting your tokens and credentials and walking through the sample code I created which grabs all the user stories in my project and displaying them in Visual Studio.
Lets get started...
As I mentioned, Pivotal Tracker is a great agile project management software. A quick wiki on Pivotal Tracker:
The tool includes file sharing and task management,
velocity tracking and iteration planning; release markers; and progress charts. There is an
API[8] for extensions and third party tools.
[9]"
What I like most about Pivotal is the fact that you can extend its functionality and directly plug in using your development tool. Although I am showing you how to use Visual Studio to plug in to Pivotal, you can you whatever your favorite code language is.
To start, you need to have access to Pivotal Tracker to be able to go through this sample project. For this blog, I just created a Sample Project, with a 60-day trial version. This project may not work after 60-days because the trial may have already expired, but you can use the project with a few minor tweaks to access your own project.
Below, shows a sample Pivotal project, with a few user stories:
Our Visual Studio Plugin will grab all these user stories in Pivotal and show them in a Textbox.
Get your user credentials...
First thing you need to do is get your credentials, specifically your API token. To do that you need to either use curl via the command below:
$ curl -X GET --user username:password "https://www.pivotaltracker.com/services/v5/me"
This would display a JSON result with a bunch of information. What you will be interested in is the entry for "api_token" and the "id" under "projects".
Another way to get this is by going through "Profile" under your login name on the upper right hand side of your screen, similar to below:
Once you have your token and projectid information, you can plug this into your code.
Creating your Visual Studio Plugin...
The first thing you need to do is you need to go through the API reference from Pivotal Tracker, this will provide a ton of information you need to get you started, as well as enhancing this solution to satisfy your teams/company's need.
The next thing you need to understand is that the Pivotal Tracker API v5 returns a JSON result. For example, to grab all the user stories from your project, you can use the curl command below:
$export TOKEN=99cbf9c263dcb63e5505260822d647bd
$export PROJECT_ID=1157418
$curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories"
This will display all the user stories in your project in JSON format. Notice that the JSON result follows a common structure, displaying such elements as id, story_type, name, description, etc.
In your Visual Studio project, you need to mimic this structure so you can bring over the data from Pivotal back to your C# classes.
Next you can start creating you Visual Studio project as a Windows Form project and begin to create the elements of the project as from the screenshot below:
The form only has a single element, a textbox with vertical and horizontal bars enabled. Notice also that the project has C# classes for Label, Owner, and Story. This is what the structure of the JSON result returns when you send an API call.
Other classes may be necessary depending on what the JSON result comes back with from your request.
After creating your project, you now need to create a method that will send the request over via an API call to Pivotal, this is the main logic that takes care of getting this data, and its shown below:
public string GetStories(string project) {
string url = "https://www.pivotaltracker.com/services/v5/projects/" + ProjectId + "/stories";
var uri = new Uri(url);
// Create a new HttpWebRequest object.
HttpWebRequest request = (HttpWebRequest)WebRequest.Create(uri);
request.Proxy = WebProxy.GetDefaultProxy();
var httpWebRequest = (HttpWebRequest)WebRequest.Create(url);
httpWebRequest.ContentType = "application/json";
httpWebRequest.Accept = "*/*";
httpWebRequest.Method = "GET";
httpWebRequest.Headers.Add("X-TrackerToken", Token);
var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
Stream objStream;
var streamReader = new StreamReader(httpResponse.GetResponseStream()).ReadToEnd();
List<Story> stories = JsonConvert.DeserializeObject<List<Story>>(streamReader.ToString());
string storylist=null;
foreach (Story story in stories)
{
storylist += story.id + "," + story.name+Environment.NewLine;
}
return storylist;
}
Explaining the code ....
From the method above, the first few lines assembles the HttpWebRequest object that uses the URL that we will need to grab our stories.
The next few lines are important, they are responsible for the content, the header, and the type of request that would be sent over to the API:
var httpWebRequest = (HttpWebRequest)WebRequest.Create(url);
httpWebRequest.ContentType = "application/json";
httpWebRequest.Accept = "*/*";
httpWebRequest.Method = "GET";
httpWebRequest.Headers.Add("X-TrackerToken", Token);
Notice also that you are passing a Token variable to the Web Request header information, this corresponds to the token you got from the first curl command you executed or from the Token on your Profile inside Pivotal Tracker.
Next, you need to issue the command to send the request over, and store the result to a variable:
var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
If you recall earlier, when you created the project, you had separate C# classes to handle the result of the API call, however, the data that's being returned is in JSON. How do you convert the data from JSON to proper C# classes? I used an open JSON deserializer framework from Newtonsoft as part of this solution.
Once that's plugged-in as a reference to your Visual Studio project, I used it to deserialize the result back as below:
var streamReader = new StreamReader(httpResponse.GetResponseStream()).ReadToEnd();
List<Story> stories = JsonConvert.DeserializeObject<List<Story>>(streamReader.ToString());
Notice that the result from the stream (in JSON format) is converted to string then deserialized as a C# class matching structure of a C# class you created:
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
namespace ManagePivotalProject
{
public class Story
{
public string kind { get; set; }
public string id {get;set;}
public string created_at {get;set;}
public string updated_at {get;set;}
public string accepted_at {get;set;}
public int estimate {get;set;}
public string story_type {get;set;}
public string name {get;set;}
public string description { get; set; }
public string current_state { get; set; }
public long requested_by_id { get; set; }
public long project_id { get; set; }
public string url { get; set; }
public List<string> owner_ids { get; set; }
public List<Label> labels { get; set; }
public string owned_by_id { get; set; }
}
}
Once you have this information, you can then iterate through the structure so you can return it back to a Textbox that you can display as a result:
string storylist=null;
foreach (Story story in stories)
{
storylist += story.id + "," + story.name+Environment.NewLine;
}
You should see something similar to screenshot below:
There you go....you have now created a Visual Studio plugin that grabs all the user stories from your Pivotal Tracker project! You can do so many things with this solution, you can extend it further so you can update your stories from within Visual Studio back to Pivotal, which might be useful if you have SDETs or devs that need to update the user stories and send it back with the updates to your Product Owner. Another extension might be to automatically grab these user stories, definition, and acceptance criterias and create Specflow feature files so your SDETs and devs dont need to write the tests themselves in Visual Studio. There are a lot of possibilities that you can do with this solution.
Hopefully you enjoyed this post and if you need the source code for this project, just put in a comment here and I will email it to you. Have fun!
