Lisa Crispin

Cycle Time Report—An Example Script Using Trackers API


Tracker’s API can provide information that’s not currently available through the Tracker web application. Read on to learn how to use the API to compute cycle time.

Cycle time defined for Tracker

Lean software development has given us some useful metrics to help identify problem areas in our development flow. Lead time is the time from when a story is first created to its final acceptance and delivery to customers. Mary and Tom Poppendieck call this “Concept to Cash” in their book, Implementing Lean Software Development.

Cycle time measures only the part of lead time from when work actually begins on the story to the final acceptance and delivery to production. Since Tracker’s workflow allows story state to be changed at any time to any state, a story might be rejected and restarted, unstarted and put back in the Icebox, or even changed from accepted to unstarted. Therefore, for Tracker stories, cycle time begins the very first time a story was started. Since Tracker doesn’t know for sure when a story was actually deployed live to production, we have to use the last time it was accepted as the end of cycle time. Note that this is different from the true Lean definition, but it still can provide useful feedback to help teams improve the way they work. In this post, “cycle time” refers to our specific definition within Tracker.

Cycle time vs. lead time

Cycle time in Tracker

It’s helpful to identify stories with a cycle time significantly longer than what’s usual in the project. For example, if a story was delivered and rejected multiple times, it might be a sign that the delivery team and product stakeholders didn’t share the same understanding of how the feature should work at the time the developers started it. If that happens often, the team might try experimenting with techniques to improve shared understanding, such as story mapping.

Another reason for a long cycle time could be that the team was using brand-new technology with a steep learning curve, so it took a long time to finish one or more stories. Once they’ve mastered it, that probably won’t happen again, so there may be no need to try anything different.

Computing cycle time for your project’s stories

Because of Tracker’s built-in flexibility to cycle through different story states multiple times if needed, calculating cycle time for Tracker stories is not straightforward. We’re planning new reports that will show these types of metrics. Until then, you can calculate cycle times for stories in your project using Tracker’s API.

You can check out our example Ruby script from our repository of API examples. The script uses the activity endpoint to retrieve all the activity for the specified project. (Note that only the most recent six months of activity are available, and it’s returned in reverse order, with the most recent activity first.) The response to this endpoint is paginated, so our example shows how to page through all the entries, 100 items at a time. The script loops through all the activity events, looking for story state changes. It stores the earliest started date and latest accepted-at date for each accepted story, using the information returned in the activity resource.

Next, the script uses the API to look up the story name and type of each active story, drops the release-type stories, and then drops all stories that didn’t have at least one started-at and accepted-at time in the last six months. The remaining stories are sorted by cycle time in ascending order, and a report is printed out with the story ID, cycle time, and story name (since story names can be long, we’ve ellipsified anything over 40 characters).

To run the script, set environment variables for your Tracker API TOKEN and PROJECT_ID. Depending on the size of your project, it can take a few minutes to run.

Here are a few pointers to help you use this example:

  • If any stories that were accepted in your project were subsequently deleted or moved to another project, the report will show “deleted” instead of the story name.
  • Since you can currently only retrieve around the last six months of activity, the script can’t calculate cycle time for stories that were started more than six months ago.
  • It is possible in Tracker to put a story directly into a different active state than started (e.g., a story could go directly from the unstarted to the finished state). This script won’t compute cycle times for those, but of course you can write your own script to accommodate those differences.
  • Release-type stories and stories that are not (yet) in the accepted state will not appear on the report.
  • If a story was started more than once, and the first time was before the available activity for the project, the resulting cycle time would be incorrect.

We hope this example will help you use Tracker’s API for your own reports of metrics such as cycle time. For bonus points, update the script to also display the number of times each story was rejected. There’s an example of that in the repository, too.

Please see our API help to learn more about the API.