Daily Archive

What follows are instructions on how to get started with the databasedotcom gem, released yesterday afternoon at Dreamforce.

The examples here will be assuming you use Heroku for hosting and deployment although you can use all of the features mentioned without Heroku if you so chose.

This is also for the most part a tutorial and not a replacement for the existing documentation includes as part of the databasedotcom gem on Github and shared via Ruby docs, which hopefully will be expanded as the gem gets some love.

There are two main components of the current release:

(1) A wrapper for the Force.com REST API which currently works with both Force.com and Database.com
(2) A wrapper for the Chatter API which will not be useful until Winter ’12 (or in orgs w/ api v. 23 already enabled)

There is also an additional controller released separately on Github which provides a class that your controllers (assuming you are using a Rails app) can extend. By doing so they will instantly get access to the Force.com or Database.com backend you are hooking into.

As of right now, the gem only supports Ruby 1.9.x, although support for earlier versions of Ruby is promised within the very near future. Although the development of the gem was commissioned by Salesforce/Heroku, maintenance is less certain and depends largely on your contributions.

The first thing you need to do is include the gem in your app. Add the databasedotcom gem to your Gemfile.

gem 'databasedotcom'

If desired, use the edge version instead of the released gem version. This will allow you to get the latest version (you will probably want this if testing in the next couple of days, not necessarily later once the few warts have been ironed out).

gem 'databasedotcom', :git => "https://github.com/heroku/databasedotcom.git"

I’m assuming you’ve already initialized your app on Heroku. If not, go through the Heroku starter tutorial and create your heroku app.

I also recommend adding ssl to your Heroku app:

heroku addons:add ssl:piggyback

The first thing you need to do is add your credentials. You will need to add remote access for your heroku app in Salesforce (Setup -> Develop -> Remote Access).

Note your consumer key and secret. For the purposes of this gem, the client id is always your consumer key, and client secret is the same as consumer secret.

You can add this information to your app in one of three ways: (1) explicitly passing a hash. (2) Setting environment variables via Heroku (3) setting up a yml file in your config folder with the credentials. I recommend doing (3) unless you have a reason to use one of the other options.

The second thing you need to do to authenticate is do the OAuth handshake.
I recommend using the username and password combination for the user with the appropriate permissions for your org.

These can also be set in your yml file. I recommend also turning on debugging.

This will lead to a file called “databasedotcom.yml” in the config folder with the following info:

client_id: CONSUMER_KEY_FROM_REMOTE_ACCESS
client_secret: SECRET_FROM_REMOTE_ACCESS
username: SALESFORCE_USERNAME
password: PASSWORD_PLUS_SEC_TOKEN
debugging: true

Now make sure that is included and deploy the yml to Heroku.

To actually use the gem I recommend starting by extending the databasedotcom controller. Your code will look like this:

class SObjectNameController < DatabasedotcomController

You can then easily refer to the objects you need in that controller.

For instance in the index method you can do

@users = User.all

Where “User” is now your automagically instantiated SObject class queried via the REST API. The way this works is that if you use a variable (e.g. “User”) that is unknown to the class it will find all of the available SObjects and attempt to instantiate a new instance.

That should be enough to get you started. A bunch of other useful examples are in dburkes’ example code.

One note of caution, there is as of yet no session management for this app, so if your auth token times out you will need to re-authenticate yourself.