node-pivotal : Node.JS API Library for PivotalTracker
License: MIT
To install:
npm install pivotal
To use:
var pivotal = ;pivotal;
You can also retrieve the token initially by using the pivotal.getToken function
Contributing
When making changes to the library, please run make doc
before submitting pull requests.
Tests
Tests are located in test/ directory. To run them you need to install the required dependencies
npm install
and either set your pivotal api-token as a variable
export token=xxxxxxxxxxxxxx
or your username and password (which will result in an additional test for creating the token)
export username=tester export password=testpw
for testing against a specific project/story/member
export project_id=123456 export story_id=9876546 export member_id=192837
finally run the tests using:
make test
For more information:
API methods
For examples see tests/test.js
pivotal.getToken : retrieve a user's token
ref: https://www.pivotaltracker.com/help/api?version=v3#retrieve_token_post
Arguments
- user : user name (email)
- pass : the user's password
pivotal.useToken : set the token to use for all Pivotal callso
Arguments
- token: A valid Pivotal Token
pivotal.getActivities: list activities for the projects you have access to
ref: https://www.pivotaltracker.com/help/api?version=v3#get_all_activity
Arguments
- filters : Limits the return data
: project id limit : maximum return entries occurred_since_date : earliest date for return entries newer_than_version : allows restricting the activity feed to only those items that have a greater than supplied version
pivotal.getProjectActivities: list activities for the projects you have access to
ref: https://www.pivotaltracker.com/help/api?version=v3#get_project_activity
Arguments
- project (int) : project id
- filters : Limits the return data
limit : maximum return entries occurred_since_date : earliest date for return entries newer_than_version : allows restricting the activity feed to only those items that have a greater than supplied version
pivotal.getProjects : get all the projects you have access to
ref: https://www.pivotaltracker.com/help/api?version=v3#get_project_all_projects
pivotal.getProject : access a project
ref: https://www.pivotaltracker.com/help/api?version=v3#get_project_info
Arguments
- id (int) : id of the project
pivotal.addProject : create a project
ref: https://www.pivotaltracker.com/help/api?version=v3#add_project
Arguments
- project : Data of the project to add
: The project's name iteration_length (int) : Iteration length no_owner (boolean, optional) : Does the project have an owner?}
pivotal.getMemberships : get the members of this projects
ref: https://www.pivotaltracker.com/help/api?version=v3#get_memberships
Arguments
- projectId (int) : id of the project
pivotal.getMembership : get a single member of this projects
ref: https://www.pivotaltracker.com/help/api?version=v3#get_membership_info
Arguments
- projectId (int) : id of the project
- membershipId (int) : id of the member
pivotal.addMembership : add a member to this projects
ref: https://www.pivotaltracker.com/help/api?version=v3#add_membership
Arguments
- projectId (int) : id of the project
- membershipData : Data of the new member
role : Member or Owner person : Personal information name : Person's full name initials : Name's initials email : E-mail
Note: The user does not have to be in the system already. He will receieve an email asking him to join if he does not have a project already.
pivotal.removeMembership : remove a single member of this projects
ref: https://www.pivotaltracker.com/help/api?version=v3#remove_membership
Arguments
- projectId (int) : id of the project
- membershipId (int) : id of the member
pivotal.getIterations : get a project list of iterations
ref: https://www.pivotaltracker.com/help/api?version=v3#get_iterations
Arguments
- projectId (int) : id of the project
- filters : Limits the return data
group : filter by iteration type done|current|backlog|current_backlog limit : maximum return entries offset : start from story num N in the list
pivotal.getDoneIterations: get a project completed iterations
ref: https://www.pivotaltracker.com/help/api?version=v3#get_iterations
Arguments
- projectId (int) : id of the project
- filters : Limits the return data
limit : maximum return entries offset : start from story num N in the list
pivotal.getCurrentIteration : get a project current iteration
ref: https://www.pivotaltracker.com/help/api?version=v3#get_iterations
Arguments
- projectId (int) : id of the project
pivotal.getBacklogIterations: get a project backlog
ref: https://www.pivotaltracker.com/help/api?version=v3#get_iterations
Arguments
- projectId (int) : id of the project
- filters : Limits the return data
limit : maximum return entries offset : start from story num N in the list
pivotal.getCurrentBacklogIterations: get a project backlog and current iterations
ref: https://www.pivotaltracker.com/help/api?version=v3#get_iterations
Arguments
- projectId (int) : id of the project
pivotal.getStories: Get a list of stories for this project
ref: https://www.pivotaltracker.com/help/api?version=v3#get_all_stories
Arguments
- projectId (int) : id of the project
- filters : Limits the return data
limit : maximum return entries offset : start from story num N in the list filter : search string to
pivotal.getStory: Get a story from a project
ref: https://www.pivotaltracker.com/help/api?version=v3#get_story
Arguments
- projectId (int) : id of the project
- storyId (int) : id of the story
pivotal.addStory: Add a story to a project
ref: https://www.pivotaltracker.com/help/api?version=v3#add_story
and
https://www.pivotaltracker.com/help/api?version=v3#link_story
Arguments
- projectId (int) : id of the project
- storyData : data of the story
name : Name of this story story_type : bug feature chore release : number which indicates the level of difficulty of the story description : description labels : Comma-separated list of labels requested_by : Name of the requester should be an existing member person name but I dont know if this is an actual limitation
pivotal.addStoryAttachment: Add a file to a story
ref: https://www.pivotaltracker.com/help/api?version=v3#upload_attachment
Arguments
- projectId (int) : id of the project
- storyId (int) : id of the story
- fileData : information of file to upload
name : filename of the file after upload path : path to the file on disk data : if no path is provided one may simply put the data of the file in there instead
pivotal.addStoryComment: Add a comment to a story
ref: https://www.pivotaltracker.com/help/api?version=v3#add_note
Arguments
- projectId (int) : id of the project
- storyId (int) : id of the story
- comment (string) : The text of the comment to add
pivotal.updateStory: Update story infos and/or move a story to a different project
ref: https://www.pivotaltracker.com/help/api?version=v3#update_story
Arguments
- projectId (int) : id of the project
- storyData : data of the story
project_id : Id of the project name : Name of this story story_type : bug feature chore release : number which indicates the level of difficulty of the story description : description labels : Comma-separated list of labels requested_by : Name of the requester should be an existing member person name but I dont know if this is an actual limitation
pivotal.moveStory: move a story in the list of priority
ref: https://www.pivotaltracker.com/help/api?version=v3#move_stories
Arguments
- projectId (int) : id of the project
- storyId (int) : id of the story
- moveData : Information on how the move should happen
target : Id of the destination story move : before or
pivotal.removeStory: remove a story from a project
ref: https://www.pivotaltracker.com/help/api?version=v3#delete_story
Arguments
- projectId (int) : id of the project
- storyId (int) : id of the story
pivotal.deliverAllFinishedStories: self-explanatory
ref: https://www.pivotaltracker.com/help/api?version=v3#deliver_all_finished
Arguments
- projectId (int) : id of the project
pivotal.getTasks: Get tasks for a story
ref: https://www.pivotaltracker.com/help/api?version=v3#view_task
Arguments
- projectId (int) : id of the project
- storyId (int) : id of the story
pivotal.getTask: Get a task from a story
ref: https://www.pivotaltracker.com/help/api?version=v3#view_task
Arguments
- projectId (int) : id of the project
- storyId (int) : id of the story
- taskId (int) : id of the task
pivotal.addTask : add a task to a story
ref: https://www.pivotaltracker.com/help/api?version=v3#add_task
Arguments
- projectId (int) : id of the project
- storyId (int) : id of the story
- taskData : data of the task
description : text of the task complete : true of false
pivotal.updateTask : add a task to a story
ref: https://www.pivotaltracker.com/help/api?version=v3#update_task
Arguments
- projectId (int) : id of the project
- storyId (int) : id of the story
- taskId (int) : id of the task
- taskData : data of the task
description : text of the task complete : true of false
pivotal.removeTask : remove a task from a story
ref: https://www.pivotaltracker.com/help/api?version=v3#delete_task
Arguments
- projectId (int) : id of the project
- storyId (int) : id of the story
- taskId (int) : id of the task