yltsrc / targetprocess-ruby

TargetProcess

[![Code Climate] (https://codeclimate.com/github/Kamrad117/targetprocess-ruby.png)] (https://codeclimate.com/github/Kamrad117/targetprocess-ruby) [![Travis CI] (https://api.travis-ci.org/Kamrad117/targetprocess-ruby.png?branch=master)] (https://travis-ci.org/Kamrad117/targetprocess-ruby)

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:[email protected]/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:[email protected]/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:[email protected]/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:[email protected]/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