Class: Basecamp

Inherits:
Object
  • Object
show all
Defined in:
lib/openwfe/extras/misc/basecamp.rb

Overview

An interface to the Basecamp web-services API. Usage is straightforward:

session = Basecamp.new('your.basecamp.com', 'username', 'password')
puts "projects: #{session.projects.length}"

Defined Under Namespace

Classes: FileUpload, Record

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(url, user_name, password, use_ssl = false) ⇒ Basecamp

Connects



93
94
95
96
97
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 93

def initialize(url, user_name, password, use_ssl = false)
  @use_xml = false
  @user_name, @password = user_name, password
  connect!(url, use_ssl)
end

Instance Attribute Details

#use_xml ⇒ Object

Returns the value of attribute use_xml.



90
91
92
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 90

def use_xml
  @use_xml
end

Instance Method Details

#comment(id) ⇒ Object

Retrieve a specific comment



201
202
203
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 201

def comment(id)
  record "/msg/comment/#{id}"
end

#comments(post_id) ⇒ Object

Return a list of the comments for the specified message.



196
197
198
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 196

def comments(post_id)
  records "comment", "/msg/comments/#{post_id}"
end

#company(id) ⇒ Object

Return information for the company with the given id



115
116
117
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 115

def company(id)
  record "/contacts/company/#{id}"
end

#complete_item(id) ⇒ Object

Marks the given item completed.



231
232
233
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 231

def complete_item(id)
  record "/todos/complete_item/#{id}"
end

#complete_milestone(id) ⇒ Object

Complete the milestone with the given id



300
301
302
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 300

def complete_milestone(id)
  record "/milestones/complete/#{id}"
end

#create_comment(post_id, comment, attachments = []) ⇒ Object

Add a new comment to a message. comment must be a hash describing the comment. You can add attachments to the comment, too, by giving them in an array. See the #post_message method for a description of how to do that.



208
209
210
211
212
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 208

def create_comment(post_id, comment, attachments=[])
  prepare_attachments(attachments)
  record "/msg/create_comment", :comment => comment.merge(:post_id => post_id),
    :attachments => attachments
end

#create_item(list_id, content, responsible_party = nil, notify = true) ⇒ Object

Creates a new to-do item.



241
242
243
244
245
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 241

def create_item(list_id, content, responsible_party=nil, notify=true)
  record "/todos/create_item/#{list_id}",
    :content => content, :responsible_party => responsible_party,
    :notify => notify
end

#create_list(project_id, list) ⇒ Object

Creates a new list using the given hash of list metadata.



248
249
250
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 248

def create_list(project_id, list)
  record "/projects/#{project_id}/todos/create_list", list
end

#create_milestone(project_id, data) ⇒ Object

Create a new milestone for the given project. data must be hash of the values to set, including title, deadline, responsible_party, and notify.



307
308
309
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 307

def create_milestone(project_id, data)
  create_milestones(project_id, [data]).first
end

#create_milestones(project_id, milestones) ⇒ Object

As #create_milestone, but can create multiple milestones in a single request. The milestones parameter must be an array of milestone values as descrbed in #create_milestone.



314
315
316
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 314

def create_milestones(project_id, milestones)
  records "milestone", "/projects/#{project_id}/milestones/create", :milestone => milestones
end

#delete_comment(id) ⇒ Object

Deletes (and returns) the given comment.



222
223
224
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 222

def delete_comment(id)
  record "/msg/delete_comment/#{id}"
end

#delete_item(id) ⇒ Object

Deletes the given item from it’s parent list.



253
254
255
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 253

def delete_item(id)
  record "/todos/delete_item/#{id}"
end

#delete_list(id) ⇒ Object

Deletes the given list and all of its items.



258
259
260
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 258

def delete_list(id)
  record "/todos/delete_list/#{id}"
end

#delete_message(id) ⇒ Object

Deletes the message with the given id, and returns it.



191
192
193
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 191

def delete_message(id)
  record "/msg/delete/#{id}"
end

#delete_milestone(id) ⇒ Object

Destroys the milestone with the given id.



319
320
321
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 319

def delete_milestone(id)
  record "/milestones/delete/#{id}"
end

#file_categories(project_id) ⇒ Object

Returns the list of file categories for the given project



110
111
112
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 110

def file_categories(project_id)
  records "attachment-category", "/projects/#{project_id}/attachment_categories"
end

#get_list(id) ⇒ Object

Retrieves the specified list, and all of its items.



263
264
265
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 263

def get_list(id)
  record "/todos/list/#{id}"
end

#lists(project_id, complete = nil) ⇒ Object

Return all lists for a project. If complete is true, only completed lists are returned. If complete is false, only uncompleted lists are returned.



269
270
271
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 269

def lists(project_id, complete=nil)
  records "todo-list", "/projects/#{project_id}/todos/lists", :complete => complete
end

#message(*ids) ⇒ Object

Return information about the message(s) with the given id(s). The API limits you to requesting 25 messages at a time, so if you need to get more than that, you’ll need to do it in multiple requests.



135
136
137
138
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 135

def message(*ids)
  result = records("post", "/msg/get/#{ids.join(",")}")
  result.length == 1 ? result.first : result
end

#message_categories(project_id) ⇒ Object

Returns the list of message categories for the given project



105
106
107
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 105

def message_categories(project_id)
  records "post-category", "/projects/#{project_id}/post_categories"
end

#message_list(project_id, category_id = nil) ⇒ Object

Returns a summary of all messages in the given project (and category, if specified). The summary is simply the title and category of the message, as well as the number of attachments (if any).



143
144
145
146
147
148
149
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 143

def message_list(project_id, category_id=nil)
  url = "/projects/#{project_id}/msg"
  url << "/cat/#{category_id}" if category_id
  url << "/archive"
  
  records "post", url
end

#milestones(project_id, find = "all") ⇒ Object

Returns a list of all milestones for the given project, optionally filtered by whether they are completed, late, or upcoming.



325
326
327
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 325

def milestones(project_id, find="all")
  records "milestone", "/projects/#{project_id}/milestones/list", :find => find
end

#move_item(id, to) ⇒ Object

Repositions an item to be at the given position in its list



274
275
276
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 274

def move_item(id, to)
  record "/todos/move_item/#{id}", :to => to
end

#move_list(id, to) ⇒ Object

Repositions a list to be at the given position in its project



279
280
281
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 279

def move_list(id, to)
  record "/todos/move_list/#{id}", :to => to
end

#people(company_id, project_id = nil) ⇒ Object

Return an array of the people in the given company. If the project-id is given, only people who have access to the given project will be returned.



121
122
123
124
125
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 121

def people(company_id, project_id=nil)
  url = project_id ? "/projects/#{project_id}" : ""
  url << "/contacts/people/#{company_id}"
  records "person", url
end

#person(id) ⇒ Object

Return information about the person with the given id



128
129
130
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 128

def person(id)
  record "/contacts/person/#{id}"
end

#post_message(project_id, message, notify = [], attachments = []) ⇒ Object

Create a new message in the given project. The message parameter should be a hash. The email_to parameter must be an array of person-id’s that should be notified of the post.

If you want to add attachments to the message, the attachments parameter should be an array of hashes, where each has has a :name key (optional), and a :file key (required). The :file key must refer to a Basecamp::FileUpload instance.

msg = session.post_message(158141,
   { :title => "Requirements",
     :body => "Here are the requirements documents you asked for.",
     :category_id => 2301121 },
   [john.id, martha.id],
   [ { :name => "Primary Requirements",
       :file => Basecamp::FileUpload.new('primary.doc", File.read('primary.doc')) },
     { :file => Basecamp::FileUpload.new('other.doc', File.read('other.doc')) } ])



168
169
170
171
172
173
174
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 168

def post_message(project_id, message, notify=[], attachments=[])
  prepare_attachments(attachments)
  record "/projects/#{project_id}/msg/create",
    :post => message,
    :notify => notify,
    :attachments => attachments
end

#projects ⇒ Object

Return the list of all accessible projects.



100
101
102
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 100

def projects
  records "project", "/project/list"
end

#record(path, parameters = {}) ⇒ Object

A convenience method for wrapping the result of a query in a Record object. This assumes that the result is a singleton, not a collection.



360
361
362
363
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 360

def record(path, parameters={})
  result = request(path, parameters)
  (result && !result.empty?) ? Record.new(result.keys.first, result.values.first) : nil
end

#records(node, path, parameters = {}) ⇒ Object

A convenience method for wrapping the result of a query in Record objects. This assumes that the result is a collection–any singleton result will be wrapped in an array.



368
369
370
371
372
373
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 368

def records(node, path, parameters={})
  result = request(path, parameters).values.first or return []
  result = result[node] or return []
  result = [result] unless Array === result
  result.map { |row| Record.new(node, row) }
end

#request(path, parameters = {}, second_try = false) ⇒ Object

Make a raw web-service request to Basecamp. This will return a Hash of Arrays of the response, and may seem a little odd to the uninitiated.



343
344
345
346
347
348
349
350
351
352
353
354
355
356
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 343

def request(path, parameters = {}, second_try = false)
  response = post(path, convert_body(parameters), "Content-Type" => content_type)

  if response.code.to_i / 100 == 2
    result = XmlSimple.xml_in(response.body, 'keeproot' => true,
      'contentkey' => '__content__', 'forcecontent' => true)
    typecast_value(result)
  elsif response.code == "302" && !second_try
    connect!(@url, !@use_ssl)
    request(path, parameters, true)
  else
    raise "#{response.message} (#{response.code})"
  end
end

#uncomplete_item(id) ⇒ Object

Marks the given item uncompleted.



236
237
238
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 236

def uncomplete_item(id)
  record "/todos/uncomplete_item/#{id}"
end

#uncomplete_milestone(id) ⇒ Object

Uncomplete the milestone with the given id



330
331
332
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 330

def uncomplete_milestone(id)
  record "/milestones/uncomplete/#{id}"
end

#update_comment(id, comment, attachments = []) ⇒ Object

Update the given comment. Attachments follow the same format as #post_message.



215
216
217
218
219
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 215

def update_comment(id, comment, attachments=[])
  prepare_attachments(attachments)
  record "/msg/update_comment", :comment_id => id,
    :comment => comment, :attachments => attachments
end

#update_item(id, content, responsible_party = nil, notify = true) ⇒ Object

Updates the given item



284
285
286
287
288
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 284

def update_item(id, content, responsible_party=nil, notify=true)
  record "/todos/update_item/#{id}",
    :item => { :content => content }, :responsible_party => responsible_party,
    :notify => notify
end

#update_list(id, list) ⇒ Object

Updates the given list’s metadata



291
292
293
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 291

def update_list(id, list)
  record "/todos/update_list/#{id}", :list => list
end

#update_message(id, message, notify = [], attachments = []) ⇒ Object

Edit the message with the given id. The message parameter should be a hash. The email_to parameter must be an array of person-id’s that should be notified of the post.

The attachments parameter, if used, should be the same as described for #post_message.



182
183
184
185
186
187
188
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 182

def update_message(id, message, notify=[], attachments=[])
  prepare_attachments(attachments)
  record "/msg/update/#{id}",
    :post => message,
    :notify => notify,
    :attachments => attachments
end

#update_milestone(id, data, move = false, move_off_weekends = false) ⇒ Object

Updates an existing milestone.



335
336
337
338
339
 
# File 'lib/openwfe/extras/misc/basecamp.rb', line 335

def update_milestone(id, data, move=false, move_off_weekends=false)
  record "/milestones/update/#{id}", :milestone => data,
    :move_upcoming_milestones => move,
    :move_upcoming_milestones_off_weekends => move_off_weekends
end