Like many of you, I was excited about the announcement regarding Heroku at Dreamforce.  I wanted to learn more about Ruby and Heroku and what better way to learn a new programming language than to write and deploy an application.  Though I found the getting started article useful, it assumes you have a working environment.  This article shows you how you can easily setup a working environment on a windows machine. 

The Big Picture

Before we get started, it is useful to understand how the toolkit fits into the overall Ruby environment. Ruby is a programming language  and Rails is a web application framework.  The toolkit for Ruby is a library (called a gem in Ruby parlance) that speaks to the database via the Web Services API.  Ruby provides several tools like gem for package management and rake a build program similar to make.  


Setting up the Ruby on Rails environment

The first step is to install Ruby.  I downloaded and installed from  this site – .  Run the executable and choose the installation option to add Ruby executable to your path.  I installed it in c:softwareRuby192

Next, open a command window and follow the steps below.  We will be installing various libraries needed to setup our environment.

  •  Install rake.  We will need it later.

    c:softwareRuby192 >  gem install rake

  • Install Rails.  We explicitly specify version 2.3.8 since the toolkit was built against that version.

    c:softwareRuby192 >  gem install -v=2.3.8 rails

  •  Install hpricot as below.  I had to specify the platform flag since I got an error without it.  

    c:softwareRuby192 >  gem install hpricot –platform=mswin32

  • Install Facets.

    c:softwareRuby192 >  gem install -v=2.8.4 facets

  • Install the Ruby toolkit

    c:softwareRuby192 >  gem install asf-soap-adapter

At this point we have the necessary environment to create a Rails project that uses the toolkit.  Let us test it by creating a new project and making sure that everything is setup properly.

Testing the toolkit 

We start by creating a new rails project

c:softwareRailsExamples > rails test

This creates a new project under the directory test.  We would need to modify two of the files that Rails creates for us.

  • configenvironment.rb – Add the reference to the toolkit.  Your file should look like  this environment.rb file.
  • configdatabase.yml – you need to specify your org credentials.  Add a configuration element called salesforce-default-realm.  The final file should look like this database.yml file.  Do not forget to add the security token to the password element. 

We are now ready to test the connectivity.  Open a command window and go to the root of your project directory.  We will start the console to do our test.

c:softwareRailsExamplestest > ruby scriptconsole

You will now be able to call the different methods in the toolkit.  Let us do a simple query by typing the following in the console.

>> Salesforce::SfBase.query_by_sql("select name from Account") 

If everything is setup correctly, you should see a list of the accounts in your org.  

Congrats!  You now have a working environment to start building your Rails applications that leverages

What next?

  • Download the example referenced in the wiki article.  You can either download the source or use git a distributed source code control tool.  You can find more information on git and github here.
  • Examine the source of the toolkit – especially sf_base.rb an sf_utility.rb to get an idea of the methods available.  The toolkit is available  here on github.
  • Build your own application and deploy on Heroku.  I will be examining this in a later blog.  

I hope this blog saves you some time as you begin your Ruby journey with and  I am excited about the possibilities. Finally, I would like to thank my friend Ray Gao for helping me with some of the issues I ran into while building my first Ruby app.



tagged , , , Bookmark the permalink. Trackbacks are closed, but you can post a comment.
  • Ajay TS

    Trivial syntax issue. You need to be in bin folder to run ‘gem’

  • Nick Simha

    Ajay – just add rubybin to your PATH and you will be able to run it from anywhere.

  • Vadim

    Hello. How to run the same with Rails3? Is it possible as for now?

  • Tim

    I got it to work locally, but when I push to heroku…it dies. Heroku overwrites the database.yml, so I tried to create separate .yml files but am unable to load them using the config block in initializer.
    How do you do it?

  • Kunjan

    I am getting error while installing rake using gem install rake command.
    The error says: While executing gem … (Zlib::GZipFile::Error) not in gzip format.
    If you could guide me to resolve the above error to install all the steps successfully then it will be really helpful for me and it will be highly appreciated.
    Thanks in advance,

  • Kunjan

    Please let me know asf-soap-adapter is useful for standard objects only? If it is possible to use custom object also using this api then please let me know how ?
    Thanks in advance,

  • umesh chaudhari

    hi can we deploy our ruby on rails application on
    or do we need to deploy it on heroku??
    what is the use of salesforce API then for ruby on rails??

  • Harshit

    I am a newbie to Heroku, but I started writing about my learning and experiments with Salesforce. Here are couple of post on my blog for reference.