Description
This gem allows you to easily use the Pivotal Tracker v5 API.
It’s powered by Faraday and Virtus.
TrackerApi alternatives and similar gems
Based on the "Third-party APIs" category.
Alternatively, view TrackerApi alternatives based on common mentions on social networks and blogs.
-
-
-
-
-
-
-
-
ruby-gmail
A Rubyesque interface to Gmail. Connect to Gmail via IMAP and manipulate emails and labels. Send email with your Gmail account via SMTP. Includes full support for parsing and generating MIME messages. -
-
-
-
-
-
-
-
-
itunes_store_transporter
Upload and manage your assets in the iTunes Store using the iTunes Store’s Transporter (iTMSTransporter). -
-
-
pivotal-tracker-api
This is a Ruby Gem that can be used to communicate with the Pivotal Tracker API v5 -
-
-
Scout Monitoring - Performance metrics and, now, Logs Management Monitoring with Scout Monitoring
* Code Quality Rankings and insights are calculated and provided by Lumnify.
They vary from L1 to L5 with "L5" being the highest.
Do you think we are missing an alternative of TrackerApi or a related project?
README
TrackerApi
This gem allows you to easily use the Pivotal Tracker v5 API.
It’s powered by Faraday and Virtus.
Demonstration
Dash of Agile uses tracker_api to create agile dashboards from Pivotal Tracker projects.
Installation
Add this line to your application's Gemfile:
gem 'tracker_api'
And then execute:
$ bundle install
Or install it yourself as:
$ gem install tracker_api
Basic Usage
client = TrackerApi::Client.new(token: 'my-api-token') # Create API client
client.me.email # Get email for the authenticated person
client.activity # Get a list of all the activity performed the authenticated person
client.notifications # Get notifications for the authenticated person
projects = client.projects # Get all projects
project = client.project(123456) # Find project with given ID
project.activity # Get a list of all the activity performed on this project
project.stories # Get all stories for a project
project.stories(with_state: :unscheduled, limit: 10) # Get 10 unscheduled stories for a project
project.stories(filter: 'requester:OWK label:"jedi stuff"') # Get all stories that match the given filters
project.create_story(name: 'Destroy death star') # Create a story with the name 'Destroy death star'
project.search('Destroy death star') # Get a search result with all epics and stories relevant to the query
story = project.story(847762630) # Find a story with the given ID
story.activity # Get a list of all the activity performed on this story
story.transitions # Get a list of all the story transitions on this story
story.name = 'Save the Ewoks' # Update a single story attribute
story.attributes = { name: 'Save the Ewoks', description: '...' } # Update multiple story attributes
story.add_label('Endor') # Add a new label to an existing story
story.save # Save changes made to a story
story = client.story(117596687) # Get a story with story ID only
story = TrackerApi::Resources::Story.new( client: client,
project_id: 123456,
id: 847762630) # Use the Story resource to get the story
comments = story.comments # comments without first fetching the story
comment = story.create_comment(text: "Use the force!") # Create a new comment on the story
comment = story.create_comment(text: "Use the force again !", # Create a new comment on the story with
files: ['path/to/an/existing/file']) # file attachments
comment.text += " (please be careful)"
comment.save # Update text of an existing comment
comment.delete # Delete an existing comment
comment.create_attachments(files: ['path/to/an/existing/file']) # Add attachments to existing comment
comment.delete_attachments # Delete all attachments from a comment
attachments = comment.attachments # Get attachments associated with a comment
attachments.first.delete # Delete a specific attachment
comment.attachments(reload: true) # Re-load the attachments after modification
task = story.tasks.first # Get story tasks
task.complete = true
task.save # Mark a task complete
review = story.reviews.first # Mark a review as complete
review.status = 'pass'
review.save
epics = project.epics # Get all epics for a project
epic = epics.first
label = epic.label # Get an epic's label
workspaces = client.workspaces # Get person's multi-project workspaces
Eager Loading
See Pivotal Tracker API documentation for how to use the fields parameter.
client = TrackerApi::Client.new(token: 'my-api-token') # Create API client
client.project(project_id, fields: ':default,labels(name)') # Eagerly get labels with a project
client.project(project_id, fields: ':default,epics') # Eagerly get epics with a project
client.project(project_id).stories(fields: ':default,tasks') # Eagerly get stories with tasks
story.comments(fields: ':default,person') # Eagerly get comments and the person that made the comment for a story
Error Handling
TrackerApi::Errors::ClientError is raised for 4xx HTTP status codes
TrackerApi::Errors::ServerError is raised for 5xx HTTP status codes
Warning
Direct mutation of an attribute value skips coercion and dirty tracking. Please use direct assignment or the specialized add_* methods to get expected behavior. https://github.com/solnic/virtus#important-note-about-member-coercions
This will cause coercion and dirty tracking to be bypassed and the new label will not be saved.
story = project.story(847762630)
label = TrackerApi::Resources::Label.new(name: 'Special Snowflake')
# BAD
story.labels << label
story.save
# GOOD
story.labels = story.labels.dup.push(label)
story.save
TODO
- Add missing resources and endpoints
- Add create, update, delete for resources
- Error handling for error responses
Semantic Versioning
Given a version number MAJOR.MINOR.PATCH, increment the:
- MAJOR version when you make incompatible API changes,
- MINOR version when you add functionality in a backwards-compatible manner, and
- PATCH version when you make backwards-compatible bug fixes.
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
Contributing
Currently this client supports read-only access to Pivotal Tracker. We will be extending it as our use cases require, but are always happy to accept contributions.
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create new Pull Request