New and Ruby gem now available

As of Aug 30, 2011 a new ruby gem, databasedotcom, is available. See the blog post announcement for more details.


Ruby on Rails is an open source framework geared to fast, agile web development. Using the Toolkit for Ruby, it is possible to manipulate data directly from Ruby and easily integrate it with Rails applications.

The Toolkit for Ruby is built on the ASF Soap Adapter Gem, which itself is based on the earlier ActiveSalesforce-Adapter Gem, but offers more functionality and flexibility. It includes several convenience classes for standard objects, Chatter methods and more SOQL options for data queries. The RForcedotcom Gem is now a prerequisite for use, rather than being embedded, which allows for future updates to that functionality to be handled independently.


This article assumes Rails 2.3 development as it was the most current during the toolkit’s development. Rails 3 offers new data functionality and integration into REST APIs and will be covered in a future article.

A functional Ruby on Rails environment is also assumed. For help in getting Ruby on Rails running on your platform, see the following articles, visit the Rails Wiki.

Getting Started

The toolkit requires two other Gems, RForcedotcom and Facets. They can be installed using the gem command. At the time of this writing, toolkit requires the Facets to use 2.8.4 as opposed to the most recent version. To install these two gems, use the following commands:

sudo gem install rforcedotcom

sudo gem install facets –v=2.8.4

To install and use toolkit with your application, update the initalizer in the environment.rb file with “config.gem "asf-soap-adapter", :lib => 'asf-soap-adapter'”, such as: do |config|    
  #additional or existing configuration
  config.gem "asf-soap-adapter", :lib => 'asf-soap-adapter'   

And then, from the project root directory, run:

sudo rake gems:install

This Gem is also backwards compatible with the original ActiveSalesforce-Adapter Gem. To use the original adapter, replace the config.gem "asf-soap-adapter", :lib => 'asf-soap-adapter' declaration with config/environment.rb with config.gem “asf-soap-adapter”, :lib => “activerecord-activesalesforce-adapter“ in do |config| section.

In order to access data on, add the following entry to database.yml:

    adapter: activesalesforce
    username: <username>
    password: <password+security token>
    api_version: 20.0

Using the username and password for the user with the correct profile to access the data you need. URL and API version are optional. To use a sandbox org, enter for URL. API version will default to 20, update it to access a specific version of the API.

Testing The Toolkit

Once installed, the toolkit can be testing by running the console. From the project root, run...

script/console enter the console. Since the toolkit comes equipped with several convenience classes which form models for the standard objects, the following can be run directly from the console without generating any new models:

>> Salesforce::Contact.first

And if everything is configured correctly, it should respond with data:

-> <Salesforce::Contact id: "003T000000GqvJsIAJ", ... >

Adding Custom Objects

To add custom objects for use with an application, generate the model using the Salesforce namespace, for instance:

script/generate model Salesforce::CustomObject

And update the resulting model file to run set_table_name:

class Salesforce::CustomObject < Salesforce::SfBase     
  set_table_name ‘CustomObject’  
  # must be a valid Salesforce Table, otherwise, it will complain.   

Note that the use of “__c” from the naming convention does not apply within the Ruby code. The toolkit will translate as necessary. In addition, due to a constraint imposed by the ActiveRecord, custom objects with an underscore ('_') in their name (eg: Book_Review) are not supported.

Adding Views and Controllers

It’s possible to generate scaffold from the toolkit's models with a few edits. For example, to create some baseline code for editing Contact information:

script/generate scaffold Salesforce::Contact first_name:string last_name:string phone:string

Make sure that any view is properly referring to the Salesforce namespace, for example:

<td><%= link_to 'Edit', edit_salesforce_contact_path(h %> <%=h contact.first_name %></td>

And have routes.rb acknowledge the namespace as well, by adding:

map.namespace :salesforce do |salesforce|
  	salesforce.resources :contacts

Since the toolkit does not require a local database for use, some of the controller methods will need to be altered form the normal. In this example, to update a record we get the salesforce_contact param, create an instance of a standard contact object, and then save it back to Salesforce (as opposed to the normal method of updating existing attributes.

# PUT /salesforce_contacts/1
# PUT /salesforce_contacts/1.xml
  def update
    @contact = Salesforce::Contact.update(params[:id], params[:salesforce_contact]) 

    respond_to do |format|
      if @contact.update_attributes(params[:contact])
        format.html { redirect_to(@contact, :notice => 'Salesforce::Contact was successfully updated.') }
        format.xml  { head :ok }
        format.html { render :action => "edit" }
        format.xml  { render :xml => @contact.errors, :status => :unprocessable_entity }

Enabling Session Authentication

Controllers can be enabled to use session IDs for authentication. To use this feature, add the following to /app/controllers/application.rb:

class ApplicationController < ActionController::Base
  before_filter ActiveSalesforce::SessionIDAuthenticationFilter 

Chatter Support

To avoid repetitive queries to find the appropriate data for chatter feeds, a convenience utility has been included to simplify the process. For example:

chatter_feed_finder =
 # The following two lines shows how to get the You can replace it with your

account_feed = Salesforce::AccountFeed.first

object_id =

feed_no_attachment = chatter_feed_finder.get_all_chatter_feeds_without_attachments(object_id, 'Account', user.connection.binding, 'test-session-id')

The following methods are included:

chatter_feed_finder.get_all_chatter_feeds_with_attachments(object_id, object_type, binding, directory_name, limit, get_attachment)
chatter_feed_finder.get_all_chatter_feeds_without_attachments(object_id, object_type, binding, directory_name, limit)
chatter_feed_finder.get_single_chatter_feed_with_attachment(feedpost_id, feed_type, binding, directory_name, limit)


The Toolkit for Ruby allows a Rails developer to take a new application and integrate with data quickly and easily. It provides an update to previous GEMs by adding more flexibility and configuration and several new utilities to make development less repetitive and simplifying access.

Additionally, a new REST based adapter has been made available, which addresses the underscore "_" problem associated with this SOAP adapter. The new adapter is called asf-rest-adapter. The source code is on Github.


About the Authors

Raymond Gao is a Ruby expert and Cloud Computing consultant. He is a dedicated open-source project developer. Raymond developed the original asf-soap-adapter GEM from which the Ruby Toolkit sprang. (The new REST adapter is also developed by him.) Catch him on his blog or, at least at the time of this writing, in France. His organization is called Are4Us Technologies.

Josh Birk is a Developer Evangelist at and wrangler of code for everything from Ruby to Flex. Follow up with him on the blog or via Twitter.