Setup

Fix Settings

The current version of the batchbook.rb file on github has localhost as the domain. You won’t have much luck accessing the API at the localhost:3000 domain. Hopefully they will update this soon, but if they haven’t just change the batchbook.rb file on lines 41-44 to look like this:

 self.host_format = '%s://%s/%s'
 self.domain_format = '%s.batchbook.com'
 self.path = 'service'
 self.protocol = 'https'

Start Using

To start messing around with this I just run script/console from the terminal to get into my Rails app. Then enter:

require 'batchbook'
BatchBook.account = 'your_account'
BatchBook.token = 'your_api_key'

Creating a New Person With an Email

Creating a person is easy enough.

person = BatchBook::Person.new person.first_name = ‘john’ person.last_name = ‘doe’

But what if you want to add an email address? This WON’T work:

person.email = 'john@mail.com'

That is because Batchbook has this concept of locations. So a person doesn’t have an email address. They have a location labeled “work” which has email, phone, city, etc.

So to add that email address, do this:

location = BatchBook::Location.new
location.label = 'work' ## You need this line or it won't save
location.email = 'john@mail.com'

Now, before you call location.save you need to do one very important thing. The location is a nested attribute of the person, so you need to add a path prefix option. Do this:

If you haven’t already saved your person, do so. This will assign an ID to the person object, which you are going to need.

person.save

ActiveResource then posts the information to http://youraccount.batchbook.com/services/people.xml

Now add the prefix option to the location.

location.prefix_options[:person_id] = person.id

This is part of ActiveResource and will add a prefix onto the url. If you don’t add the prefix, ActiveResource posts to /services/locations.xml. That isn’t what you want. The API needs to get a POST to /services/people/#{the_id_of_the_person}/locations.xml. By adding the prefix_option person_id we tell ActiveResource to add the people/#{the_id_of_the_person} to the front of the locations url.

Now just save.

location.save

That’s it. In hindsight it makes sense. But it sure had me confused last night.