“Setting up your Ruby on Rails environment for Force.com “

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 Force.com toolkit for Ruby is a library (called a gem in Ruby parlance) that speaks to the Force.com 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 – http://rubyinstaller.org/downloads/ .  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 Force.com 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 Force.com 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 Force.com 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 Force.com.

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 githubhere.
  • Examine the source of the Force.com 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 Force.com and database.com.  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.

“Setting up your Ruby on Rails environment for Force.com “

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s