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.
- 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 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.