Notes on using sforce with ruby

First download the sforce API documentation from http://www.sforce.com/us/docs/sforce60/sforce_API.pdf

Next download latest version of http-access2 from http://raa.ruby-lang.org/project/http-access2.

Install http-access2 with:

    $ cd ~/work
    $ tar xzvf ~/downloads/http-access-2_0_5.tar.gz
    $ cd http-access_2_0_5
    $ sudo ruby install.rb

Download the latest version of soap4r from http://raa.ruby-lang.org/project/soap4r

Install soap4r with:

    $ cd ~/work
    $ tar xzvf ~/downloads/http-access-2_0_5.tar.gz
    $ cd http-access_2_0_5
    $ sudo ruby install.rb

Copy the wsdl2ruby.rb and xsd2ruby.rb scripts someplace useful:

    $ sudp cp bin/*.rb /usr/local/bin

Make a working directory for your project:

    $ mkdir ~/work/myproj

Download the enterprise wsdl from salesforce.com. I think you need to login to salesforce as an administrator (alternately get a developer login on the sforce site and download the partner wsdl file). After logging in, go to "Setup" (upper right hand corner) then to "Integrate" (left-hand navigation) then to "WSDL Generator". Save the resulting file as ~/work/myproj/enterprise.wsdl.xml.

Create the ruby bindings with:

    $ /usr/local/bin/wsdl2ruby.rb --type client --wsdl enterprise.wsdl.xml

This creates the following files:

    default.rb                  # Class definition file
    defaultDriver.rb            # Driver file (includes default.rb)
    SforceServiceClient.rb      # Sample client (includes defaultDriver.rb)

The sample client isn't terribly useful as is, because the sforce api requires you to change the default endpoint and rewrite the session id in the SOAP header before you can use the API.

I created a new driver file called "sforceDriver.rb" that contained the following:

    require 'defaultDriver.rb'
    require 'soap/header/simplehandler'

    class SessionHeaderHandler < SOAP::Header::SimpleHandler

      HeaderName = XSD::QName.new('urn:partner.soap.sforce.com', 'SessionHeader')

      attr_accessor :sessionid

      def initialize
        super(HeaderName)
        @sessionid = nil
      end

      def on_simple_outbound
        if @sessionid
          {'sessionId' => @sessionid}
        else
          nil       # no header
        end
      end
    end

    class CallOptionsHandler < SOAP::Header::SimpleHandler

      HeaderName = XSD::QName.new('urn:partner.soap.sforce.com', 'CallOptions')

      attr_accessor :client

      def initialize
        super(HeaderName)
        @client = nil
      end

      def on_simple_outbound
        if @client
          {'client' => @client}
        else
          nil       # no header
        end
      end
    end

Now you need to create a certificate file and tell soap to use it.

    $ mkdir soap
    $ cat > soap/property
    client.protocol.http.ssl_config.ca_file = ca.pem
    ^D
    $ cat > ca.pem
    -----BEGIN CERTIFICATE-----
    MIICPDCCAaUCEHC65B0Q2Sk0tjjKewPMur8wDQYJKoZIhvcNAQECBQAwXzELMAkG
    A1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMTcwNQYDVQQLEy5DbGFz
    cyAzIFB1YmxpYyBQcmltYXJ5IENlcnRpZmljYXRpb24gQXV0aG9yaXR5MB4XDTk2
    MDEyOTAwMDAwMFoXDTI4MDgwMTIzNTk1OVowXzELMAkGA1UEBhMCVVMxFzAVBgNV
    BAoTDlZlcmlTaWduLCBJbmMuMTcwNQYDVQQLEy5DbGFzcyAzIFB1YmxpYyBQcmlt
    YXJ5IENlcnRpZmljYXRpb24gQXV0aG9yaXR5MIGfMA0GCSqGSIb3DQEBAQUAA4GN
    ADCBiQKBgQDJXFme8huKARS0EN8EQNvjV69qRUCPhAwL0TPZ2RHP7gJYHyX3KqhE
    BarsAx94f56TuZoAqiN91qyFomNFx3InzPRMxnVx0jnvT0Lwdd8KkMaOIG+YD/is
    I19wKTakyYbnsZogy1Olhec9vn2a/iRFM9x2Fe0PonFkTGUugWhFpwIDAQABMA0G
    CSqGSIb3DQEBAgUAA4GBALtMEivPLCYATxQT3ab7/AoRhIzzKBxnki98tsX63/Do
    lbwdj2wsqFHMc9ikwFPwTtYmwHYBV4GSXiHx0bH/59AhWM1pF+NEHJwZRDmJXNyc
    AA9WjQKZ7aKQRUzkuxCkPfAyAw7xzvjoyVGM5mKf5p/AfbdynMk2OmufTqj/ZA1k
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    MIIDgzCCAuygAwIBAgIQJUuKhThCzONY+MXdriJupDANBgkqhkiG9w0BAQUFADBf
    MQswCQYDVQQGEwJVUzEXMBUGA1UEChMOVmVyaVNpZ24sIEluYy4xNzA1BgNVBAsT
    LkNsYXNzIDMgUHVibGljIFByaW1hcnkgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkw
    HhcNOTcwNDE3MDAwMDAwWhcNMTExMDI0MjM1OTU5WjCBujEfMB0GA1UEChMWVmVy
    aVNpZ24gVHJ1c3QgTmV0d29yazEXMBUGA1UECxMOVmVyaVNpZ24sIEluYy4xMzAx
    BgNVBAsTKlZlcmlTaWduIEludGVybmF0aW9uYWwgU2VydmVyIENBIC0gQ2xhc3Mg
    MzFJMEcGA1UECxNAd3d3LnZlcmlzaWduLmNvbS9DUFMgSW5jb3JwLmJ5IFJlZi4g
    TElBQklMSVRZIExURC4oYyk5NyBWZXJpU2lnbjCBnzANBgkqhkiG9w0BAQEFAAOB
    jQAwgYkCgYEA2IKA6NYZAn0fhRg5JaJlK+G/1AXTvOY2O6rwTGxbtueqPHNFVbLx
    veqXQu2aNAoV1Klc9UAl3dkHwTKydWzEyruj/lYncUOqY/UwPpMo5frxCTvzt01O
    OfdcSVq4wR3Tsor+cDCVQsv+K1GLWjw6+SJPkLICp1OcTzTnqwSye28CAwEAAaOB
    4zCB4DAPBgNVHRMECDAGAQH/AgEAMEQGA1UdIAQ9MDswOQYLYIZIAYb4RQEHAQEw
    KjAoBggrBgEFBQcCARYcaHR0cHM6Ly93d3cudmVyaXNpZ24uY29tL0NQUzA0BgNV
    HSUELTArBggrBgEFBQcDAQYIKwYBBQUHAwIGCWCGSAGG+EIEAQYKYIZIAYb4RQEI
    ATALBgNVHQ8EBAMCAQYwEQYJYIZIAYb4QgEBBAQDAgEGMDEGA1UdHwQqMCgwJqAk
    oCKGIGh0dHA6Ly9jcmwudmVyaXNpZ24uY29tL3BjYTMuY3JsMA0GCSqGSIb3DQEB
    BQUAA4GBAAgB7ORolANC8XPxI6I63unx2sZUxCM+hurPajozq+qcBBQHNgYL+Yhv
    1RPuKSvD5HKNRO3RrCAJLeH24RkFOLA9D59/+J4C3IYChmFOJl9en5IeDCSk9dBw
    E88mw0M9SR2egi5SX7w+xmYpAY5Okiy8RnUDgqxz6dl+C2fvVFIa
    -----END CERTIFICATE-----
    ^D

Now create your client application file. The following sample generates a list of accounts for your enterprise:

    #!/usr/bin/ruby

    require 'pp'
    require 'sforceDriver.rb'

    sessionid_handler = SessionHeaderHandler.new
    calloptions_handler = CallOptionsHandler.new

    endpoint_url = ARGV.shift
    obj = Soap.new(endpoint_url)
    obj.headerhandler << sessionid_handler
    obj.headerhandler << calloptions_handler

    # Turn on wiredumps
    obj.wiredump_dev = STDERR

    # Dunno what this accomplishes
    calloptions_handler.client = 'client'

    parameters = Login.new('mylogin@mydomain.com', 'mypassword')
    login_result = obj.login(parameters).result

    sessionid_handler.sessionid = login_result.sessionId

    # Get accounts (defaults to no more than 2000 at a time, use querymore
    # to get the rest)

    my_query = XSD::XSDString.new("select Name, Id from Account")

    accounts = obj.query(my_query)

    #pp accounts
    accounts.result.records.each { |obj| puts "#{obj.id[0]}\t#{obj.name}" }

Running this program generates output like:

    $ chmod +x client.rb
    $ ./client.rb
    00130000000wgugAAA      Spacely Sprockets
    00130000000wguhAAA      Cogswell Cogs
    ...

I was using "https://na1-api.salesforce.com/services/Soap/c/6.0" as my endpoint_url.

The API says to use the endpoint URL that is returned after the call to login using the default url. This was the na1-api URL above. Unfortunately, however, there doesn't appear to be any way to change the endpoint URL after calling Soap.new (at least none that I can figure out).

Note, too, that it seems you can't call query with a simple string. This was a surprise to me.

I'm also not sure what the calloptions stuff is for, either, but it was in Nakamura-san's example so I left it.

I'm rapidly becoming allergic to SOAP. All these extraneous calls to a "result" method seems overly verbose to put it mildly. The last line in client.rb just cries for yet another wrapper method -- it would be nice if wsdl2ruby.rb just did all this for you. It feels like the "2ruby" part is only halfway there -- I want to use RUBY strings as parameters to query() and I want to have accessors that return normal RUBY objects.

To add insult to injury, you can't even run the debugger on the client program above, even though it runs fine outside of the debugger:

    $ ruby -r debug client.rb
    Debug.rb
    Emacs support available.

    client.rb:3:require 'pp'
    (rdb:1) b 33
    Set breakpoint 1 at client.rb:33
    (rdb:1) c
    Wire dump:

    = Request

    ! CONNECTION ESTABLISHED


    = Response



    Wire dump:

    = Request



    = Response



    /usr/lib/ruby/1.8/soap/rpc/proxy.rb:156: `org.xml.sax.SAXException:
    SimpleDeserializer encountered a child element, which is NOT expected,
    in something it was trying to deserialize.' (SOAP::FaultError)
            from /usr/lib/ruby/1.8/soap/rpc/driver.rb:177:in `call'
            from /usr/lib/ruby/1.8/soap/rpc/driver.rb:231:in `query'
            from /usr/lib/ruby/1.8/soap/rpc/driver.rb:226:in `query'
            from client.rb:30
    /usr/lib/ruby/1.8/soap/rpc/proxy.rb:156:      raise
    SOAP::FaultError.new(body.fault)

Bah!