restforce-db 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9839ca71a54acd8b9da16ea06ebe5835abaec61d
-  data.tar.gz: 0395b99de5b72aa53b08ae0b3a758ed6d8e2b8d6
+  metadata.gz: 9b41ed218d9bcffc70f1d5d8f52a141debf89d99
+  data.tar.gz: 2a353f19c80633f4773f3810c0b9df921ee339ce
 SHA512:
-  metadata.gz: a73f240312804395c2469866b895531795e5c0aa25ef485649f783b1c2b04e2e53372f51ce29a35d17ee7bca9519af9593bb504b062fd8350ab1537c404545f3
-  data.tar.gz: 6633584716645f92206a9495d5bdaf25ee23c9ecc6aea28bbb50bad4d078465b0f0bd785744c3268efa4a0f329e0871b5416ec43feae1f412bbc287ce770d1d2
+  metadata.gz: 5388edf3a22a22f6a5d50b61f438dd4ecb304175733c78ab0bcbd08cd7084df64e5006bea3c8256e4a248a0dcad127e9daec73e2515d3d7eeaa1a04792c4360c
+  data.tar.gz: cd9cafc0c560e850a40a4dc9cb1f6f185e39a53d1ae56df29395175a6c0779e091c636e5189218163f01c046818dbba84d82073e5b315ced162def4ec3bf07af

data/README.md

@@ -31,33 +31,64 @@ In order to keep your database records in sync with Salesforce, the table will n
 
 ### Register a mapping
 
-To register a Salesforce mapping in an `ActiveRecord` model, you need to add a few lines of DSL-style code to your class definition:
+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:
 
 ```ruby
-class MyModel < ActiveRecord::Base
+class Restaurant < ActiveRecord::Base
 
   include Restforce::DB::Model
+  has_one :specialty, class_name: "Dish"
+
+  sync_with(
+    "Restaurants__c",
+    fields: {
+      name:  "Name",
+      style: "Style__c",
+    },
+    associations: {
+      specialty: "Specialty__c",
+    },
+    root: true,
+  )
 
-  map_to "Object__c", name: "Name", color: "Color__c"
+end
+
+class Dish < ActiveRecord::Base
 
+  include Restforce::DB::Model
+  belongs_to :restaurant
+
+  sync_with(
+    "Dish__c",
+    fields: {
+      name:       "Name",
+      ingredient: "Ingredient__c",
+    },
+  )
 end
 ```
 
-This will automatically register the model with an entry in the `Restforce::DB::RecordType` collection.
+This will automatically register the models with entries in the `Restforce::DB::Mapping` collection. This collection defines the manner in which the database and Salesforce systems will be synchronized.
+
+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).
 
 ### Run the daemon
 
-To actually perform the system synchronization, you'll want to run the binstub installed through the generator (see above). This will daemonize a process which loops repeatedly to continuously synchronize your database and Salesforce according to your established mappings.
+To actually perform this system synchronization, you'll want to run the binstub installed through the generator (see above). This will daemonize a process which loops repeatedly to continuously synchronize your database and your Salesforce account, according to the established mappings.
 
-        $ bundle exec bin/restforce-db start
+    $ bundle exec bin/restforce-db start
 
 By default, this will load the credentials at the same location the generator installed them. You can explicitly pass the location of your configuration file with the `-c` option:
 
-        $ bundle exec bin/restforce-db -c /path/to/my/config.yml start
+    $ bundle exec bin/restforce-db -c /path/to/my/config.yml start
 
 For additional information and a full set of options, you can run:
 
-        $ bundle exec bin/restforce-db -h
+    $ bundle exec bin/restforce-db -h
 
 ## Development
 

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

@@ -46,15 +46,6 @@ module Restforce
           super
         end
 
-        private
-
-        # Internal: Get a description of the expected attribute Hash format.
-        #
-        # Returns a Symbol.
-        def conversion
-          :database
-        end
-
       end
 
     end

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

@@ -12,9 +12,11 @@ module Restforce
 
         # Public: Initialize a new Restforce::DB::Instances::Base instance.
         #
-        # record  - The Salesforce or database record to manage.
-        # mapping - An instance of Restforce::DB::Mapping.
-        def initialize(record, mapping = Mapping.new)
+        # record_type - A String or Class describing the record's type.
+        # record      - The Salesforce or database record to manage.
+        # mapping     - An instance of Restforce::DB::Mapping.
+        def initialize(record_type, record, mapping = nil)
+          @record_type = record_type
           @record = record
           @mapping = mapping
         end
@@ -40,7 +42,7 @@ module Restforce
         # Returns self.
         # Raises if the update fails for any reason.
         def copy!(from_record)
-          update! @mapping.convert(conversion, from_record.attributes)
+          update! @mapping.convert(@record_type, from_record.attributes)
         end
 
         # Public: Get a Hash mapping the configured attributes names to their
@@ -48,7 +50,7 @@ module Restforce
         #
         # Returns a Hash.
         def attributes
-          @mapping.attributes(conversion) { |attribute| record.send(attribute) }
+          @mapping.attributes(@record_type) { |attribute| record.send(attribute) }
         end
 
         # Public: Has this record been synced with Salesforce?

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

@@ -36,15 +36,6 @@ module Restforce
           last_update
         end
 
-        private
-
-        # Internal: Get a description of the expected attribute Hash format.
-        #
-        # Returns a Symbol.
-        def conversion
-          :salesforce
-        end
-
       end
 
     end

data/lib/restforce/db/mapping.rb

@@ -7,26 +7,65 @@ module Restforce
     # attributes from one to the other.
     class Mapping
 
-      attr_reader :mappings
+      class << self
+
+        include Enumerable
+        attr_accessor :collection
+
+        # Public: Get the Restforce::DB::Mapping entry for the specified
+        # database model.
+        #
+        # database_model - A Class compatible with ActiveRecord::Base.
+        #
+        # Returns a Restforce::DB::Mapping.
+        def [](database_model)
+          collection[database_model]
+        end
+
+        # Public: Iterate through all registered Restforce::DB::Mappings.
+        #
+        # 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
+          end
+        end
 
-      # Public: Initialize a new Restforce::DB::Mapping.
-      #
-      # mappings - A Hash, with keys corresponding to the names of Ruby object
-      #            attributes, and the values of those keys corresponding to the
-      #            names of the related Salesforce fields.
-      def initialize(mappings = {})
-        @mappings = mappings
       end
 
-      # Public: Append a new set of attribute mappings to the current set.
-      #
-      # mappings - A Hash, with keys corresponding to the names of Ruby object
-      #            attributes, and the values of those keys corresponding to the
-      #            names of the related Salesforce fields.
+      self.collection ||= {}
+
+      attr_reader :database_record_type, :salesforce_record_type, :associations
+      attr_writer :root
+
+      # Public: Initialize a new Restforce::DB::Mapping.
       #
-      # Returns nothing.
-      def add_mappings(mappings = {})
-        @mappings.merge!(mappings)
+      # database_model   - A Class compatible with ActiveRecord::Base.
+      # salesforce_model - A String name of an object type in Salesforce.
+      # options          - A Hash of mapping attributes. Currently supported
+      #                    keys are:
+      #                    :fields       - A Hash of mappings between database
+      #                                    columns and fields in Salesforce.
+      #                    :associations - A Hash of mappings between Active
+      #                                    Record association names and the
+      #                                    corresponding Salesforce Lookup name.
+      #                    :root         - A Boolean reflecting whether or not
+      #                                    this is a root-level mapping.
+      def initialize(database_model, salesforce_model, options = {})
+        @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) { {} }
+        @root = options.fetch(:root) { false }
+
+        @types = {
+          database_model   => :database,
+          salesforce_model => :salesforce,
+        }
+
+        self.class.collection[database_model] = self
       end
 
       # Public: Get a list of the relevant Salesforce field names for this
@@ -34,7 +73,7 @@ module Restforce
       #
       # Returns an Array.
       def salesforce_fields
-        @mappings.values
+        @fields.values + @associations.values
       end
 
       # Public: Get a list of the relevant database column names for this
@@ -42,26 +81,36 @@ module Restforce
       #
       # Returns an Array.
       def database_fields
-        @mappings.keys
+        @fields.keys
+      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
       end
 
       # Public: Build a normalized Hash of attributes from the appropriate set
       # of mappings. The keys of the resulting mapping Hash will correspond to
       # the database column names.
       #
-      # in_format - A Symbol reflecting the expected attribute list. Accepted
-      #             values are :database and :salesforce.
+      # in_format - A String or Class reflecting the record type from which the
+      #             attribute Hash is being compiled.
       #
       # Yields the attribute name.
       # Returns a Hash.
       def attributes(from_format)
         use_mappings =
-          case from_format
+          case @types[from_format]
           when :salesforce
-            @mappings
+            @fields
           when :database
             # Generate a mapping of database column names to record attributes.
             database_fields.zip(database_fields)
+          else
+            raise ArgumentError
           end
 
         use_mappings.each_with_object({}) do |(attribute, mapping), values|
@@ -72,33 +121,44 @@ module Restforce
       # Public: Convert a Hash of attributes to a format compatible with a
       # specific platform.
       #
-      # to_format  - A Symbol reflecting the expected format. Accepted values
-      #              are :database and :salesforce.
-      # attributes - A Hash, with keys corresponding to the attribute names in
-      #              the format to convert away from.
+      # to_format  - A String or Class reflecting the record type for which the
+      #              attribute Hash is being compiled.
+      # attributes - A Hash of attributes, with keys corresponding to the
+      #              normalized attribute names.
       #
       # Examples
       #
-      #   mapping = Mapping.new(some_key: "Some_Field__c")
-      #   mapping.convert(:salesforce, some_key: "some value")
+      #   mapping = Mapping.new(MyClass, "Object__c", some_key: "SomeField__c")
+      #
+      #   mapping.convert("Object__c", some_key: "some value")
       #   # => { "Some_Field__c" => "some value" }
       #
-      #   mapping.convert(:database, some_key: "some other value")
+      #   mapping.convert(MyClass, some_key: "some other value")
       #   # => { some_key: "some other value" }
       #
       # Returns a Hash.
       def convert(to_format, attributes)
-        case to_format
+        case @types[to_format]
         when :database
           attributes.dup
         when :salesforce
-          @mappings.each_with_object({}) do |(attribute, mapping), converted|
+          @fields.each_with_object({}) do |(attribute, mapping), converted|
             next unless attributes.key?(attribute)
             converted[mapping] = attributes[attribute]
           end
+        else
+          raise ArgumentError
         end
       end
 
+      # Public: Get a Synchronizer for the record types captured by this
+      # Mapping.
+      #
+      # Returns a Restforce::DB::Synchronizer.
+      def synchronizer
+        @synchronizer ||= Synchronizer.new(@database_record_type, @salesforce_record_type)
+      end
+
     end
 
   end

data/lib/restforce/db/model.rb

@@ -15,30 +15,15 @@ module Restforce
       # :nodoc:
       module ClassMethods
 
-        # Public: Initializes a Restforce::DB::RecordType defining this model's
+        # Public: Initializes a Restforce::DB::Mapping defining this model's
         # relationship to a Salesforce object type.
         #
         # salesforce_model - A String name of an object type in Salesforce.
-        # mappings         - A Hash of mappings between database columns and
-        #                    fields in Salesforce.
+        # options          - A Hash of options to pass through to the Mapping.
         #
-        # Returns a Restforce::DB::RecordType.
-        def map_to(salesforce_model, **mappings)
-          RecordType.new(
-            self,
-            salesforce_model,
-            mappings,
-          )
-        end
-
-        # Public: Append the passed mappings to this model.
-        #
-        # mappings - A Hash of database column names mapped to Salesforce
-        #            fields.
-        #
-        # Returns nothing.
-        def add_mappings(mappings)
-          RecordType[self].add_mappings(mappings)
+        # Returns a Restforce::DB::Mapping.
+        def sync_with(salesforce_model, **options)
+          Mapping.new(self, salesforce_model, options)
         end
 
       end

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

@@ -17,11 +17,17 @@ module Restforce
         # Returns a Restforce::DB::Instances::ActiveRecord instance.
         # Raises on any validation or database error.
         def create!(from_record)
-          attributes = @mapping.convert(:database, from_record.attributes)
+          attributes = @mapping.convert(@record_type, from_record.attributes)
 
-          record = @record_type.create!(attributes.merge(salesforce_id: from_record.id))
+          record = @record_type.new(attributes.merge(salesforce_id: from_record.id))
+          @mapping.associations.each do |association, lookup|
+            lookup_id = from_record.record.send(lookup)
+            associated = record.send("build_#{association}")
+            build_association associated, lookup_id
+          end
+          record.save!
 
-          Instances::ActiveRecord.new(record, @mapping).after_sync
+          Instances::ActiveRecord.new(@record_type, record, @mapping).after_sync
         end
 
         # Public: Find the instance of this ActiveRecord model corresponding to
@@ -34,7 +40,7 @@ module Restforce
           record = @record_type.find_by(salesforce_id: id)
           return nil unless record
 
-          Instances::ActiveRecord.new(record, @mapping)
+          Instances::ActiveRecord.new(@record_type, record, @mapping)
         end
 
         # Public: Iterate through all recently-updated ActiveRecord records of
@@ -55,7 +61,7 @@ module Restforce
           scope = scope.where("updated_at < ?", options[:before]) if options[:before]
 
           scope.find_each do |record|
-            yield Instances::ActiveRecord.new(record, @mapping)
+            yield Instances::ActiveRecord.new(@record_type, record, @mapping)
           end
         end
 
@@ -71,6 +77,33 @@ module Restforce
           @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 associatd database record.
+        # lookup_id  - A Salesforce ID corresponding to the record type in the
+        #              Mapping defined for the associated database model.
+        #
+        # Returns a Boolean.
+        def build_association(associated, lookup_id)
+          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,
+              synchronized_at: Time.now,
+            ),
+          )
+        end
+
       end
 
     end

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

@@ -12,7 +12,7 @@ module Restforce
         #
         # record_type - The name or class of the system record type.
         # mapping     - A Restforce::DB::Mapping.
-        def initialize(record_type, mapping = Mapping.new)
+        def initialize(record_type, mapping = nil)
           @record_type = record_type
           @mapping = mapping
         end
@@ -27,7 +27,7 @@ module Restforce
         def sync!(from_record)
           if synced?(from_record)
             update!(from_record)
-          else
+          elsif @mapping.root?
             create!(from_record)
           end
         end

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

@@ -17,7 +17,7 @@ module Restforce
         # Returns a Restforce::DB::Instances::Salesforce instance.
         # Raises on any error from Salesforce.
         def create!(from_record)
-          attributes = @mapping.convert(:salesforce, from_record.attributes)
+          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
@@ -37,7 +37,7 @@ module Restforce
 
           return unless record
 
-          Instances::Salesforce.new(record, @mapping)
+          Instances::Salesforce.new(@record_type, record, @mapping)
         end
 
         # Public: Iterate through all Salesforce records of this type.
@@ -61,7 +61,7 @@ module Restforce
           query = "select #{lookups} from #{@record_type}#{constraints}"
 
           DB.client.query(query).each do |record|
-            yield Instances::Salesforce.new(record, @mapping)
+            yield Instances::Salesforce.new(@record_type, record, @mapping)
           end
         end
 

data/lib/restforce/db/version.rb

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

data/lib/restforce/db/worker.rb

@@ -73,10 +73,7 @@ module Restforce
 
         loop do
           runtime = Benchmark.realtime { perform }
-
-          if runtime < @interval && !stop?
-            sleep(@interval - runtime)
-          end
+          sleep(@interval - runtime) if runtime < @interval && !stop?
 
           break if stop?
         end
@@ -99,8 +96,8 @@ module Restforce
       # Returns nothing.
       def perform
         track do
-          Restforce::DB::RecordType.each do |name, record_type|
-            synchronize name, record_type
+          Restforce::DB::Mapping.each do |name, mapping|
+            synchronize name, mapping
           end
         end
       end
@@ -132,13 +129,13 @@ 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.
-      # record_type - A Restforce::DB::RecordType.
+      # name    - The String name of the record type to synchronize.
+      # mapping - A Restforce::DB::Mapping.
       #
       # Returns a Boolean.
-      def synchronize(name, record_type)
+      def synchronize(name, mapping)
         log "  SYNCHRONIZE #{name}"
-        runtime =  Benchmark.realtime { record_type.synchronize }
+        runtime = Benchmark.realtime { mapping.synchronizer.run }
         log format("  COMPLETE after %.4f", runtime)
 
         return true

data/lib/restforce/db.rb

@@ -16,7 +16,6 @@ require "restforce/db/record_types/salesforce"
 
 require "restforce/db/mapping"
 require "restforce/db/model"
-require "restforce/db/record_type"
 require "restforce/db/synchronizer"
 require "restforce/db/tracker"
 require "restforce/db/worker"

data/test/cassettes/Restforce_DB/accessing_Salesforce/uses_the_configured_credentials.yml

@@ -21,10 +21,10 @@ http_interactions:
       message: OK
     headers:
       Date:
-      - Tue, 17 Mar 2015 18:29:58 GMT
+      - Thu, 26 Mar 2015 10:20:18 GMT
       Set-Cookie:
-      - BrowserId=KvCaIxn-RmelQDRcZJJmcw;Path=/;Domain=.salesforce.com;Expires=Sat,
-        16-May-2015 18:29:58 GMT
+      - BrowserId=OGFSgeFMR5uovzRw9T5zQw;Path=/;Domain=.salesforce.com;Expires=Mon,
+        25-May-2015 10:20:18 GMT
       Expires:
       - Thu, 01 Jan 1970 00:00:00 GMT
       Pragma:
@@ -37,7 +37,7 @@ http_interactions:
       - chunked
     body:
       encoding: ASCII-8BIT
-      string: '{"id":"https://login.salesforce.com/id/00D1a000000H3O9EAK/0051a000000UGT8AAO","issued_at":"1426616998243","token_type":"Bearer","instance_url":"https://<host>","signature":"UW5T01ssq1ZZjJa4k86jnWTT+XYv7lNzCLudxzKJ2BQ=","access_token":"00D1a000000H3O9!AQ4AQBFd3oqpDO.7.Xcxso.goiRaetayUacefPmDpnmt8PamElbwequE5PNhXF16HhJY.W21KtDWD8mnv5vFKKt9refJWu.h"}'
+      string: '{"id":"https://login.salesforce.com/id/00D1a000000H3O9EAK/0051a000000UGT8AAO","issued_at":"1427365218093","token_type":"Bearer","instance_url":"https://<host>","signature":"zr8yut/9lhLfOwHlsCXPJ635XLUaIg62ecMRMW7mAV4=","access_token":"00D1a000000H3O9!AQ4AQFqDs34WtnS6RDwxyGdLSPYE_cFTuNjjnDvX2HbNhGMu917m6JyqchGFbdiOruyd5Z.w7uN.ogsJF4_8TMMzdt2fw7OZ"}'
     http_version: 
-  recorded_at: Tue, 17 Mar 2015 18:29:58 GMT
+  recorded_at: Thu, 26 Mar 2015 10:20:18 GMT
 recorded_with: VCR 2.9.3