restforce-db 0.3.5 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 36ac23672709a2d24f9193d4d8cabbaf0bcb4e35
-  data.tar.gz: 8d9f0bbeab71f7a1edf1c6159887f63b27865708
+  metadata.gz: 98a9d9a418a15a7b4ca5ab954bc95d3e831e3bca
+  data.tar.gz: 26effab90549afaecad3d7883ef6f0881c4e96d4
 SHA512:
-  metadata.gz: ff1d1b1d71a0a506dbae3b3aa9990474c2e9800bef66987040d9df20b790bc2eb6720330cbf69fc71c1fd3ef2f321ae16f0607bacb1648920c5f7decd7c2a698
-  data.tar.gz: 0152fb60d9d3a91ff76943c7be5cf64f480c365b46cd768bfbb224b9ac2c4f965db913f51b9a850134e653440f7df2ec755c31108a32132160fa2b6690e5f311
+  metadata.gz: 5b8140eb2811c5fad0e94d82bf255219eb15d95105581eb32d84ce3cf0fd504495c5b39251d436581eee8f1955355311484491b26571b0041cb38c50f0a2e269
+  data.tar.gz: 170e5593fe2cf93d1e2500927baaec31747d5670fd7bb4113619d6ba65e35fdabcbc48201cdc7213a696ea565772218111f95575945c3ad62e7b5554dda852c9

data/README.md

@@ -24,11 +24,13 @@ This gem assumes that you're running Rails 4 or greater, therefore the `bin` fil
 
 ### Update your model schema
 
-In order to keep your database records in sync with Salesforce, the table will need to store a reference to its associated Salesforce record. A generator is included to trivially add this `salesforce_id` column to your tables:
+In order to keep your database records in sync with Salesforce, the table will need to store a reference to its associated Salesforce record. A generator is included to trivially add a generic `salesforce_id` column to your tables:
 
     $ bundle exec rails g restforce:migration MyModel
     $ bundle exec rake db:migrate
 
+If you need to activate multiple Salesforce mappings within a single model, you can do this with scoped column names. For example, if your Salesforce object types are named "Animal__c" and "Cat__c", `Restforce::DB` will look for columns named `animal_salesforce_id` and `cat_salesforce_id`.
+
 ### Register a mapping
 
 To register a Salesforce mapping in an `ActiveRecord` model, you'll need to add a few lines of DSL-style code to the relevant class definitions:
@@ -48,7 +50,6 @@ class Restaurant < ActiveRecord::Base
     associations: {
       specialty: "Specialty__c",
     },
-    root: true,
   )
 
 end
@@ -60,6 +61,7 @@ class Dish < ActiveRecord::Base
 
   sync_with(
     "Dish__c",
+    through: "Specialty__c",
     fields: {
       name:       "Name",
       ingredient: "Ingredient__c",
@@ -74,7 +76,7 @@ There are a few options to be aware of when describing a mapping:
 
 - `fields`: These are direct field-to-field mappings. The keys should line up with your ActiveRecord attribute names, while the values should line up with the matching field names in Salesforce.
 - `associations`: These are mappings of ActiveRecord associations to Salesforce lookups. Associations defined here will be built as part of the creation process for a newly-synced record. 
-- `root`: When `true`, all records of the associated type will be synchronized from Salesforce into the database and vice-versa. When `false` or `nil`, records will still be updated, but can only be created through associations (see just above).
+- `through`: This should be set for models which are created through an association. It references the lookup field on its parent's Salesforce object type.
 
 ### Run the daemon
 

data/lib/restforce/db/associations/active_record.rb

@@ -0,0 +1,68 @@
+module Restforce
+
+  module DB
+
+    module Associations
+
+      # Restforce::DB::Associations::ActiveRecord is a utility class which
+      # encapsulates the logic for creating/populating a one-to-one association
+      #
+      class ActiveRecord
+
+        attr_reader :associated
+
+        # Public: Initialize a new Restforce::DB::Associations::ActiveRecord.
+        #
+        # record      - The base ActiveRecord::Base instance for which the
+        #               association should be built.
+        # association - The name of the association which should be built.
+        def initialize(record, association)
+          @record = record
+          @associated = record.association(association).build
+        end
+
+        # Public: Build the associated record from the attributes found on the
+        # passed Salesforce record's lookups.
+        #
+        # from_record - A Hashie::Mash representing a base Salesforce record.
+        #
+        # Returns the constructed associated record.
+        def build(from_record)
+          Mapping[associated.class].each do |mapping|
+            lookup_id = from_record[mapping.through]
+            apply(mapping, lookup_id)
+          end
+
+          associated
+        end
+
+        private
+
+        # Internal: Assemble the associated record, using the data from the
+        # Salesforce record corresponding to a specific lookup ID.
+        #
+        # TODO: With some refactoring, this should be possible to handle as a
+        # recursive call to the configured Mapping's database record type. Right
+        # now, nested associations are unhandled.
+        #
+        # mapping   - A Restforce::DB::Mapping.
+        # lookup_id - A Salesforce ID corresponding to the record type in the
+        #             passed Mapping.
+        #
+        # Returns nothing.
+        def apply(mapping, lookup_id)
+          return if lookup_id.nil?
+
+          salesforce_instance = mapping.salesforce_record_type.find(lookup_id)
+          attributes = mapping.convert(associated.class, salesforce_instance.attributes)
+
+          associated.assign_attributes(attributes.merge(mapping.lookup_column => lookup_id))
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/lib/restforce/db/instances/active_record.rb

@@ -13,14 +13,14 @@ module Restforce
         #
         # Returns a String.
         def id
-          @record.salesforce_id
+          @record.send(@mapping.lookup_column)
         end
 
         # Public: Has this record been synced to a Salesforce record?
         #
         # Returns a Boolean.
         def synced?
-          @record.salesforce_id?
+          @record.send(:"#{@mapping.lookup_column}?")
         end
 
         # Public: Get the time of the last update to this record.

data/lib/restforce/db/mapping.rb

@@ -7,6 +7,8 @@ module Restforce
     # attributes from one to the other.
     class Mapping
 
+      class InvalidMappingError < StandardError; end
+
       class << self
 
         include Enumerable
@@ -27,8 +29,10 @@ module Restforce
         # Yields one Mapping for each database-to-Salesforce mapping.
         # Returns nothing.
         def each
-          collection.each do |database_model, record_type|
-            yield database_model.name, record_type
+          collection.each do |_, mappings|
+            mappings.each do |mapping|
+              yield mapping
+            end
           end
         end
 
@@ -37,12 +41,14 @@ module Restforce
       self.collection ||= {}
 
       attr_reader(
+        :database_model,
+        :salesforce_model,
         :database_record_type,
         :salesforce_record_type,
         :associations,
         :conditions,
+        :through,
       )
-      attr_writer :root
 
       # Public: Initialize a new Restforce::DB::Mapping.
       #
@@ -61,20 +67,24 @@ module Restforce
       #                    :root         - A Boolean reflecting whether or not
       #                                    this is a root-level mapping.
       def initialize(database_model, salesforce_model, options = {})
+        @database_model = database_model
+        @salesforce_model = salesforce_model
+
         @database_record_type = RecordTypes::ActiveRecord.new(database_model, self)
         @salesforce_record_type = RecordTypes::Salesforce.new(salesforce_model, self)
 
         @fields = options.fetch(:fields) { {} }
         @associations = options.fetch(:associations) { {} }
         @conditions = options.fetch(:conditions) { [] }
-        @root = options.fetch(:root) { false }
+        @through = options.fetch(:through) { nil }
 
         @types = {
           database_model   => :database,
           salesforce_model => :salesforce,
         }
 
-        self.class.collection[database_model] = self
+        self.class.collection[database_model] ||= []
+        self.class.collection[database_model] << self
       end
 
       # Public: Get a list of the relevant Salesforce field names for this
@@ -82,7 +92,7 @@ module Restforce
       #
       # Returns an Array.
       def salesforce_fields
-        @fields.values + @associations.values
+        @fields.values + @associations.values.flatten
       end
 
       # Public: Get a list of the relevant database column names for this
@@ -93,12 +103,32 @@ module Restforce
         @fields.keys
       end
 
+      # Public: Get the name of the database column which should be used to
+      # store the Salesforce lookup ID.
+      #
+      # Raises an InvalidMappingError if no database column exists.
+      # Returns a Symbol.
+      def lookup_column
+        @lookup_column ||= begin
+          column_prefix = salesforce_model.underscore.chomp("__c")
+          column = :"#{column_prefix}_salesforce_id"
+
+          if database_record_type.column?(column)
+            column
+          elsif database_record_type.column?(:salesforce_id)
+            :salesforce_id
+          else
+            raise InvalidMappingError, "#{database_model} must define a Salesforce ID column"
+          end
+        end
+      end
+
       # Public: Is this a root-level mapping? Used to determine whether or not
       # to trigger the creation of "missing" database records.
       #
       # Returns a Boolean.
       def root?
-        @root
+        @through.nil?
       end
 
       # Public: Build a normalized Hash of attributes from the appropriate set

data/lib/restforce/db/record_types/active_record.rb

@@ -19,11 +19,10 @@ module Restforce
         def create!(from_record)
           attributes = @mapping.convert(@record_type, from_record.attributes)
 
-          record = @record_type.new(attributes.merge(salesforce_id: from_record.id))
-          associations = @mapping.associations.map do |association, lookup|
-            associated = record.association(association).build
-            lookup_id = from_record.record.send(lookup)
-            build_association associated, lookup_id
+          record = @record_type.new(attributes.merge(@mapping.lookup_column => from_record.id))
+
+          associations = @mapping.associations.map do |association, _|
+            Associations::ActiveRecord.new(record, association).build(from_record.record)
           end
 
           record.transaction do
@@ -44,7 +43,7 @@ module Restforce
         #
         # Returns nil or a Restforce::DB::Instances::ActiveRecord instance.
         def find(id)
-          record = @record_type.find_by(salesforce_id: id)
+          record = @record_type.find_by(@mapping.lookup_column => id)
           return nil unless record
 
           Instances::ActiveRecord.new(@record_type, record, @mapping)
@@ -72,6 +71,19 @@ module Restforce
           end
         end
 
+        # Public: Does the model represented by this record type have a column
+        # with the requested name?
+        #
+        # column - A Symbol column name.
+        #
+        # Returns a Boolean.
+        def column?(column)
+          ::ActiveRecord::Base.connection.column_exists?(
+            @record_type.table_name,
+            column,
+          )
+        end
+
         private
 
         # Internal: Has this Salesforce record already been linked to a database
@@ -81,32 +93,7 @@ module Restforce
         #
         # Returns a Boolean.
         def synced?(record)
-          @record_type.exists?(salesforce_id: record.id)
-        end
-
-        # Internal: Assemble an associated record, using the data from the
-        # Salesforce record corresponding to a specific lookup ID.
-        #
-        # TODO: With some refactoring using ActiveRecord inflections, this
-        # should be possible to handle as a recursive call to the configured
-        # Mapping's database record type. Right now, nested associations are
-        # ignored.
-        #
-        # associated - The associated database record.
-        # lookup_id  - A Salesforce ID corresponding to the record type in the
-        #              Mapping defined for the associated database model.
-        #
-        # Returns the associated ActiveRecord instance.
-        def build_association(associated, lookup_id)
-          return if lookup_id.nil?
-
-          mapping = Mapping[associated.class]
-
-          salesforce_instance = mapping.salesforce_record_type.find(lookup_id)
-          attributes = mapping.convert(associated.class, salesforce_instance.attributes)
-
-          associated.assign_attributes(attributes.merge(salesforce_id: lookup_id))
-          associated
+          @record_type.exists?(@mapping.lookup_column => record.id)
         end
 
       end

data/lib/restforce/db/record_types/salesforce.rb

@@ -20,7 +20,7 @@ module Restforce
           attributes = @mapping.convert(@record_type, from_record.attributes)
           record_id = DB.client.create!(@record_type, attributes)
 
-          from_record.update!(salesforce_id: record_id).after_sync
+          from_record.update!(@mapping.lookup_column => record_id).after_sync
 
           find(record_id)
         end

data/lib/restforce/db/version.rb

@@ -3,7 +3,7 @@ module Restforce
   # :nodoc:
   module DB
 
-    VERSION = "0.3.5"
+    VERSION = "0.4.0"
 
   end
 

data/lib/restforce/db/worker.rb

@@ -99,8 +99,8 @@ module Restforce
       # Returns nothing.
       def perform
         track do
-          Restforce::DB::Mapping.each do |name, mapping|
-            synchronize name, mapping
+          Restforce::DB::Mapping.each do |mapping|
+            synchronize mapping
           end
         end
       end
@@ -132,12 +132,11 @@ module Restforce
       # Internal: Synchronize the objects in the database and Salesforce
       # corresponding to the passed record type.
       #
-      # name    - The String name of the record type to synchronize.
       # mapping - A Restforce::DB::Mapping.
       #
       # Returns a Boolean.
-      def synchronize(name, mapping)
-        log "  SYNCHRONIZE #{name}"
+      def synchronize(mapping)
+        log "  SYNCHRONIZE #{mapping.database_model.name} with #{mapping.salesforce_model}"
         runtime = Benchmark.realtime { mapping.synchronizer.run(delay: @delay) }
         log format("  COMPLETE after %.4f", runtime)
 

data/lib/restforce/db.rb

@@ -6,6 +6,8 @@ require "restforce/extensions"
 require "restforce/db/version"
 require "restforce/db/configuration"
 
+require "restforce/db/associations/active_record"
+
 require "restforce/db/instances/base"
 require "restforce/db/instances/active_record"
 require "restforce/db/instances/salesforce"

data/test/lib/restforce/db/associations/active_record_test.rb

@@ -0,0 +1,43 @@
+require_relative "../../../../test_helper"
+
+describe Restforce::DB::Associations::ActiveRecord do
+
+  configure!
+  mappings!
+
+  let(:associations) { { user: "Friend__c" } }
+  let(:record) { CustomObject.new }
+  let(:association) { Restforce::DB::Associations::ActiveRecord.new(record, :user) }
+
+  describe "#build" do
+    let(:association_id) { "a001a000001EFRIEND" }
+    let(:salesforce_record) { Hashie::Mash.new("Friend__c" => association_id) }
+    let(:associated_record) { association.build(salesforce_record) }
+
+    before do
+      mapping = Restforce::DB::Mapping.new(
+        User,
+        "Contact",
+        through: "Friend__c",
+        fields: { email: "Email" },
+      )
+      salesforce_record_type = mapping.salesforce_record_type
+
+      # Stub out the `#find` method on the record type
+      def salesforce_record_type.find(id)
+        Struct.new(:id, :last_update, :attributes).new(
+          id,
+          Time.now,
+          email: "somebody@example.com",
+        )
+      end
+    end
+
+    it "creates the associated record from the related Salesforce record's attributes" do
+      expect(associated_record).to_not_be_nil
+      expect(associated_record.email).to_equal("somebody@example.com")
+      expect(associated_record.salesforce_id).to_equal(association_id)
+      expect(associated_record).to_equal record.user
+    end
+  end
+end

data/test/lib/restforce/db/mapping_test.rb

@@ -27,14 +27,14 @@ describe Restforce::DB::Mapping do
     # Restforce::DB::Mapping actually implements Enumerable, so we're just
     # going with a trivially testable portion of the Enumerable API.
     it "yields the registered record types" do
-      expect(Restforce::DB::Mapping.first).to_equal [database_model.name, mapping]
+      expect(Restforce::DB::Mapping.first).to_equal mapping
     end
   end
 
   describe "#initialize" do
 
     it "adds the mapping to the global collection" do
-      expect(Restforce::DB::Mapping[database_model]).to_equal mapping
+      expect(Restforce::DB::Mapping[database_model]).to_equal [mapping]
     end
   end
 
@@ -56,6 +56,46 @@ describe Restforce::DB::Mapping do
     end
   end
 
+  describe "#lookup_column" do
+    let(:db) { mapping.database_record_type }
+
+    describe "when the database table has a column matching the Salesforce model" do
+      before do
+        def db.column?(_)
+          true
+        end
+      end
+
+      it "returns the explicit column name" do
+        expect(mapping.lookup_column).to_equal(:custom_object_salesforce_id)
+      end
+    end
+
+    describe "when the database table has a generic salesforce ID column" do
+      before do
+        def db.column?(column)
+          column == :salesforce_id
+        end
+      end
+
+      it "returns the generic column name" do
+        expect(mapping.lookup_column).to_equal(:salesforce_id)
+      end
+    end
+
+    describe "when the database table has no salesforce ID column" do
+      before do
+        def db.column?(_)
+          false
+        end
+      end
+
+      it "raises an error" do
+        expect(-> { mapping.lookup_column }).to_raise Restforce::DB::Mapping::InvalidMappingError
+      end
+    end
+  end
+
   describe "#attributes" do
 
     it "builds a normalized Hash of database attribute values" do

data/test/lib/restforce/db/model_test.rb

@@ -23,8 +23,7 @@ describe Restforce::DB::Model do
     end
 
     it "creates a mapping in Restforce::DB::Mapping" do
-      expect(Restforce::DB::Mapping[database_model])
-        .to_be_instance_of(Restforce::DB::Mapping)
+      expect(Restforce::DB::Mapping[database_model]).to_not_be :empty?
     end
   end
 

data/test/lib/restforce/db/record_types/active_record_test.rb

@@ -79,7 +79,12 @@ describe Restforce::DB::RecordTypes::ActiveRecord do
       let(:associations) { { user: "Friend__c" } }
 
       before do
-        mapping = Restforce::DB::Mapping.new(User, "Contact", fields: { email: "Email" })
+        mapping = Restforce::DB::Mapping.new(
+          User,
+          "Contact",
+          through: "Friend__c",
+          fields: { email: "Email" },
+        )
         salesforce_record_type = mapping.salesforce_record_type
 
         # Stub out the `#find` method on the record type

data/test/lib/restforce/db/synchronizer_test.rb

@@ -50,8 +50,9 @@ describe Restforce::DB::Synchronizer do
       end
 
       describe "for a non-root mapping" do
+        let(:through) { "SomeField__c" }
+
         before do
-          mapping.root = false
           synchronizer.run
         end
 

data/test/support/utilities.rb

@@ -18,11 +18,12 @@ def mappings!
   let(:fields) { { name: "Name", example: "Example_Field__c" } }
   let(:associations) { {} }
   let(:conditions) { [] }
+  let(:through) { nil }
   let!(:mapping) do
     Restforce::DB::Mapping.new(
       database_model,
       salesforce_model,
-      root: true,
+      through: through,
       fields: fields,
       associations: associations,
       conditions: conditions,

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: restforce-db
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  version: 0.4.0
 platform: ruby
 authors:
 - Andrew Horner
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-04-01 00:00:00.000000000 Z
+date: 2015-04-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -220,6 +220,7 @@ files:
 - lib/generators/templates/migration.rb.tt
 - lib/generators/templates/script
 - lib/restforce/db.rb
+- lib/restforce/db/associations/active_record.rb
 - lib/restforce/db/command.rb
 - lib/restforce/db/configuration.rb
 - lib/restforce/db/instances/active_record.rb
@@ -252,6 +253,7 @@ files:
 - test/cassettes/Restforce_DB_Synchronizer/_run/given_an_existing_Salesforce_record/for_a_non-root_mapping/does_not_create_a_database_record.yml
 - test/cassettes/Restforce_DB_Synchronizer/_run/given_an_existing_Salesforce_record/for_a_root_mapping/creates_a_matching_database_record.yml
 - test/cassettes/Restforce_DB_Synchronizer/_run/given_an_existing_database_record/populates_Salesforce_with_the_new_record.yml
+- test/lib/restforce/db/associations/active_record_test.rb
 - test/lib/restforce/db/configuration_test.rb
 - test/lib/restforce/db/instances/active_record_test.rb
 - test/lib/restforce/db/instances/salesforce_test.rb