Class: Basecamp

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

Overview

A Ruby library for working with the Basecamp web-services API.

For more information about the Basecamp web-services API, visit:

http://developer.37signals.com/basecamp

NOTE: not all of Basecamp’s web-services are accessible via REST. This library provides access to RESTful services via ActiveResource. Services not yet upgraded to REST are accessed via the Basecamp class. Continue reading for more details.

Establishing a Connection

The first thing you need to do is establish a connection to Basecamp. This requires your Basecamp site address and your login credentials. Example:

Basecamp.establish_connection!('you.grouphub.com', 'username', 'password')

This is the same whether you’re accessing using the ActiveResource interface, or the legacy interface.

Using the REST interface via ActiveResource

The REST interface is accessed via ActiveResource, a popular Ruby library that implements object-relational mapping for REST web-services. For more information on working with ActiveResource, see:

* http://api.rubyonrails.org/files/activeresource/README.html
* http://api.rubyonrails.org/classes/ActiveResource/Base.html

Finding a Resource

Find a specific resource using the find method. Attributes of the resource are available as instance methods on the resulting object. For example, to find a message with the ID of 8675309 and access its title attribute, you would do the following:

m = Basecamp::Message.find(8675309)
m.title # => 'Jenny'

To find all messages for a given project, use find(:all), passing the project_id as a parameter to find. Example:

messages = Basecamp::Message.find(:all, params => { :project_id => 1037 })
messages.size # => 25

Creating a Resource

Create a resource by making a new instance of that resource, setting its attributes, and saving it. If the resource requires a prefix to identify it (as is the case with resources that belong to a sub-resource, such as a project), it should be specified when instantiating the object. Examples:

m = Basecamp::Message.new(:project_id => 1037)
m.category_id = 7301
m.title = 'Message in a bottle'
m.body = 'Another lonely day, with no one here but me'
m.save # => true

c = Basecamp::Comment.new(:post_id => 25874)
c.body = 'Did you get those TPS reports?'
c.save # => true

You can also create a resource using the create method, which will create and save it in one step. Example:

Basecamp::TodoItem.create(:todo_list_id => 3422, :contents => 'Do it')

Updating a Resource

To update a resource, first find it by its id, change its attributes, and save it. Example:

m = Basecamp::Message.find(8675309)
m.body = 'Changed'
m.save # => true

Deleting a Resource

To delete a resource, use the delete method with the ID of the resource you want to delete. Example:

Basecamp::Message.delete(1037)

Attaching Files to a Resource

If the resource accepts file attachments, the attachments parameter should be an array of Basecamp::Attachment objects. Example:

a1 = Basecamp::Attachment.create('primary', File.read('primary.doc'))
a2 = Basecamp::Attachment.create('another', File.read('another.doc'))

m = Basecamp::Message.new(:project_id => 1037)
...
m.attachments = [a1, a2]
m.save # => true

Using the non-REST inteface

The non-REST interface is accessed via instance methods on the Basecamp class. Ensure you’ve established a connection, then create a new Basecamp instance and call methods on it. Object attributes are accessible as methods. Example:

session = Basecamp.new
person = session.person(93832) # => #<Record(person)..>
person.first_name # => "Jason"

Defined Under Namespace

Classes: Attachment, Category, Comment, Company, Connection, Message, Person, Project, Record, Resource, TimeEntry, TodoItem, TodoList

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Basecamp

Returns a new instance of Basecamp.



494
495
496
 
# File 'lib/basecamp.rb', line 494

def initialize
  @use_xml = false
end

Class Attribute Details

.password ⇒ Object (readonly)

Returns the value of attribute password.



468
469
470
 
# File 'lib/basecamp.rb', line 468

def password
  @password
end

.site ⇒ Object (readonly)

Returns the value of attribute site.



468
469
470
 
# File 'lib/basecamp.rb', line 468

def site
  @site
end

.use_ssl ⇒ Object (readonly)

Returns the value of attribute use_ssl.



468
469
470
 
# File 'lib/basecamp.rb', line 468

def use_ssl
  @use_ssl
end

.user ⇒ Object (readonly)

Returns the value of attribute user.



468
469
470
 
# File 'lib/basecamp.rb', line 468

def user
  @user
end

Instance Attribute Details

#use_xml ⇒ Object

Returns the value of attribute use_xml.



465
466
467
 
# File 'lib/basecamp.rb', line 465

def use_xml
  @use_xml
end

Class Method Details

.connection ⇒ Object 



483
484
485
 
# File 'lib/basecamp.rb', line 483

def connection
  @connection || raise('No connection established')
end

.establish_connection!(site, user, password, use_ssl = false) ⇒ Object 



470
471
472
473
474
475
476
477
478
479
480
481
 
# File 'lib/basecamp.rb', line 470

def establish_connection!(site, user, password, use_ssl = false)
  @site     = site
  @user     = user
  @password = password
  @use_ssl  = use_ssl

  Resource.user = user
  Resource.password = password
  Resource.site = (use_ssl ? "https" : "http") + "://" + site

  @connection = Connection.new(self)
end

.get_token ⇒ Object 



487
488
489
490
491
 
# File 'lib/basecamp.rb', line 487

def get_token
  response = @connection.get('/me.xml')
  xml = XmlSimple.xml_in(response.body)
  xml['token'][0]
end

Instance Method Details

#complete_milestone(id) ⇒ Object

Complete the milestone with the given id



552
553
554
 
# File 'lib/basecamp.rb', line 552

def complete_milestone(id)
  record "/milestones/complete/#{id}"
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.



528
529
530
 
# File 'lib/basecamp.rb', line 528

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 described in #create_milestone.



535
536
537
 
# File 'lib/basecamp.rb', line 535

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

#delete_milestone(id) ⇒ Object

Destroys the milestone with the given id.



547
548
549
 
# File 'lib/basecamp.rb', line 547

def delete_milestone(id)
  record "/milestones/delete/#{id}"
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.



521
522
523
 
# File 'lib/basecamp.rb', line 521

def milestones(project_id, find = 'all')
  records "milestone", "/projects/#{project_id}/milestones/list", :find => find
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.



504
505
506
507
508
 
# File 'lib/basecamp.rb', line 504

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



511
512
513
 
# File 'lib/basecamp.rb', line 511

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

#uncomplete_milestone(id) ⇒ Object

Uncomplete the milestone with the given id



557
558
559
 
# File 'lib/basecamp.rb', line 557

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

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

Updates an existing milestone.



540
541
542
543
544
 
# File 'lib/basecamp.rb', line 540

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