The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
WWW-PivotalTracker-1.00
River stage zero No dependents
++
/ WWW::PivotalTracker

NAME

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

VERSION

1.00

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, <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-2010 Jacob Helwig.

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