salesforce_record 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6ad16d2a059b16aff6a15262ab0552d83d3d12f9
+  data.tar.gz: 48123ec4187661eae7f4cd93c20bebbd9e5c4ead
+SHA512:
+  metadata.gz: feea79ba0c8a43da14fa76a52c2cfc253357be6ab6d480f5b3373cea59fa7f99a4f24979e244687a693e1435cbdad23a31cbadf087929f53a182e2015f29677b
+  data.tar.gz: 577b8ab8cec74c6834298afdb5173443d3b8c3d4f9f03dda8f1d44ca58623eb18163bba24ca5e52a9f5711777aa82ff415b2d8360f2caf990e67bc3d6884d998

data/README.md

@@ -0,0 +1,69 @@
+# SalesforceRecord
+
+[![Build Status](https://travis-ci.org/mru2/salesforce_record.png?branch=master)](https://travis-ci.org/mru2/salesforce_record) [![Coverage Status](https://coveralls.io/repos/mru2/salesforce_record/badge.png)](https://coveralls.io/r/mru2/salesforce_record) [![Code Climate](https://codeclimate.com/github/mru2/salesforce_record.png)](https://codeclimate.com/github/mru2/salesforce_record)
+
+ActiveRecord-like mixin for querying, fetching and updating Salesforce models
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'salesforce_record'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install salesforce_record
+
+## Usage
+
+```
+require 'salesforce_adapter'
+require 'salesforce_record'
+
+$salesforce = SalesforceAdapter::Base.new(
+  :url        => 'https://test.salesforce.com/services/Soap/u/16.0',
+  :login      => 'your_salesforce_login',
+  :password   => 'your_salesforce_password'
+)
+
+class MyLeadModel
+  include SalesforceRecord
+
+  is_salesforce_model :Lead
+  sf_adapter          $salesforce
+  sf_attributes       :Company, :FirstName, :LastName
+end
+
+# Finders
+> lead = MyLeadModel.find('00Qg000000ORDER66')
+=> #<MyLeadModel:0x007fe47983b700 @Id="00Qg000000ORDER66", @Company="JEDI inc", @FirstName="Mace", @LastName="Windu">
+
+# Attribute getters
+> lead.Company
+=> "JEDI inc"
+
+# Remote setters
+> lead.update_fields(:Company => 'One-arm support group')
+=> true
+
+# Record creation
+> new_lead = MyLeadModel.create(:LastName => 'Binks', :FirstName => 'Jar-Jar', :Company => 'Lobby for a new Autocracy')
+=> #<MyLeadModel:0x007fe4798e1970 @Id="00Qg0000002DUMBASS", @Company="Unwilling Dictatorship Lobby", @FirstName="Jar-Jar", @LastName="Binks">
+
+# Queries
+> results = MyLeadModel.where(:LastName => 'Windu')
+=> [#<MyLeadModel:0x007fe47991bee0 @Id="00Qg000000ORDER66", @Company="One-arm support group", @FirstName="Mace", @LastName="Windu">]
+```
+
+
+## Contributing
+
+1. Fork it ( http://github.com/<my-github-username>/salesforce_record/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_record.rb

@@ -0,0 +1,34 @@
+# Module allowing a class to wrap a salesforce object
+# Define accessors and finder methods
+
+# Usage :
+# class Lead
+#   is_salesforce_model :Lead
+#   include SalesforceRecord
+#   sf_adapter    salesforce_adapter
+#   sf_attributes :ConvertedAccountId, :Street
+#   sf_attribute  :owner_email,             :from => 'Owner.Email'
+#   sf_attribute  :Date_saisie_CB__c,       :type => :date
+# end
+# 
+# lead = Lead.find('my_lead_id', rforce_salesforce_adapter)
+# lead.owner_email # => "my@email.tld"
+
+require 'salesforce_record/version'
+
+require 'salesforce_record/base'
+require 'salesforce_record/attributes'
+require 'salesforce_record/finder'
+require 'salesforce_record/persistence'
+
+module SalesforceRecord
+
+  def self.included(base)
+    # Include dependencies
+    base.send :include, SalesforceRecord::Base
+    base.send :include, SalesforceRecord::Attributes
+    base.send :include, SalesforceRecord::Finder
+    base.send :include, SalesforceRecord::Persistence
+  end
+
+end

data/lib/salesforce_record/attributes.rb

@@ -0,0 +1,152 @@
+# Attributes handling
+# defines #new and #attributes
+# also class methods for parsing / encoding attributes hash for salesforce
+
+require 'salesforce_record/fields'
+
+module SalesforceRecord
+  module Attributes
+
+    def self.included(base)
+      base.send(:extend, ClassMethods)
+
+      base.instance_eval do
+        # Store the attributes and aliases at the class level
+        @salesforce_fields = {} # name  => field instance
+
+        # The base attributes
+        sf_attribute :Id, :type => :id
+      end
+    end
+
+
+    module ClassMethods
+
+      # The salesforce fields and options
+      def salesforce_fields ; @salesforce_fields ; end
+
+      # The attributes for this model
+      def salesforce_attributes ; @salesforce_fields.keys ; end
+
+      # Add salesforce attributes to the model
+      def sf_attributes(*attrs)
+        attrs.each do |attr|
+          sf_attribute attr
+        end
+      end
+
+      # Add a salesforce attribute to the model
+      # Possible options : 
+      # :from => the remote key to fetch to populate the field
+      # :type => one of :date, :float, :integer, :boolean, :id
+      def sf_attribute(attribute, opts={})
+
+        case opts[:type]
+        when :date
+          @salesforce_fields[attribute] = Fields::DateField.new(attribute, opts)
+        when :float
+          @salesforce_fields[attribute] = Fields::FloatField.new(attribute, opts)
+        when :integer
+          @salesforce_fields[attribute] = Fields::IntegerField.new(attribute, opts)
+        else
+          @salesforce_fields[attribute] = Fields::BaseField.new(attribute, opts)
+        end
+
+        # Set its accessor
+        attr_reader attribute
+      end
+
+
+      # Create an imported record from salesforce
+      def from_salesforce(fields)
+        new parse_salesforce_fields(fields)
+      end
+
+      # Parse fields coming from salesforce
+      def parse_salesforce_fields(sf_fields)
+        {}.tap do |parsed_fields|
+          sf_fields.each do |name, value|
+            parsed_field = parse_salesforce_field(name, value) unless value.nil?
+            parsed_fields.merge! parsed_field if !parsed_field.nil?
+          end
+        end
+      end
+
+      # Encode fields for salesforce
+      def encode_salesforce_fields(fields)
+        {}.tap do |encoded_fields|
+          fields.each do |name, value|
+            encoded_field = encode_salesforce_field(name, value)
+            encoded_fields.merge! encoded_field if !encoded_field.nil?
+          end
+        end
+      end
+
+      # Parse a field coming from salesforce (type)
+      def parse_salesforce_field(name, value)
+        # If existing, parse it depending on type
+        if (field = get_field name)
+          { field.local_name => field.parse(value) }
+
+        # Else, try to find if it is an alias
+        else
+          find_matching_alias(name => value)
+        end
+      end
+
+      # Encode a field from salesforce
+      def encode_salesforce_field(name, value)
+        # If existing, encode it depending on type and alias
+        if (field = get_field name) && (!field.alias?)
+          { field.remote_name => field.encode(value) }
+        end
+      end
+
+      def get_field(name)
+        self.salesforce_fields[name]
+      end
+
+      def has_field?(name)
+        !!get_field(name)
+      end
+
+      def field_type(name)
+        has_field?(name) && self.salesforce_fields[name].type
+      end
+
+      def field_remote_name(name)
+        has_field?(name) && self.salesforce_fields[name].remote_name
+      end
+
+
+      # Tries to find a salesforce alias matching a nested hash. Returns the alias name and corresponding value if found
+      def find_matching_alias(nested_hash)
+        self.salesforce_fields.each do |name, field|
+          if (value = field.is_alias_of(nested_hash))
+            return parse_salesforce_field(name, value)
+          end
+        end
+        return nil
+      end
+
+    end
+
+
+    # Constructor
+    def initialize(attributes = {})
+      # Iterate over the salesforce attributes and sets them
+      attributes.each do |name, value|
+        instance_variable_set :"@#{name}", value
+      end
+    end
+
+
+    # The attributes hash : name => parsed value
+    def attributes
+      Hash[*self.class.salesforce_attributes.map{|attr|[attr, self.send(attr)]}.flatten]
+    end
+
+
+
+  end
+end

data/lib/salesforce_record/base.rb

@@ -0,0 +1,36 @@
+# Base dependencies for the salesforce models
+# Handles the attribute list, the salesforce adapter, ...
+
+module SalesforceRecord
+  module Base
+
+    # Bulding the class
+    def self.included(base)
+      base.send(:extend, ClassMethods)
+
+      base.instance_eval do
+        @salesforce_table_name = nil
+        @salesforce_adapter    = nil
+      end
+    end
+
+
+    module ClassMethods
+
+      # Defines the salesforce table name
+      def is_salesforce_model(table_name)
+        @salesforce_table_name  = table_name
+      end
+      def salesforce_table_name ; @salesforce_table_name ; end
+
+
+      # Defines the salesforce adapter
+      def sf_adapter(adapter)
+        @salesforce_adapter = adapter
+      end
+      def salesforce_adapter    ; @salesforce_adapter    ; end
+
+    end
+
+  end
+end

data/lib/salesforce_record/fields.rb

@@ -0,0 +1,80 @@
+# All the possible salesforce fields
+# Responsible for parsing / encoding the values
+# Also handle local and remote name, if different
+
+module SalesforceRecord
+  module Fields
+
+    # The base class for the fields. No values parsing or encoding
+    class BaseField
+
+      attr_reader :local_name
+
+      def initialize(name, opts)
+        @local_name = name
+        @remote_name = opts[:from]
+      end
+
+      # Parse : SF => local
+      def parse(value)
+        value
+      end
+
+      # Encode : local => SF
+      def encode(value)
+        value
+      end
+
+      def remote_name
+        @remote_name || @local_name
+      end
+
+      def alias?
+        !!@remote_name
+      end
+
+      # Check if matching nested hash
+      def is_alias_of(nested_hash)
+        return false unless @remote_name
+        deep_fetch(nested_hash, remote_name.split('.').map(&:to_sym))
+      end
+
+      private
+
+      # Helper : fetch deep value from a hash
+      def deep_fetch(hash, keys)
+        keys.inject(hash){|subhash, key| subhash.is_a?(Hash) && subhash[key] }
+      end      
+    end
+
+
+    # A date. YYYY-MM-DD on salesforce
+    class DateField < BaseField
+      def encode(value)
+        value.strftime("%Y-%m-%d")
+      end
+
+      def parse(value)
+        Date.parse(value)
+      end
+    end
+
+
+    # A float
+    class FloatField < BaseField
+      def parse(value)
+        value.to_f
+      end
+    end
+
+
+    # An integer
+    class IntegerField < BaseField
+      def parse(value)
+        value.to_i
+      end
+    end
+
+
+  end
+end

data/lib/salesforce_record/finder.rb

@@ -0,0 +1,101 @@
+# Finder methods
+# defines #find and #where
+
+module SalesforceRecord
+  module Finder
+
+    def self.included(base)
+      base.send(:extend, ClassMethods)
+    end
+
+    module ClassMethods
+
+      # Returns the object matching a salesforce id
+      def find(id)
+        where(:Id => id).first
+      end
+
+
+      # Returns a list of object matching a specific query
+      def where(query)
+
+        # Build the matching query string
+        query_string = query_string(query)
+
+        # Run the query and get the results (always an array)
+        sf_results = salesforce_adapter.query(query_string)
+
+        # Create new objets with the results and return them
+        sf_results.map{|sf_attributes| from_salesforce(sf_attributes)}
+
+      end
+
+
+      # Creates an soql query for the resource. The query matchers are the argument
+      def query_string(query)
+
+        # The first letter of the model used
+        # i.e : Lead => l
+        # Used in the query : Select l.Type_de_paiement__c from Lead l where Id='id-goes-here'
+        key = 
+
+        # Build the base query : select all the attributes in the model table (except "type" : returned but should not be queried)
+        query_string = "Select "
+        query_string << (salesforce_attributes - [:type]).map{|attribute| remote_attribute_name(attribute)}.join(", ")
+        query_string << " from #{salesforce_table_name} #{salesforce_query_key}"
+
+        # Add the selectors
+        if query.is_a? String
+          soql_selector = query
+        else
+          soql_selector = query.map{|attribute, value| format_where_clause(attribute, value)}.join(' AND ')
+        end
+        
+        query_string << " WHERE #{soql_selector}"
+
+        query_string
+
+      end
+
+      
+      # The key used to namespace the salesforce queries : first character of the table name
+      # i.e : Lead => l
+      # Used in : Select l.Type_de_paiement__c from Lead l where Id='id-goes-here'        
+      def salesforce_query_key
+        self.salesforce_table_name.to_s[0, 1].downcase
+      end
+
+      # Aliases : the remote name for an attribute
+      def remote_attribute_name(attribute)
+        if (field = self.get_field attribute)
+          name_without_alias = field.remote_name
+        else
+          name_without_alias = attribute
+        end
+        "#{salesforce_query_key}.#{name_without_alias}"
+      end
+
+
+
+      # Create the query string for an attribute/value pair
+      # Returns something along the lines of "key.attribute='value'", to be injected in a WHERE clause
+      def format_where_clause(attribute, value)
+        q = "#{remote_attribute_name(attribute)}=" #exact match
+
+        # No escaping boolean values
+        if value.is_a?(TrueClass) || value.is_a?(FalseClass)
+          q << value.to_s
+        elsif value.is_a? Date
+          q << value.strftime("%Y-%m-%d")
+        elsif value.nil?
+          q << "NULL"
+        else
+          q << "'#{value}'"
+        end
+
+        q
+      end
+    end
+
+  end
+end

data/lib/salesforce_record/persistence.rb

@@ -0,0 +1,79 @@
+# Persisting the model to salesforce
+# defines #update_fields and #create methods
+
+require 'salesforce_adapter'
+
+module SalesforceRecord
+  module Persistence
+    
+    def self.included(base)
+      base.send(:extend, ClassMethods)
+    end
+
+
+    # Pushes new field values to salesforce and updates them locally
+    def update_fields(fields)
+
+      update_fields = self.class.encode_attributes(fields).merge({
+        :Id   => self.Id,
+        :type => self.class.salesforce_table_name.to_s
+      })
+      
+      begin
+        self.class.salesforce_adapter.update( self.class.salesforce_table_name, update_fields )
+        saved = true
+      rescue SalesforceAdapter::SalesforceFailedUpdate => e
+        # No check of the error code necessary here
+        saved = false
+      end
+
+      # Update the fields locally if the request passed
+      if saved
+        fields.each do |attribute, value|
+          self.instance_variable_set(:"@#{attribute}", value)
+        end
+      end
+
+      return saved
+    end
+
+
+
+    module ClassMethods
+
+      # Tries to create an instance, given a set of attributes
+      def create(attributes)
+
+        fields = encode_attributes(attributes).merge(:type => self.salesforce_table_name.to_s)
+
+        # Tries to create it remotely
+        begin
+          id = self.salesforce_adapter.create( self.salesforce_table_name, fields )
+
+          # If successful, return an instance with the given Id
+          return from_salesforce(fields.merge(:Id => id))
+
+        # TODO : have a real handling of failures
+        rescue => e
+          puts e.message
+          return nil
+        end
+
+      end
+
+
+      def encode_attributes(attributes)
+        {}.tap do |encoded_attributes|
+          attributes.each do |name, value|
+            if (field = self.get_field(name))
+              encoded_attributes[name] = field.encode value
+            else
+              encoded_attributes[name] = value
+            end
+          end
+        end
+      end
+    end
+
+  end
+end

data/lib/salesforce_record/version.rb

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

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: salesforce_record
+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: salesforce_adapter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+- !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_record.rb
+- lib/salesforce_record/attributes.rb
+- lib/salesforce_record/base.rb
+- lib/salesforce_record/fields.rb
+- lib/salesforce_record/finder.rb
+- lib/salesforce_record/persistence.rb
+- lib/salesforce_record/version.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.1
+signing_key: 
+specification_version: 4
+summary: ActiveRecord-like mixin for querying, fetching and updating Salesforce models
+test_files: []
+has_rdoc: