Class: Kanbanize::API

Inherits:
Object
  • Object
show all
Includes:
HTTParty
Defined in:
lib/kanbanize/api.rb

Overview

Low level API calls

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(apikey = nil) ⇒ API

Returns a new instance of API.

Parameters:

  • apikey (String) (defaults to: nil)

    the API key to use to connect to the Kanbanize API


19
20
21
22
# File 'lib/kanbanize/api.rb', line 19

def initialize(apikey = nil )
  set_apikey(apikey)
  set_proxy
end

Instance Attribute Details

#apikeyString (readonly)

Returns the API key used for API calls.

Returns:

  • (String)

    the API key used for API calls


16
17
18
# File 'lib/kanbanize/api.rb', line 16

def apikey
  @apikey
end

Instance Method Details

#get_all_tasks(board_id, options = {}) ⇒ Array<Hash>

Get tasks from a board

Format of the returned array:

[
  {
    'taskid' => '1',
    'position' => '0',
    'type' => 'Feature request',
    'assignee' => 'karouf',
    'title' => 'Write Api specs',
    'description' => '',
    'subtasks' => '1',
    'subtaskscomplete' => '0',
    'color' => '#b3b340',
    'priority' => 'Average',
    'size' => null,
    'deadline' => null,
    'deadlineoriginalformat' => null,
    'extlink' => null,
    'tags' => null,
    'columnid' => 'progress_2',
    'laneid' => '7',
    'leadtime' => 42,
    'blocked' => '0',
    'blockedreason' => null,
    'subtaskdetails' => [],
    'columnname' => 'In progress',
    'lanename' => 'Standard',
    'columnpath' => 'In progress',
    'logedtime' => 0
  },
  .
  .
  .
]

Parameters:

  • board_id (Integer)

    the id of the board

  • options (Hash) (defaults to: {})

    options to filter and paginate the tasks to get

Options Hash (options):

  • :page (Integer) — default: 1

    the page number

  • :archive (Boolean) — default: false

    archived tasks or not

  • :subtasks (Boolean) — default: false

    get subtasks or not

  • :from (Date)

    the date after which you want to get the tasks

  • :to (Date)

    the date before which you want to get the tasks

  • :version (String)

    name of the version

Returns:

  • (Array<Hash>)

    the tasks selected

Raises:

  • (ArgumentError)

    if page number is not an integer

  • (ArgumentError)

    if page number is not > 0

See Also:


211
212
213
214
215
216
217
218
219
220
# File 'lib/kanbanize/api.rb', line 211

def get_all_tasks(board_id, options = {})
  raise ArgumentError if options[:page] && !options[:page].kind_of?(Integer)
  raise ArgumentError if options[:page] && (options[:page] < 1)

  if options.delete(:archive)
    return get_archived_tasks(board_id, options)
  else
    return get_board_tasks(board_id, options)
  end
end

#get_board_activities(board_id, from, to, options = {}) ⇒ Hash

Get events for a board

Format of the returned hash:

{ 'allactivities' => 105,
  'page'          => 1,
  'activities'    => [
                        { 'author'  => 'owner',
                          'event'   => 'Task moved',
                          'text'    => 'From <em>'Backlog'<\/em> to <em>'Next'<\/em>',
                          'date'    => '2013-07-09 16:30:13',
                          'taskid'  => '12'
                        }
                      ]
}

Parameters:

  • board_id (Integer)

    the id of the board

  • from (Date)

    the date after which you want to get the events

  • to (Date)

    the date before which you want to get the events

  • options (Hash) (defaults to: {})

    options to paginate and filter events

Options Hash (options):

  • :page (Integer) — default: 1

    the page number

  • :results (Integer) — default: 30

    the number of results per page

  • :author (String)

    User the events are related to

  • :events (String)

    the type of events

Returns:

  • (Hash)

    the selected events

See Also:


148
149
150
151
152
153
154
155
156
# File 'lib/kanbanize/api.rb', line 148

def get_board_activities(board_id, from, to, options = {})
  uri = "/get_board_activities/boardid/#{board_id}/fromdate/#{from}/todate/#{to}"
  uri += "/page/#{options[:page]}" if options[:page]
  uri += "/resultsperpage/#{options[:results]}" if options[:results]
  uri += "/author/#{options[:author]}" if options[:author]
  uri += "/eventtype/#{options[:events]}" if options[:events]

  post(uri)
end

#get_board_settings(board_id) ⇒ Hash

Get the settings for a board

Format of the returned hash:

{  'usernames' => ['owner'],
   'templates' => ['Bug','Feature','Support'],
   'types'     => ['Bug','Feature request','Support request']
}

Parameters:

  • board_id (Integer)

    the id of the board

Returns:

  • (Hash)

    the settings of the board

See Also:


113
114
115
# File 'lib/kanbanize/api.rb', line 113

def get_board_settings(board_id)
  post("/get_board_settings/boardid/#{board_id}")
end

#get_board_structure(board_id) ⇒ Hash

Get the structure of a board

Format of the returned hash:

{ 'columns' => [{
                  'position'    => '0',
                  'lcname'      => 'Column name',
                  'description' => 'A nice vertical column',
                  'tasksperrow' => '3'
                }],
  'lanes'   => [{
                  'lcname' => 'Urgent',
                  'color' => '#d99f9f',
                  'description' => 'Do now!'
                }]
}

Parameters:

  • board_id (Integer)

    the id of the board

Returns:

  • (Hash)

    the columns and lanes of the board

See Also:


92
93
94
# File 'lib/kanbanize/api.rb', line 92

def get_board_structure(board_id)
  post("/get_board_structure/boardid/#{board_id}")
end

#get_projects_and_boardsHash

Get projects and corresponding boards

Format of the returned hash:

{ 'projects' => [
                  { 'name'    => 'Kanban project',
                    'id'      => '1',
                    'boards'  =>  [
                                    {
                                      'name'  => 'Kanban board',
                                      'id'    => '2'
                                    }
                                  ]
                  }
                ]
}

63
64
65
# File 'lib/kanbanize/api.rb', line 63

def get_projects_and_boards
  post('/get_projects_and_boards')
end

#get_task_details(board_id, task_id, options = {}) ⇒ Object

Get detailed infos on a task

Format of the returned hash:

{ 'taskid' => '7',
  'title' => 'Write Api specs',
  'description' => '',
  'type' => 'Feature request',
  'assignee' => 'karouf',
  'subtasks' => '1',
  'subtaskscomplete' => '0',
  'color' => '#b3b340',
  'priority' => 'Average',
  'size' => null,
  'deadline' => null,
  'deadlineoriginalformat' => null,
  'extlink' => null,
  'tags' => null,
  'leadtime' => 42,
  'blocked' => '0',
  'blockedreason' => null,
  'columnname' => 'En cours',
  'lanename' => 'Standard',
  'subtaskdetails' => [{  'taskid' => '42',
                          'assignee' => 'None',
                          'title' => 'Some stuff to do',
                          'completiondate' => null
                      }],
  'columnid' => 'progress_2',
  'laneid' => '7',
  'columnpath' => 'En cours',
  'loggedtime' => 0,
  'historydetails' => [
                        {  'eventtype' => 'Unarchive',
                           'historyevent' => 'Task unarchived',
                           'details' => 'Task: Test',
                           'author' => 'karouf',
                           'entrydate' => '27 Jun 13, 10:02',
                           'historyid' => '88'
                        }, ...
                      ]
}

return [Hash] details of the task

Parameters:

  • board_id (Integer)

    the id of the board

  • task_id (Integer)

    the id of the task

  • options (Hash) (defaults to: {})

    options for the history of the task

  • [Boolean] (Hash)

    a customizable set of options

  • [String] (Hash)

    a customizable set of options

See Also:


276
277
278
279
280
281
282
# File 'lib/kanbanize/api.rb', line 276

def get_task_details(board_id, task_id, options = {})
  uri = "/get_task_details/boardid/#{board_id}/taskid/#{task_id}"
  uri += '/history/yes' if options[:history]
  uri += "/event/#{options[:event]}" if options[:event]

  post(uri)
end

#login(email, pass) ⇒ Hash

Log in to the API with the credentials provided

Parameters:

  • email (String)

    the email of the user to login as

  • password (String)

    the password of the user

Returns:

  • (Hash)

    User infos

See Also:


33
34
35
36
37
38
39
# File 'lib/kanbanize/api.rb', line 33

def (email, pass)
  hash = self.class.post("/login/email/#{uri_encode(email)}/pass/#{uri_encode(pass)}/format/json")

  set_apikey(hash['apikey'])

  return hash
end