No description or website provided.
Pull request Compare This branch is even with sergeyenin:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
gemfiles
lib
spec
.gitignore
.rspec
.travis.yml
Gemfile
Guardfile
LICENSE.txt
README.md
Rakefile
TODO
target_process.gemspec

README.md

TargetProcess

Code Climate Travis CI

Ruby wrapper for TargetProcess JSON REST API.

Installation

Add this line to your application's Gemfile:

gem 'target_process'

And then execute:

$ bundle

Or install it yourself as:

$ gem install target_process

Usage

Configuration

For rails usage you may put following code to config/initializers/target_process.rb or use anywhere you need it.

TargetProcess.configure do |config|
  config.domain = "http://ALIAS.tpondemand.com/api/v1/"
  config.username = "USERNAME"
  config.password = "PASSWORD"
end

Do not confuse: PASSWORD and USERNAME - your bugtracker's inner ALIAS.tpondemand.com credentials.

To check configuration:

    > TargetProcess.configuration #=>
    <TargetProcess::Configuration:0x00000004fa7b80
    @domain="http://myacc.tpondemand.com/api/v1/",
    @password="login",
    @username="secret">

Context

To get context you can use #context(options={}) method provided with gem. Examples:

TargetProcess.context # http://myacc.tpondemand.com/api/v1/context/

TargetProcess.context(ids: [1,88]) # http://myacc.tpondemand.com/api/v1/context/?ids=[1,88]

TargetProcess.context(ids: [1,88], acid:"5FCD2783A543047AD90BB28A50EC2152")
# http://myacc.tpondemand.com/api/v1/context/?ids=[1,88]&acid=5FCD2783A543047AD90BB28A50EC2152

CRUD

Here you can browse TP's REST CRUD api summary to find out what fields a required to save new instance or what CRUD operations available with current entity.

Create

>project = TargetProcess::Project.new(name: "FooBar")    # to create it locally.
 =>
<TargetProcess::Project:0x007f32a838c228
 @attributes={},
 @changed_attributes={:name=>"FooBar"}>
>project.save          #to save on server.
 =>
<TargetProcess::Project:0x007f32a8918bb0
 @attributes=
  {:id=>3154,
   :name=>"FooBar",
   :description=>nil,
   :start_date=>nil,
   :end_date=>nil,
   :create_date=>2013-08-09 18:43:52 +0300,
   :modify_date=>2013-08-09 18:43:52 +0300,
   :last_comment_date=>nil,
   :tags=>"",
   :numeric_priority=>1579.0,
   :is_active=>true,
   :is_product=>false,
   :abbreviation=>"FOO",
   :mail_reply_address=>nil,
   :color=>nil,
   :entity_type=>{:id=>1, :name=>"Project"},
   :owner=>{:id=>1, :first_name=>"Administrator", :last_name=>"Administrator"},
   :last_commented_user=>nil,
   :project=>nil,
   :program=>nil,
   :process=>{:id=>3, :name=>"Scrum"},
   :company=>nil,
   :custom_fields=>[]},
 @changed_attributes={}>

We use simple implementation of "dirty attributes", that means only @changed_attributes will be sent to the server. As you can see, some attributes setts by default or calculates with TP's logic. Also not all of it available to modify. To find out which attributes are required, or unmodifiable browse this reference.

Each local instance of TP's entities contains two hashes : @attributes and @changed_attributes. If some value is in @attributes hash it means that this value is the same on server. @changed_attributes, obviously contains values, changed locally. You can access current value of each hash with the key-named getters (Setters also provided).

Example of usage:

role = TargetProcess::Role.find(1)
=> <TargetProcess::Role:0x8a7cad0
 @attributes={:id=>1, :name=>"Developer", :is_pair=>true, :has_effort=>true}
 @changed_attributes={}>

role.name
=> "Developer"

role.name = "Programmer"

role
=> <TargetProcess::Role:0x8a7cad0
 @attributes={:id=>1, :name=>"Developer", :is_pair=>true, :has_effort=>true},
 @changed_attributes={:name=>"Programmer"}>

role.name = "Developer"

role
=> <TargetProcess::Role:0x8a7cad0
 @attributes={:id=>1, :name=>"Developer", :is_pair=>true, :has_effort=>true},
 @changed_attributes={}>

role.name = "Programmer"
=> "Programmer"

role.save       # send changes on server.
=> <TargetProcess::Role:0x8a7cad0
 @attributes={:id=>1, :name=>"Programmer", :is_pair=>true, :has_effort=>true},
 @changed_attributes={}>

Read

Gem provides 3 read methods: .find(id, options={}), .all(options={}), .where(search_condition, options={}) (Yeah, the goal was to make it mostly similar to ActiveRecord).

.find(id, options={})

Return instance with specified id.

>project = TargetProcess::Project.find(2)
# http://username:password@account.tpondemand.com/api/v1/Projects/2
=> <TargetProcess::Project:0x007f32a8a9fe48
 @attributes=
  {:id=>2,
   :name=>"Tau Product - Kanban #1",
                .   .   .
   :program=>{:id=>1, :name=>"tauLine #1"},
   :process=>{:id=>2, :name=>"Kanban"},
   :company=>nil,
   :custom_fields=>[]},
 @changed_attributes={}>

If you want to learn more about available options - browse this guide.

.all(options={})
TargetProcess::Project.all  # will  make a
# http://username:password@account.tpondemand.com/api/v1/Projects/?format=json` request,
# and return an array of TargetProcess::Project instances.

Could be used with options:

TargetProcess::Project.all( take: 5, include: "[Tasks]", append: "[Tasks-Count]")
# will make this request:
# http://kamrad.tpondemand.com/api/v1/projects?format=json&take=5&include=[Tasks]&append=[Tasks-Count]
.where(search_condition, options={})
> TargetProcess::Comment.where('General.Id eq 182') #=>
#http://username:password@account.tpondemand.com/api/v1/comments?format=json&where=General.Id%20eq%20183

You can also use it with options like:

TargetProcess::Comment.where('General.Id eq 182', take: 1)
# http://username:password@account.tpondemand.com/api/v1/comments?format=json&where=General.Id%20eq%20182&take=1

Update

#save method also can be used for updating remote entity. Remember that all attributes in @changed_attributes still not updated on server. After you get remote entity as local instance and modify it, you can update remote entity with #save method:

Example:

>bug = TargetProcess::Bug.find(123)
>bug.description = "new description"
>bug.save

To find out what attributes you can modify browse this reference.

Delete

#delete

Just call it on entity and...it's gone!

>bug  = TargetProcess::Bug.find(347)
>bug.delete #=> true
>TargetProcess::Bug.find(347) #=>  will raise TargetProcess::NotFound error

Metadata

#meta

To get metadata of entity use #meta:

TargetProcess::Userstory.meta
# will make a http://tpruby.tpondemand.com/api/v1/userstories/meta?format=json request.

Errors

ConfigurationError
APIError
|-BadRequest
|-NotFound
|-MethodNotAllowed
|-InternalServerError
|-Forbidden
|-NotImplemented
|-Unauthorized

You can catch APIError or a specific type of error.

Example:

begin
  TargetProcess::Project.all
resque TargetProcess::APIError  #or TargetProcess::APIError::NotFound
  #something awesome
end

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request