salesforce_adapter 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e5db31804a0b4354b11b1e8cdd09ace23a9fc106
+  data.tar.gz: 15d3305e9a909da4ff4afed346144df47ddf8b7e
+SHA512:
+  metadata.gz: 017c7c92736a178b66243ccbf7c8dbecf533dfc113a38b88d7c353117013d7e07040265c91b9c7c352d6d6db74ad31fbe560e3a731a7f1901951ea7c0324b14b
+  data.tar.gz: 28a734ff1747df86d47497c39cc5b33dab8fb35abe6ddc7bb63bc5bcb0f6b895c5ddb8c9501e2e59a0a5fbb0ee4415fdf5be568353d42290ffee05aedd1f6970

data/README.md

@@ -0,0 +1,56 @@
+# SalesforceAdapter
+
+[![Build Status](https://travis-ci.org/mru2/salesforce_adapter.png?branch=master)](https://travis-ci.org/mru2/salesforce_adapter) [![Coverage Status](https://coveralls.io/repos/mru2/salesforce_adapter/badge.png)](https://coveralls.io/r/mru2/salesforce_adapter) [![Code Climate](https://codeclimate.com/github/mru2/salesforce_adapter.png)](https://codeclimate.com/github/mru2/salesforce_adapter)
+
+
+
+Ruby client for the salesforce API
+Actually, lightweight wrapper around the RForce gem
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'salesforce_adapter'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install salesforce_adapter
+
+## Usage
+
+```
+require 'salesforce_adapter'
+
+adapter = SalesforceAdapter::Base.new(
+  :url        => 'https://test.salesforce.com/services/Soap/u/16.0',
+  :login      => 'your_salesforce_login',
+  :password   => 'your_salesforce_password'
+)
+
+ > adapter.query("SELECT a.Id, a.Name FROM Account a WHERE Id='a_salesforce_id'")
+=> [ {:type => "Account", :Id => "a_salesforce_id", :Name => "an_account" } ]
+
+ > adapter.create(:Lead, {:type => 'Lead', :FirstName => 'Mace', :LastName => 'Windu', :Company => 'JEDI inc'})
+=> 'the_new_lead_id'
+
+ > adapter.update(:Lead, {:type => 'Lead', :Id => 'the_new_lead_id', :Company => 'One Arm Support Group'})
+=> 'the_new_lead_id'
+
+
+ > adapter.webservice('MyWebserviceClass').myMethod('foo')
+=> 'bar'
+```
+
+
+## Contributing
+
+1. Fork it ( http://github.com/<my-github-username>/salesforce_adapter/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/lib/salesforce_adapter/helpers.rb

@@ -0,0 +1,90 @@
+# Global helper methods used in the salesforce adapter
+
+module SalesforceAdapter
+
+
+  # Exception : Salesforce API timeout
+  class SalesforceTimeout   < StandardError ; end
+
+
+  module Helpers
+
+    class << self
+
+      # Attemps to run a salesforce operation a given number of times, 
+      # Handle timeout errors and sleep between retries
+      def handle_timeout(opts= {}, &block)
+
+        max_tries = opts[:max_tries] || 1
+        sleep_between_tries = opts[:sleep_between_tries] || 1
+
+        counter = 0
+
+        begin
+          counter += 1
+          yield
+
+        rescue Timeout::Error => e
+          raise SalesforceAdapter::SalesforceTimeout.new(e.message) if counter >= max_tries
+
+          sleep sleep_between_tries
+          retry
+        end
+
+      end
+
+
+      # Format a fields hash in an array, to be sent with a create or update query
+      # Necessary to handle nil fields (must be submitted under the :fieldsToNull key, and there can be more than one)
+      def format_fields_for_create_or_update(fields)
+        fields_array = []
+        fields = fields.dup
+
+        # The type and Id have to be the first fields given
+        type = fields.delete(:type)
+        id   = fields.delete(:Id)
+
+        fields_array << :type << type if type
+        fields_array << :Id   << id   if id
+
+        # Then append the other fields, handling the nil and boolean ones
+        fields.each do |key, value|
+          if value.nil?
+            fields_array << :fieldsToNull << key.to_s
+          else
+            fields_array << key << format_value_for_create_or_update(value)
+          end
+        end
+
+        fields_array
+      end
+
+
+      # Format a single value to be send in a create or update query
+      def format_value_for_create_or_update(value)
+        # Boolean have to be casted to strings
+        if !!value == value
+          value.to_s
+        else
+          value
+        end
+      end
+
+
+      # Format a hash for its display in logs / error messages
+      # Here for ruby 1.8's OrderedHash, to remove when migrated to ruby 2.0 +
+      def hash_to_s(h)
+        if h.class == Hash
+          h.inspect
+        elsif h.class < Hash
+          Hash[h.to_a].inspect
+        else
+          raise ArgumentError.new('h is not a Hash or a subclass of Hash')
+        end
+      end
+
+    end
+
+  end
+
+end

data/lib/salesforce_adapter/operations/base.rb

@@ -0,0 +1,80 @@
+# Base class for performing rforce operations
+# Template for formatting input, performing operation and validating results
+# Implementation details defined in subclasses
+
+# Responsible for validating, running and formatting the results of a query
+
+module SalesforceAdapter
+
+  # Exception : Fault from the API, no results returned. The error code has its accessor : :code
+  class SalesforceApiFault  < StandardError
+    attr_reader :code
+    def initialize(code, message = nil)
+      @code = code
+      super(message)
+    end
+  end
+
+
+  module Operations
+
+    class Base
+
+      attr_reader :rforce_binding
+
+
+      def initialize(rforce_binding)
+        @rforce_binding = rforce_binding
+      end
+
+
+      def run
+        validate_request!
+
+        Helpers.handle_timeout(:max_tries => 4, :sleep_between_tries => 5) do
+          @response = perform
+        end
+
+        validate_response!
+
+        format_response
+      end
+
+
+      private
+
+      def context
+        "No context given"
+      end
+
+      def validate_request!
+        # nothing by default...
+      end
+
+      def perform!
+        raise NotImplementedError.new("Must be defined in subclass")
+      end
+
+      def validate_response!
+        # Check for API errors and raise them
+        if @response[:Fault]
+
+          fault_code    = @response[:Fault][:faultcode] # "sf:MALFORMED_QUERY"
+          fault_details = @response[:Fault][:faultstring]
+
+          message = "Salesforce API Fault : #{fault_details}.\nContext : #{context}"
+
+          raise SalesforceApiFault.new(fault_code), message
+        end
+
+      end
+
+      def format_response
+        # Nothing by default
+        @response
+      end
+
+    end
+
+  end
+end

data/lib/salesforce_adapter/operations/create.rb

@@ -0,0 +1,59 @@
+# Responsible for validating, running and formatting the results of a salesforce creation
+
+module SalesforceAdapter
+
+  # Exception : Creation failure, (still a response but no record created done)
+  class SalesforceFailedCreate < StandardError
+    attr_reader :code
+    def initialize(code, message = nil)
+      @code = code
+      super(message)
+    end
+  end
+
+
+  module Operations
+
+    class Create < Base
+
+      def initialize(rforce_binding, table_name, attributes)
+        @table_name = table_name
+        @attributes = attributes
+
+        super(rforce_binding)
+      end
+
+
+      private
+
+      def context
+        "creating salesforce #{@table_name} with attributes #{Helpers.hash_to_s(@attributes)}"
+      end
+
+      def validate_request!
+        raise ArgumentError.new("type must be specified for a Salesforce Create") unless @attributes[:type]
+      end
+
+      def perform
+        rforce_binding.create( @table_name => Helpers.format_fields_for_create_or_update(@attributes) )
+      end
+
+      def validate_response!
+        super
+
+        # Raise exception on update failure
+        if !@response[:createResponse][:result][:success]
+          sf_error_code     = @response[:createResponse][:result][:errors][:statusCode]
+          sf_error_message  = @response[:createResponse][:result][:errors][:message]
+          raise SalesforceFailedCreate.new(sf_error_code), "#{sf_error_message}\nContext : #{context}"
+        end
+      end
+
+      def format_response
+        # Return the id
+        @response[:createResponse][:result][:id]
+      end
+
+    end
+  end
+end

data/lib/salesforce_adapter/operations/query.rb

@@ -0,0 +1,43 @@
+# Responsible for validating, running and formatting the results of a query
+
+module SalesforceAdapter
+  module Operations
+
+    class Query < Base
+
+      def initialize(rforce_binding, query_string)
+        @query_string = query_string
+
+        super(rforce_binding)
+      end
+
+
+      private
+
+      def context
+        "querying salesforce with : #{@query_string}"
+      end
+
+      def perform
+        rforce_binding.query(:queryString => @query_string)
+      end
+
+      def format_response
+        # If no results, return an empty array
+        return [] if @response[:queryResponse][:result][:size] == "0"
+
+        # Otherwise return an array of the results (can be empty, or contain only one result)
+        records = @response[:queryResponse][:result][:records]
+
+        if records.is_a?(Array)
+          return records
+        else
+          return [records].compact # if nil => returning an empty array
+        end
+      end
+
+
+    end
+
+  end
+end

data/lib/salesforce_adapter/operations/update.rb

@@ -0,0 +1,61 @@
+# Responsible for validating, running and formatting the results of a salesforce update
+
+module SalesforceAdapter
+
+  # Exception : Update failure, (still a response but no update done)
+  class SalesforceFailedUpdate < StandardError
+    attr_reader :code
+    def initialize(code, message = nil)
+      @code = code
+      super(message)
+    end
+  end
+
+
+  module Operations
+
+    class Update < Base
+
+      def initialize(rforce_binding, table_name, attributes)
+        @table_name = table_name
+        @attributes = attributes
+
+        super(rforce_binding)
+      end
+
+
+      private
+
+      def context
+        "updating salesforce #{@table_name} with attributes #{Helpers.hash_to_s(@attributes)}"
+      end
+
+      def validate_request!
+        raise ArgumentError.new("Id must be specified for a Salesforce Update")   unless @attributes[:Id]
+        raise ArgumentError.new("type must be specified for a Salesforce Update") unless @attributes[:type]
+      end
+
+      def perform
+        rforce_binding.update( @table_name => Helpers.format_fields_for_create_or_update(@attributes) )
+      end
+
+      def validate_response!
+        super
+
+        # Raise exception on update failure
+        if !@response[:updateResponse][:result][:success]
+          sf_error_code     = @response[:updateResponse][:result][:errors][:statusCode]
+          sf_error_message  = @response[:updateResponse][:result][:errors][:message]
+          raise SalesforceFailedUpdate.new(sf_error_code), "#{sf_error_message}\nContext : #{context}"
+        end
+      end
+
+      def format_response
+        # Return the id
+        @response[:updateResponse][:result][:id]
+      end
+
+    end
+
+  end
+end

data/lib/salesforce_adapter/operations/webservice_call.rb

@@ -0,0 +1,69 @@
+# Responsible for validating, running and formatting the results of a webservice operation
+
+module SalesforceAdapter
+  module Operations
+
+    class WebserviceCall < Base
+
+      def initialize(rforce_binding, method_name, arguments, schema_url, service_path)
+        @method_name  = method_name.to_s
+        @arguments    = arguments || {}
+        @schema_url   = schema_url
+        @service_path = service_path
+
+        super(rforce_binding)
+      end
+
+
+      private
+
+      def context
+        "calling webservice method #{@method_name} with arguments #{@arguments.inspect}.\n Schema url: #{@schema_url}, service path: #{@service_path}"
+      end
+
+      def perform
+        rforce_binding.call_remote(@method_name, formatted_arguments){ [@schema_url, @service_path] }
+      end
+
+      def format_response
+        @response[:"#{@method_name}Response"][:result]
+      end
+
+      # Rescue missing methods by inspecting the content of the response
+      def validate_response!
+        begin
+          super
+        rescue SalesforceApiFault => e
+
+          # Change the exception to a NoMethodError if undefined on salesforce
+          if e.message =~ /No operation available for request/
+            raise NoMethodError.new(e.message)
+          else
+            raise e
+          end
+        end
+      end
+
+
+      # Formatted arguments for WS call : need to be like [:key1, value1, :key2, value2]
+      def formatted_arguments
+        [].tap do |formatted_arguments|
+          @arguments.each do |name, value|
+            formatted_arguments << name << cast(value)
+          end
+        end
+      end
+
+      # Convert a value before sending it to salesforce
+      def cast(value)
+        if [TrueClass, FalseClass].include? value.class
+          value
+        else
+          value.to_s
+        end
+      end
+
+    end
+
+  end
+end

data/lib/salesforce_adapter/rforce_binding.rb

@@ -0,0 +1,55 @@
+# Wrapper around the rforce binding, responsible to guarantee it is logged in
+
+module SalesforceAdapter
+
+  class RforceBinding
+
+    def initialize(url, login, password)
+      @url      = url
+      @login    = login
+      @password = password
+
+      @rforce = RForce::Binding.new(@url)
+    end
+
+
+    # Attempts to login to salesforce
+    def login
+      Helpers.handle_timeout(:max_tries => 4, :sleep_between_tries => 2) do
+        @rforce.login( @login , @password )
+      end
+    end
+
+
+    # Is it currently logged in?
+    def logged_in?
+      # An unlogged rforce binding has a session_id defined as nil
+      # Does not handle session expiration however
+      !!@rforce.instance_variable_get(:@session_id)
+    end
+
+
+    # Delegate all these methods to the rforce binding
+    [:query, :create, :update, :call_remote].each do |method_name|
+
+      define_method method_name do |*args, &block|
+
+        begin
+
+          # Guarantee the binding is logged in
+          login unless logged_in?
+
+          @rforce.send method_name, *args, &block
+
+        # Handle timeouts from salesforce
+        rescue Errno::ECONNRESET => e
+          raise SalesforceAdapter::SalesforceTimeout.new(e.message)
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/lib/salesforce_adapter/version.rb

@@ -0,0 +1,3 @@
+module SalesforceAdapter
+  VERSION = "1.0.0"
+end

data/lib/salesforce_adapter/webservice_proxy.rb

@@ -0,0 +1,20 @@
+# Proxy for a salesforce webservice. 
+# Uses method_missing behind the scenes to forward methods to salesforce calls
+
+module SalesforceAdapter
+
+  class WebserviceProxy
+
+    def initialize(adapter, webservice_class)
+      @adapter       = adapter
+      @schema_url    = "http://soap.sforce.com/schemas/class/#{webservice_class}"
+      @service_path  = "/services/Soap/class/#{webservice_class}"
+    end
+
+    # Forward calls to salesforce
+    def method_missing(method_name, args = {})
+      @adapter.call_webservice(method_name, args, @schema_url, @service_path)
+    end
+
+  end
+end

data/lib/salesforce_adapter.rb

@@ -0,0 +1,76 @@
+require 'salesforce_adapter/version'
+
+require 'salesforce_adapter/helpers'
+require 'salesforce_adapter/rforce_binding'
+require 'salesforce_adapter/webservice_proxy'
+
+require 'salesforce_adapter/operations/base'
+require 'salesforce_adapter/operations/query'
+require 'salesforce_adapter/operations/create'
+require 'salesforce_adapter/operations/update'
+require 'salesforce_adapter/operations/webservice_call'
+
+
+# Wrapper around a rforce binding
+# Forwards the 'query' method, handling the logging and error raising
+
+require 'rforce'
+
+
+module SalesforceAdapter
+
+  class Base
+
+    attr_reader :rforce_binding
+    attr_reader :webservice
+
+
+    # Initialize with the credentials
+    def initialize(config)
+      @rforce_binding = RforceBinding.new(config[:url], config[:login], config[:password])
+    end
+
+    def webservice(webservice_class)
+      WebserviceProxy.new(self, webservice_class)
+    end
+
+    # Runs a query on salesforce and returns the result
+    def query( query_string )
+
+      # Perform the query
+      Operations::Query.new(@rforce_binding, query_string).run()
+
+    end
+
+
+    # Updates a salesforce record
+    def update(table_name, attributes)
+
+      # Perform the update and returns the id
+      Operations::Update.new(@rforce_binding, table_name, attributes).run()
+
+    end
+
+
+    # Creates a salesforce record
+    def create(table_name, attributes)
+
+      # Perform the creation and returns the id
+      Operations::Create.new(@rforce_binding, table_name, attributes).run()
+
+    end
+
+
+
+    # Queries a salesforce webservice
+    def call_webservice(method_name, arguments, schema_url, service_path)
+
+      # Perform the call to the webservice and returns the result
+      Operations::WebserviceCall.new(@rforce_binding, method_name, arguments, schema_url, service_path).run()
+
+    end
+
+  end
+
+end
+

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: salesforce_adapter
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- ClicRDV
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-04-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rforce
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0.11'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- david.ruyer@clicrdv.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/salesforce_adapter.rb
+- lib/salesforce_adapter/helpers.rb
+- lib/salesforce_adapter/operations/base.rb
+- lib/salesforce_adapter/operations/create.rb
+- lib/salesforce_adapter/operations/query.rb
+- lib/salesforce_adapter/operations/update.rb
+- lib/salesforce_adapter/operations/webservice_call.rb
+- lib/salesforce_adapter/rforce_binding.rb
+- lib/salesforce_adapter/version.rb
+- lib/salesforce_adapter/webservice_proxy.rb
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Lightweight client for the salesforce API
+test_files: []
+has_rdoc: