RForce/Salesforce Setup for Dummies

Justification

It took me too many hours to set up Salesforce and then use RForce to verify that Ruby could communicate w/ the Salesforce application. Hopefully the distillation that follows here will help pave the way for others. I explain very little "why"; but being able to see something "that works" may be helpful to your understanding.

Preconditions

• You have no Salesforce account.
• You have not installed RForce
• You have Ruby 1.8.7 installed and am reasonably Ruby-fluent.
  

Here's what we're going to accomplish:

• Create a developer Salesforce account and verify there is data entered into it.
  
• Grab the RForce gem.
• Write an unit test to retrieve data from the Salesforce account that was set up.

Detailed Steps

Create a Salesforce Developers Account

You will need an email account:

1. Browse http://www.salesforce.com/platform/developers.jsp
2. In the middle of the screen:
   

   

   click the large button to the right, "get started".
3. Fill in the requested information and submit.
4. After a minute or two, check the email account you submitted for an email titled: "Salesforce login confirmation" from info@sforce.com. Open the email up and click the link supplied to confirm your developer registration and to log in.
5. The login page will require you to change your password. Do so and submit.
6. The developer landing page will appear (top-left corner shown here):
   
7. At this point, you have just created your own "sandbox" CRM application. Add a record (that we will later retrieve from Ruby) by clicking the Home tab. Your home form will appear:
   
8. In the upper-left corner to the right of the Start Here tab, click the tab.
9. Click the Accounts link.
10. Set the dropdown labeled View to "All Accounts" and click Go.
11. You should see a list of accounts. We're going to pick one to retrieve: sForce. Hence, record the following information for it:
    
    
    
    
    
    
    
    
    
    
    

    Column Name	Value
    Account Name	sForce
    Phone	(415) 901-7000

12. Finally, you're gonna need to set up a security token. At the very top of the same page, click the link Setup. You should see your Personal Setup page.
13. In this part of the page:
    
    click the (magic) link Reset your security token.
14. A page, Reset Security Token, will appear. Click the button Reset Security Token.
15. A page will appear indicating that the security token has been sent to your email address.
16. Wait for the email to arrive at your mailbox. It will be titled Salesforce security token confirmation. The token will appear after "Security Token:". Copy it and save it in a safe place.

We're done with setting up our Salesforce cloud application and our security token.

Install RForce

Use Ruby gem to install RForce. The command is:

gem install rforce

(Don't forget the sudo if you are on the Macintosh.)

Create Test in Test::Unit

Copy the following unit test code into your favorite text editor:



require 'test/unit'
require 'rubygems'
gem 'rforce'
require 'rforce'

include RForce

class RforceRetrievalTest < Test::Unit::TestCase

  def setup
    @binding = RForce::Binding.new 'https://login.salesforce.com/services/Soap/u/16.0'
    userID = 'yourID' # replace w/ your actual Salesforce developer user ID.
    password = 'password' # replace w/ your Salesforce developer account password.
    securityToken = 'token' # replace w/ your security token
    @binding.login userID, (password + securityToken)
  end

  def test_retrieve_an_account
    answer = @binding.search :searchString => "find {sForce} in name fields returning account(id, phone)"
    record = answer[:searchResponse][:result][:searchRecords][:record]
    assert_equal 'Account', record[:type]
    assert_equal '(415) 901-7000', record[:Phone]
  end

end


Put this file where your unit test files belong in a Ruby project, run it, and verify that you can retrieve data from your new Salesforce application.

Enjoy!