We have recently been migrating from Highrise to Batchbook for our CRM software. Though Batchbook isn’t nearly as pretty as Highrise, it has some killer functionality in regard to integration with other services we use as well as a pretty slick way for adding custom data fields. It also has an API that makes it easy to integrate with our existing apps.
The API has a Ruby wrapper so it should be a snap to implement. Except that there was a documentation failure. It wasn’t that the documentation was bad. It just wasn’t there. So here are a couple of examples to help anyone who might be using the Ruby wrapper. Hopefully this will save you a few hours of scratching your head.
The Ruby wrapper uses ActiveResource, which is pretty slick. The good thing about this endeavor was that I learned a lot more about ActiveResource which I hadn’t really paid attention to until now.
Setup
To start using the library all you need to do is [download the batchbook.rb file](http://github.com/batchblue/batchbook) and stick it somewhere in your app. I add it to the `lib/` directory.
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.
