We’re planning a Pivotal Tracker upgrade on Jan 23. As part of this release, we will be introducing a new API version (V3), which will make it easier to follow project activity, allow you to add file attachments, move (re-prioritize) stories, associate source commits with stories, and more.

The current API version (V2) will not change, but V1 will no longer work. If you’re still using V1, you will need to change your client code to use V2 or V3.

To find out what’s changing in V3, continue reading.

How to tell what version of the API you’re using?

The API version identifier is part of the request URLs. For example, this is a V2 request:

http://www.pivotaltracker.com/services/v2/projects

What’s New or Changed in V3

Activity

The response for the activity queries will change significantly. It will include a version # (to allow you to keep track of unique events and their order), event type, when the activity occurred (with time zone), and a nested element with all story attributes that changed as part of the activity. Example:

Activity Web Hook

This will allow you to specify a URL per project (in project settings), which Tracker will post story activity to, in the same XML format as above. You’ll be able to “pull” story activity out of Tracker via normal API GET requests, or have it POSTed to your client as it occurs via the activity web hook.

Projects

The project XML response will include the current and initial velocity, last activity date, and a list of all labels in the project.

When creating a project via the API, the user represented by the API token will be made an owner of that project by default. To leave the new project without an owner (because your client is acting on behalf of a different user, for example), you’ll need to include <no_owner type="boolean">true</no_owner> in the post data.

Stories

You’ll be able to move (re-prioritize) stories via the API. To move a story to after another story:

As part of the new integrations feature (watch for more on that later), you’ll be able to associate a story with a ticket or issue in an external system, such as Lighthouse or JIRA. You’ll need to specify a ticket/issue ID, and optionally which specific integration to use (a project may be set up with multiple):

Note: Attachments in the story response XML will most likely not include a URL to the actual AWS S3 file, since these URLs are only valid temporarily. You’ll need to make a separate API call (details TBD) to get the S3 URL for a given story file attachment.

Source Control Post Commit Hooks

This will allow you to set up post-commit hooks in git, github, subversion, etc., to link commits to stories (and optionally mark them as finished) based on this message syntax:

“Torpedoes now sufficiently powered [fixes #123456]”.

Curl example, of what you might do in a custom post-commit hook script for subversion or git:

Stories will show associated source commits as comments, with a link to the commit if you include a URL in the post body:

Github Support

The V3 version of the API will also support native Github post-commit hooks, allowing you to configure your Github repo to send commit information directly to Tracker, along with the [fixes #12345] message syntax.

Written by our friends at Hashrocket, Slurper lets you create stories as plain text files and import them into Tracker via the API. Also, if you use Vim, check out slurper.vim, a Vim companion script with syntax highlighting and key mappings.

Perhaps you have heard about Pivotal Tracker but you don’t know if it’s a good fit for your organization. Perhaps you are a new user with some questions about how best to use the tool. Perhaps you’ve been using Tracker for a while but are curious about more advanced features. If you’re in San Francisco next Tuesday we can give you answers in person.

The San Francisco Tracker Users Group is having a lunchtime meeting next Tuesday at 12:30 p.m. at the Pivotal Labs office on Market St. Please register on the Meetup site, as seating is limited.

Edward Hieatt, Principal at Pivotal Labs and Pivotal Tracker developer, will give an overview of the idea behind Pivotal Tracker and the common features. Based on time and interest, Edward will go into more detail about advanced features, upcoming features, and the philosophy behind Tracker. We hope to see you there!

The Pivotal Tracker API has now been available for just over a year, and we’re really pleased with the rich variety of tools and applications that our user community has built with it, to extend Tracker’s functionality. There are now integration tools, wrappers for various programming languages, mobile apps, an IRC console, and many more on the way (see the 3rd party tools page for a comprehensive list).

We’re continuing to improve the API based on your feedback. Recently, we’ve added the ability to create projects, manage project members, and search for stories based on created and last modified dates. For the next API release, we’re adding ability to move a story relative to another story, add file attachments, and get current project velocity and all labels. We’re also adding support for Github post-commit hooks, so you can do things like “finishes #123456″ in your commit messages.

The most exciting new feature that we’re working on, though, is a push webhook, which will allow your applications to listen to activity in your Tracker project(s). You’ll be able to register a URL, per project, to which Tracker will post all story changes to (as XML). With this webhook, we’re hoping to enable a whole new class of 3rd party tools and applications, for example to facilitate 2 way integration with bug tools.

Most of these enhancements will be part of a new version of the API (V3), which we hope to have ready at the end of the year. As part of this release, we will also be turning off the first version of the API (V1), so if you’re still using that version, you’ll need to update your client code to V2 prior to that. V2 is the current version, documented on the [API Help page]. For the exact date of this release, watch this blog, or follow @pivotaltracker.

As always, your feedback is welcome. If you have ideas for other things that would be useful to add to the API, or have built a tool you’d like to share, let us know!

Koombea announced the release of the Track-r application for iPhone, a mobile client for Pivotal Tracker. Track-r is a free, open source application, and was developed using Rhomobile’s RhoHub and the Rhodes “write once and run on many” framework. Trackr uses RhoSync to sync data to your device allowing you to manage your work whether or not you have an internet connection. All of your data is synced with Pivotal Tracker the next time you get a connection.

Track-R uses the Pivotal Tracker API, which has allowed developers to create dozens of tools and applications to help extend the functionality of Tracker.

More information about Track-R is available in Koombea’s press release:

We’ve made some minor changes to Pivotal Tracker this week, and added a few new features. As always, we look forward to you feedback on Satisfaction.

Ability to Override Length of an Iteration

Teams that use longer iterations occasionally run into situations where a particular iteration needs to be of a different length than the rest. One example is a Scrum team, running 3 weeks sprints, that decides to cancel a sprint in the second week. To keep Tracker iterations aligned with real-world cycles/springs, it’s now possible to override how long a particular iteration is or will be, in # of weeks.

Click on the iteration start date to override it’s length, or revert an override. An iteration’s date range will appear in yellow if it’s been overridden. Also, Tracker will automatically adjust how many points worth of stories fit into a longer (or shorter) iteration.

Explicit Project Start Date

Normally, the first iteration of a project begins the week of the date of the first accepted story. For multi-week iterations, it’s sometimes desirable to specify exactly when the project started. You can now do this, using the Start Date field in your project settings.

If a start date is specified, your project will start on that day, or the date of the first accepted story, whichever is earlier.

Preview Balloon for Story Descriptions

Based on popular demand, the preview balloon is back for stories that have a description (but no comments). Note – you can see a preview for all stories by hovering over the story type and estimate icons.

Story Labels on the Left

We’ve moved the story labels back to the left of story titles. The motivation for moving the labels to the right (in the previous release) was to align story titles vertically, for easier visual scanning. However, we received a lot of feedback that this made it harder to see groups of related stories, for which labels are commonly used for.

We may introduce a way to either hide labels, or configure where they appear, but for the time being, we’ve moved them back where they used to be.

Enhanced Project Export

It’s now possible to export a subset of the stories in your project, by choosing whether to include done stories, stories in current/backlog, or the icebox.

Current Day in Points Breakdown Chart

The points breakdown chart now includes data for the current day. Previous day counts are all based on a nightly snapshot, but the current day counts reflect the current state of the project.

These new Points Breakdown charts help you visualize the progress of your project as stories move through different stages of completion. Stories start out as “Unstarted”, then move on to “Started”, “Finished”, “Delivered”, and then “Accepted” (unless they get rejected). The different colored bars show the point totals of the stories that are in each state at the end of each day. As days pass, you would expect the number of unstarted to go down, and the number of accepted to go up. If any of the other groups are especially big, the chart may help you identify bottlenecks in your workflow.

This breakdown is available for both the current iteration and the previous one. You can also use it to visualize the development of your entire project for the last 15, 30, or 60 days.

To access the Points Breakdown charts, click the Reports link on top of the page, or navigate from your project via the Reports option in the View menu.

At Pivotal Labs, we like to keep our Tracker stories as small as possible, so that each story describes a single, concrete feature that delivers incremental value to our project’s customer. With small stories, there is rarely a need to break things down further, but sometimes it’s still useful to keep a to-do list while working on a story. This helps keep track of all the little things you have to do, and lets everyone else on the project know exactly what’s left.

To enable story tasks for your project, go to project settings, and check the ‘enable tasks’ option under Experimental. You should then be able to add tasks to stories, under the description field. Hover over a task to edit it, delete it, or move it up and down. You can also check off a task when it’s complete, but task status does not affect overall story status.

We’ve launched a Tracker Users Group in San Francisco, and the second meetup is on June 24th at 6:30pm at the Pivotal Labs office on Market St.

This second meetup will include a demo for new users; a rundown of the new features rolled out last night and soon to come; and a discussion of Story Estimation, Point scales, and the philosophy behind how they are used in Tracker.

Click the link below to become a member of the group and RSVP. We hope to see you there!