NAME WWW::PivotalTracker - Functional interface to Pivotal Tracker http://www.pivotaltracker.com/ INSTALLATION To install this module, run the following commands: perl Makefile.PL make make test make install VERSION 0.17 SYNOPSIS This module provides simple methods to interact with the Pivotal Tracker API. use WWW::PivotalTracker qw/ add_note add_story all_stories delete_story project_details show_story stories_for_filter update_story /; my $details = project_details("API Token", "Project ID"); ... EXPORT Nothing is exported by default. See FUNCTIONS for the exportable functions. FUNCTIONS project_details Returns a hashref with the project's name, point scale, number of weeks per iteration, and which day of the week the iterations start on. my $proj = project_details($token, $project_id); print "Project name: $proj->{'name'}\n" . "Point scale: $proj->{'point_scale'}\n" . "Weeks per Iteration: $proj->{'iteration_weeks'}\n" . "Iteration start day: $proj->{'start_day'}\n"; show_story Return a hashref with the details of a specific story. my $story = show_story($token, $project_id, $story_id); # If the story doesn't have a particular attribute, then the hash key's # value will be undef. (Ex: description, deadline, labels, notes) $story->{'id'} $story->{'name'} $story->{'description'} # Possibly multi-line string. $story->{'estimate'} # Possible values are results in point_scale # returned by project_details, and -1 if not # estimated, yet. $story->{'current_state'} $story->{'created_at'} $story->{'deadline'} # undef, unless story type is 'release' $story->{'story_type'} # 'feature', 'bug', 'chore', or 'release' $story->{'labels'} # [ 'foo', 'bar', 'baz', ] $story->{'notes'} # [ # { id => 1, author => 'alice', date => 'Dec 20, 2008', text => 'comment', }, # { id => 2, author => 'bob', date => 'Dec 20, 2008', text => 'commenting on your comment', }, # ] $story->{'url'} all_stories Return an arrayref of story hashrefs (see show_story for story hashref details). add_story Create a new story, given a hashref of the story's details, and return a story hashref of the same format as show_story. Possible story details hash keys are: created_at current_state deadline description estimate labels name requested_by story_type The bare minimum to create a new story are "requested_by", and "name". New stories will default to be "feature" stories, unless a "story_type" ("feature", "bug", "chore", or "release") is specified. To add labels, include a comma separated list as the "labels" value. my $story_details = { requested_by => "Bob", name => "Users can request stories.", labels => "label 1, label 2, another label", }; my $story_details_2 = { requested_by => "Alice", name => "Release #1", deadline => "Dec 31, 2008", }; my $story = add_story($token, $project_id, $story_details); my $story_2 = add_story($token, $project_id, $story_details_2); delete_story Delete an existing story. my $result = delete_story($token, $project_id, $story_id); print $result->{'success'}; print $result->{'name'}; stories_for_filter Find all stories given search parameters. my $result = stories_for_filter($token, $project_id, $search_filter); my @stories; if($result->{'success'} eq 'true') { print $result->{'message'} . "\n"; @stories = @{$result->{'stories'}}; } In the example above `@stories' will be an array of story hashrefs. See the description of `show_story' for the details of the hashrefs. Any multi-word terms in the search filter must be enclosed by double quotes. (See http://www.pivotaltracker.com/help: Search) Example: requester:"Jacob Helwig" owner:"Jacob Helwig" mywork:"Jacob Helwig" state:unstarted type:Feature update_story Update aspects of a given story. my $result = update_story($token, $project_id, $story_id, { current_state => 'started' }); See the description of `show_story' for the details of `$result'. add_note Add a note to an existing story. my $result = add_comment($token, $project_id, $story_id, $note); See the description of `show_story' for the details of `$result'. AUTHOR Jacob Helwig, `' BUGS Please report any bugs or feature requests to `bug-www-pivotaltracker at rt.cpan.org', or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-PivotalTracker. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. SUPPORT You can find documentation for this module with the perldoc command. perldoc WWW::PivotalTracker You can also look for information at: * RT: CPAN's request tracker http://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW-PivotalTracker * AnnoCPAN: Annotated CPAN documentation http://annocpan.org/dist/WWW-PivotalTracker * CPAN Ratings http://cpanratings.perl.org/d/WWW-PivotalTracker * Search CPAN http://search.cpan.org/dist/WWW-PivotalTracker/ * Source code git: * Webpage http://github.com/jhelwig/www-pivotaltracker ACKNOWLEDGEMENTS Chris Hellmuth COPYRIGHT & LICENSE Copyright 2008-2010 Jacob Helwig. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.