/ 
WWW-PivotalTracker-0.13
River stage zero No dependents
/ WWW::PivotalTracker

NAME

WWW::PivotalTracker - Functional interface to Pivotal Tracker http://www.pivotaltracker.com/

SYNOPSIS

This module provides simple methods to interact with the Pivotal Tracker API.

use WWW::PivotalTracker qw/
    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->{'message'};

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'}};
}
else {
    print $result->{'errors'};
}

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:
    requeser:"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.

AUTHOR

Jacob Helwig, <jhelwig at cpan.org>

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:

ACKNOWLEDGEMENTS

Chris Hellmuth

COPYRIGHT & LICENSE

Copyright 2008 Jacob Helwig.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.