salesforce_ar_sync 1.0.0

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Liam Nediger
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,413 @@
+# SalesforceArSync
+
+SalesforceARSync allows you to sync models and fields with Salesforce through a combination of 
+Outbound Messaging, SOAP and databasedotcom.
+
+## Installation
+
+### Requirements
+
+* Rails >= 3.1
+* Salesforce.com instance
+* [Have your 18 character organization id ready](#finding-your-18-character-organization-id)
+* databasedotcom gem >= 1.3 installed and configured [see below](#databasedotcom)
+* delayed_job gem >= 3.0 installed and configured
+
+### Salesforce Setup
+
+Before you can start syncing your data several things must be completed in Salesforce. 
+
+#### 1. Setup Remote Access
+Create a new Remote Access Application entry by going to 
+
+    Setup -> Develop -> Remote Access
+    
+You can use http://localhost/nothing for the _Callback URL_
+
+#### 2. Setup Outbound Messaging
+Each model you wish to sync requires a workflow to trigger outbound messaging. You can set the worflow 
+to trigger on the specific fields you wish to update. 
+
+    Setup -> Create -> Workflow & Approvals -> Worflow Rules
+    
+Click _New Rule_, select the object (model) you wish to sync and click _Next_, give the rule a name, select 
+_Every time a record is created or edited_ and set a rule on the field(s) you want to sync ( a formula checking 
+if the fields have changed is recommended). Click _Save & Next_, in the _Add Worflow Action_ dropdown select
+_New Outbound Message_. Enter a name and set the _Endpoint URL_ to be http://yoursite.com/integration/sf_soap/model_name. 
+Select the fields you wish to sync (Id and SystemModstamp are required). 
+
+*You need to do this for each object/model you want to sync.
+
+### databasedotcom
+
+Before using the salesforce_ar_sync gem you must ensure you have the databasedotcom gem installed and configured 
+properly. Make sure each of the models you wish to sync are materialized.
+
+````ruby
+$sf_client = Databasedotcom::Client.new("config/databasedotcom.yml")
+$sf_client.authenticate :username => <username>, :password => <password>
+$sf_client.sobject_module = Databasedotcom
+$sf_client.materialize "User"
+````
+
+### Gem Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'salesforce_ar_sync'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install salesforce_ar_sync
+    
+### Application Setup
+
+Before using the gem you must complete the setup of your rails app. 
+
+The gem needs to know your 18 character organization id, it can be stored in a YAML file or in the ENV class.
+
+To create the yaml file run
+
+    $ rails generate salesforce_ar_sync:configuration <organization id>
+    
+Next you will need to decide which models you want to sync. For each model you must create a migration and run them
+
+    $ rails generate salesforce_ar_sync:migrations <models> --migrate
+
+To mount the engine add the following line to your routes.rb file
+
+	mount SalesforceArSync::Engine => '/integration'
+
+You can change '/integration' to whatever you want, all of the engine routes will be based off of this path. Running
+
+	$ rake routes | grep salesforce_ar_sync
+	
+will show you all of the gems routes, make sure you point your outbound messages at these urls.
+
+Next you will need to tell the gem which models are syncable by adding _salesforce_syncable_ to your model class
+and specifying which attributes you would like to sync.
+
+````ruby
+salesforce_syncable :sync_attributes => {:FirstName => :first_name, :LastName => :last_name}
+````
+
+The first parameter in the _:sync_attributes_ hash is the Salesforce field name and the second is the model attribute 
+name.
+
+## Usage
+
+### Configuration Options
+
+The gem can be configured using a YAML file or with the ENV variable.
+
+The options available to configure are
+
+* __organization_id__: the 18 character organization id of your Salesforce instance
+* __sync_enabled__: a global sync enabled flag which is a boolean true/false
+
+To generate a YAML file
+
+    $ rails generate salesforce_ar_sync:configuration
+    
+Or with an organization id
+    
+    $ rails generate salesforce_ar_sync:configuration 123456789123456789
+    
+which will create a template salesforce_ar_sync.yml in /config that looks like the following
+
+    organization_id: <organization id> #18 character organization_id
+    sync_enabled: true
+
+    
+To use the ENV variable you must pass environemnt variables to rails via the _export_ command in bash or before the
+initializer loads the ENV settings.
+
+    $ export SALESFORCE_AR_SYNC_ORGANIZATION_ID=123456789123456789
+    $ export SALESFORCE_AR_SYNC_SYNC_ENABLED=true
+    
+### Model Options
+The model can have several options set:
+
+[__salesforce_sync_enabled__](#salesforce_sync_enabled)  
+[__sync_attributes__](#sync_attributes)  
+[__async_attributes__](#async_attributes)  
+[__default_attributes_for_create__](#default_attributes_for_create)  
+[__salesforce_id_attribute_name__](#salesforce_id_attribute_name)  
+[__web_id_attribute_name__](#web_id_attribute_name)  
+[__salesforce_sync_web_id__](#salesforce_sync_web_id)  
+[__web_class_name__](#web_class_name)  
+[__salesforce_object_name__](#salesforce_object_name)  
+[__salesforce_object__](#salesforce_object)  
+[__except__](#except)  
+
+#### <a id="salesforce_sync_enabled"></a>salesforce_sync_enabled
+Model level option to enable disable the sync, defaults to true.
+
+````ruby
+:salesforce_sync_enabled => false
+````
+    
+#### sync_attributes
+Hash mapping of Salesforce attributes to web attributes, defaults to empty hash.  
+"Web" attributes can be actual method names to return a custom value.If you are providing a method name to return a 
+value, you should also implement a corresponding my_method_changed? to return if the value has changed.  Otherwise 
+it will always be synced.
+
+````ruby
+:sync_attributes => { :Email => :login, :FirstName => :first_name, :LastName => :last_name }
+````
+
+#### async_attributes
+An array of Salesforce attributes which should be synced asynchronously, defaults to an empty array. When an object is saved and only attributes contained in this array, the save to Salesforce will be queued and processed asyncronously. 
+Use this carefully, nothing is done to ensure data integrity, if multiple jobs are queued for a single object there is no way to guarentee that they are processed in order, or that the save to Salesforce will succeed.
+
+````ruby
+:async_attributes => ["Last_Login__c", "Login_Count__c"]
+````
+
+Note:  The model will fall back to synchronous sync if non-synchronous attributes are changed along with async 
+attributes
+ 
+#### default_attributes_for_create
+A hash of default attributes that should be used when we are creating a new record, defaults to empty hash.
+
+````ruby
+:default_attributes_for_create => {:password_change_required => true}
+````
+
+#### salesforce_id_attribute_name
+The "Id" attribute of the corresponding Salesforce object, defaults to _Id_.
+
+````ruby
+:salesforce_id_attribute_name => :Id
+````
+
+#### web_id_attribute_name
+The field name of the web id attribute in the Salesforce Object, defaults to _WebId__c_
+
+````ruby
+:web_id_attribute_name  => :WebId__c
+````
+
+#### salesforce_sync_web_id
+Enable or disable sync of the web id, defaults to false. Use this if you have a need for the id field of the ActiveRecord model to by synced to Salesforce.
+
+````ruby
+:salesforce_sync_web_id => false
+````
+
+#### web_class_name
+The name of the Web Objects class. A custom value can be provided if you wish to sync to a SF object and back to a 
+different web object. Defaults to the model name. This would generally be used if you wanted to flatten a web object 
+into a larger SF object like Contact.
+      
+````ruby
+:web_class_name => 'Contact',
+````
+
+#### salesforce_object_name
+Optionally holds the name of a method which will return the name of the Salesforce object to sync to, defaults to nil.
+
+````ruby
+:salesforce_object_name => :salesforce_object_name_method_name
+````
+
+#### salesforce_object
+Optionally holds the name of a method which will retrieve a Salesforce object. Default implementation is called if no 
+method is specified, defaults to nil.
+
+````ruby
+:salesforce_object => :salesforce_object_method_name
+````
+
+#### except
+Optionally holds the name of a method which can contain logic to determine if a record should be synced on save. If no 
+method is given then only the salesforce_skip_sync attribute is used. Defaults to nil.
+
+````ruby
+:except => :except_method_name
+````
+
+### Stopping the Sync
+
+Stopping the gem from syncing can be done on three levels. 
+
+* The global level before the app starts via the .yml file, ENV variables or after the app starts with the gem's 
+configuration variable _SALESFORCE_AR_SYNC_CONFIG["SYNC_ENABLED"]_
+* The model level by setting the _:salesforce_sync_enabled => false_ or _:except => :method_name_
+* The instance level by setting _:salesforce_skip_sync => true_ in the instance
+
+## Examples
+
+### Our Basic Example Model
+
+```ruby
+class Contact < ActiveRecord::Base
+  attributes :first_name, :last_name, :phone, :email, :last_login_time, :salesforce_id, :salesforce_updated_at
+  attr_accessor :first_name, :last_name, :phone, :email, :last_login_time
+end
+```
+
+### Making the Model Syncable
+
+```ruby
+class Contact < ActiveRecord::Base
+  attributes :first_name, :last_name, :phone, :email, :last_login_time, :salesforce_id, :salesforce_updated_at
+  attr_accessor :first_name, :last_name, :phone, :email
+  
+  salesforce_syncable :sync_attributes => {:FirstName => :first_name, :LastName => :last_name, :Phone => :phone, :Email => :email}
+end
+```
+
+### Stopping the Model from Syncing with a Flag
+
+```ruby
+class Contact < ActiveRecord::Base
+  attributes :first_name, :last_name, :phone, :email, :last_login_time, :salesforce_id, :salesforce_updated_at
+  attr_accessor :first_name, :last_name, :phone, :email
+  
+  salesforce_syncable :sync_attributes => {:FirstName => :first_name, :LastName => :last_name, :Phone => :phone, :Email => :email},
+                      :salesforce_sync_enabled => false
+end
+```
+
+### Stopping the Model from Syncing with a Method
+
+```ruby
+class Contact < ActiveRecord::Base
+  attributes :first_name, :last_name, :phone, :email, :last_login_time, :salesforce_id, :salesforce_updated_at
+  attr_accessor :first_name, :last_name, :phone, :email
+  
+  salesforce_syncable :sync_attributes => {:FirstName => :first_name, :LastName => :last_name, :Phone => :phone, :Email => :email},
+                      :except => :skip_sync?
+                      
+  def skip_sync?
+    if first_name.blank?
+      return true
+    end
+  end
+end
+```
+
+### Stopping a Record from Syncing
+
+```ruby
+customer = Contact.find_by_email('test@example.com')
+customer.salesforce_skip_sync = true
+```
+
+### Specify Async Attributes
+
+```ruby
+class Contact < ActiveRecord::Base
+  attributes :first_name, :last_name, :phone, :email, :last_login_time, :salesforce_id, :salesforce_updated_at
+  attr_accessor :first_name, :last_name, :phone, :email, :last_login_time
+  
+  salesforce_syncable :sync_attributes => {:FirstName => :first_name, :LastName => :last_name, :Phone => :phone, :Email => :email, :Last_Login_Time__c => :last_login_time},
+                      :async_attributes => ["Last_Login_Time__c"]
+end
+```
+
+### Specify Default Attributes when an Object is Created
+
+```ruby
+class Contact < ActiveRecord::Base
+  attributes :first_name, :last_name, :phone, :email, :last_login_time, :salesforce_id, :salesforce_updated_at
+  attr_accessor :first_name, :last_name, :phone, :email, :last_login_time
+  
+  salesforce_syncable :sync_attributes => {:FirstName => :first_name, :LastName => :last_name, :Phone => :phone, :Email => :email},
+                      :default_attributes_for_create => {:password_change_required => true}
+end
+```
+
+### Relationships
+If you want to keep the standard ActiveRecord associations in place, but need to populate these relationships from Salesforce records, you can define
+methods in your models to add to the attribute mapping.
+
+The following example shows a Contact model, which is related to an Account model through account_id, we implement a getter, setter and _changed? method
+to do our lookups and map these methods in our sync_attributes mapping instead of the standard attributes. This allows us to send/receive messages from Salesforce
+using the 18 digit Salesforce id, but maintain our ActiveRecord relationships.
+
+```ruby
+
+	class Contact < ActiveRecord::Base
+		attributes :first_name, :last_name, :account_id
+		attr_accessor :first_name, :last_name, :account_id
+
+		salesforce_syncable :sync_attributes => { :FirstName => :first_name,
+																							:LastName => :last_name,
+																							:AccountId => :salesforce_account_id }
+
+		def salesforce_account_id_changed?
+		  account_id_changed?
+		end
+
+		def salesforce_account_id
+		  return nil if account_id.nil?
+		  account.salesforce_id
+		end
+
+		def salesforce_account_id=(account_id)
+		  self.account = nil and return if account_id.nil?
+		  self.account = Account.find_or_create_by_salesforce_id(account_id)
+		end
+	end
+	
+```
+
+### Defining a Custom Salesforce Object
+
+```ruby
+class Contact < ActiveRecord::Base
+  attributes :first_name, :last_name, :phone, :email, :last_login_time, :salesforce_id, :salesforce_updated_at
+  attr_accessor :first_name, :last_name, :phone, :email, :last_login_time
+  
+  salesforce_syncable :sync_attributes => {:FirstName => :first_name, :LastName => :last_name, :Phone => :phone, :Email => :email},
+                      :salesforce_object => :custom_salesforce_object
+
+  def custom_salesforce_object
+    "CustomContact__c"
+  end
+end
+```
+
+## Deletes
+In order to handle the delete of objects coming from Salesforce, a bit of code is necessary because an Outbound Message cannot be triggered when
+an object is deleted. To work around this you will need to create a new Custom Object in your Salesforce environment:
+
+```
+	Deleted_Object__C
+		Object_Id__c_ => Text(18)
+		Object_Type__c_ => Text(255)
+```
+
+Object_Id__c will hold the 18 digit Id of the record being deleted.
+Object_Type__c will hold the name of the Rails Model that the Salesforce object is synced with.
+
+If you trigger a record to be written to this object whenever another object is deleted, and configure an Outbound Message to send to the /sf_soap/delete action
+whenever a Deleted_Object__c record is created, the corresponding record will be removed from your Rails app.
+
+## Errors
+
+### Outbound Message Errors
+
+If the SOAP handler encounters an error it will be recorded in the log of the outbound message in Salesforce. To view the message go to
+
+    Setup -> Monitoring -> Outbound Messages
+
+## <a id="orga_id"></a>Finding your 18 Character Organization ID
+ Your 15 character organization id can be found in _Setup -> Company Profile -> Company Information_. You must convert 
+ it to an 18 character id by running it through the tool located here: 
+ http://cloudjedi.wordpress.com/no-fuss-salesforce-id-converter/ or by installing the Force.com Utility Belt for Chrome.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/lib/generators/salesforce_ar_sync/configuration/configuration_generator.rb

@@ -0,0 +1,17 @@
+module SalesforceArSync
+  module Generators
+    class ConfigurationGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('../templates', __FILE__)
+
+      desc "Generates migrations to add required columns for Salesforce sync on specified models."
+
+      argument :organization_id, :type => :string, :banner => "organization_id", :default => "#18 character organization_id"
+
+      def create_yaml
+        template "salesforce_ar_sync.yml", "config/salesforce_ar_sync.yml"
+      end
+    end
+  end
+end

data/lib/generators/salesforce_ar_sync/configuration/templates/salesforce_ar_sync.yml

@@ -0,0 +1,17 @@
+production:
+  organization_id: <%= @organization_id %>
+  sync_enabled: true
+  # Salesforce owned IPs from: https://help.salesforce.com/apex/HTViewSolution?language=en_US&id=000003652
+  ip_ranges: "204.14.232.0/23,204.14.237.0/24,96.43.144.0/22,96.43.148.0/22,204.14.234.0/23,204.14.238.0/23,182.50.76.0/22"
+  
+development:
+  organization_id: <%= @organization_id %>
+  sync_enabled: false
+  # Salesforce owned IPs from: https://help.salesforce.com/apex/HTViewSolution?language=en_US&id=000003652
+  ip_ranges: "204.14.232.0/23,204.14.237.0/24,96.43.144.0/22,96.43.148.0/22,204.14.234.0/23,204.14.238.0/23,182.50.76.0/22"
+    
+test:
+  organization_id: <%= @organization_id %>
+  sync_enabled: false
+  # Salesforce owned IPs from: https://help.salesforce.com/apex/HTViewSolution?language=en_US&id=000003652
+  ip_ranges: "204.14.232.0/23,204.14.237.0/24,96.43.144.0/22,96.43.148.0/22,204.14.234.0/23,204.14.238.0/23,182.50.76.0/22"

data/lib/generators/salesforce_ar_sync/migrations/migrations_generator.rb

@@ -0,0 +1,53 @@
+require 'rails/generators/active_record'
+
+module SalesforceArSync
+  module Generators
+    class MigrationsGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('../templates', __FILE__)
+
+      desc "Generates migrations to add required columns for Salesforce sync on specified models."
+
+      #The migrate option is used to specify whether to run the migrations in the end or not
+      class_option :migrate, :type => :string, :banner => "[yes|no]", :lazy_default => "yes"
+      #The list of models to create migrations for
+      argument :models, :type => :array, :banner => "model1 model2 model3...", :required => true
+
+
+      def create_migrations
+        models.each do |model|
+          create_migration(model)
+        end
+
+        if options[:migrate] == "yes" 
+          say "Performing Migrations"
+          run_migrations
+        end
+      end
+
+      protected
+
+      def run_migrations
+        rake("db:migrate")
+      end
+
+      def self.next_migration_number(path)
+        unless @prev_migration_nr
+          @prev_migration_nr = Time.now.utc.strftime("%Y%m%d%H%M%S").to_i
+        else
+          @prev_migration_nr += 1
+        end
+        @prev_migration_nr.to_s
+      end
+
+      def create_migration(model_name)
+        #we can't load all the models in so let's assume it follows the standard nameing convention
+        @table_name = model_name.tableize
+        @model_name = model_name
+
+        migration_template "migration.rb", "db/migrate/add_salesforce_fields_to_#{@table_name}.rb"
+      end 
+    end
+  end
+end

data/lib/generators/salesforce_ar_sync/migrations/templates/migration.rb

@@ -0,0 +1,13 @@
+class AddSalesforceFieldsTo<%= @model_name.pluralize %> < ActiveRecord::Migration
+  def up
+    add_column :<%= @table_name %>, :salesforce_id, :string, :limit => 18
+    add_column :<%= @table_name %>, :salesforce_updated_at, :datetime
+
+    add_index :<%= @table_name %>, :salesforce_id, :unique => true
+  end
+  
+  def down
+    remove_column :<%= @table_name %>, :salesforce_id
+    remove_column :<%= @table_name %>, :salesforce_updated_at
+  end
+end

data/lib/salesforce_ar_sync.rb

@@ -0,0 +1,19 @@
+require 'salesforce_ar_sync/engine'
+require 'salesforce_ar_sync/version'
+require 'salesforce_ar_sync/extenders/salesforce_syncable'
+require 'salesforce_ar_sync/salesforce_object_sync'
+require 'salesforce_ar_sync/soap_handler/base'
+require 'salesforce_ar_sync/soap_handler/delete'
+require 'salesforce_ar_sync/ip_constraint'
+
+module SalesforceArSync
+  mattr_accessor :app_root
+  
+  def self.setup
+    yield self
+  end
+end
+
+if defined?(ActiveRecord::Base)
+  ActiveRecord::Base.extend SalesforceArSync::Extenders::SalesforceSyncable
+end

data/lib/salesforce_ar_sync/engine.rb

@@ -0,0 +1,9 @@
+module SalesforceArSync
+  class Engine < ::Rails::Engine
+    initializer "salesforce_ar_sync.load_app_instance_data" do |app|
+      SalesforceArSync.setup do |config|
+        config.app_root = app.root
+      end
+    end
+  end
+end

data/lib/salesforce_ar_sync/extenders/salesforce_syncable.rb

@@ -0,0 +1,57 @@
+module SalesforceArSync
+  module Extenders
+    module SalesforceSyncable      
+      def salesforce_syncable(options = {})
+        require 'salesforce_ar_sync/salesforce_sync'
+        include SalesforceArSync::SalesforceSync
+
+        self.salesforce_sync_enabled = options.has_key?(:salesforce_sync_enabled) ? options[:salesforce_sync_enabled] : true
+        self.salesforce_sync_attribute_mapping = options.has_key?(:sync_attributes) ? options[:sync_attributes].stringify_keys : {}
+        self.salesforce_async_attributes = options.has_key?(:async_attributes) ? options[:async_attributes] : {}
+        self.salesforce_default_attributes_for_create = options.has_key?(:default_attributes_for_create) ? options[:default_attributes_for_create] : {}
+        self.salesforce_id_attribute_name = options.has_key?(:salesforce_id_attribute_name) ? options[:salesforce_id_attribute_name] : :Id
+        self.salesforce_web_id_attribute_name = options.has_key?(:web_id_attribute_name) ? options[:web_id_attribute_name] : :WebId__c
+        self.salesforce_sync_web_id = options.has_key?(:salesforce_sync_web_id) ? options[:salesforce_sync_web_id] : false
+        self.salesforce_web_class_name = options.has_key?(:web_class_name) ? options[:web_class_name] : self.name
+        
+        self.salesforce_object_name_method = options.has_key?(:salesforce_object_name) ? options[:salesforce_object_name] : nil
+        self.salesforce_object_method = options.has_key?(:salesforce_object) ? options[:salesforce_object] : nil
+        self.salesforce_skip_sync_method = options.has_key?(:except) ? options[:except] : nil
+        
+        instance_eval do
+          before_save :salesforce_sync
+          after_create :sync_web_id     
+          
+          def salesforce_sync_web_id?
+            self.salesforce_sync_web_id
+          end
+        end
+        
+        class_eval do
+          # Calls a method if provided to return the name of the Salesforce object the model is syncing to.
+          # If no method is provided, defaults to the class name
+          def salesforce_object_name
+            return send(self.class.salesforce_object_name_method) if self.class.salesforce_object_name_method.present?
+            return self.class.name
+          end
+          
+          # Calls a method, if provided, to retrieve an object from Salesforce. Calls the default implementation if
+          # no custom method is specified
+          def salesforce_object
+            return send(self.class.salesforce_object_method) if self.class.salesforce_object_method.present?
+            return send(:salesforce_object_default)
+          end
+          
+          # Calls a method, if provided, to determine if a record should be synced to Salesforce. 
+          # The salesforce_skip_sync instance variable is also used.
+          # The SALESFORCE_AR_SYNC_ENABLED flag overrides all the others if set to false
+          def salesforce_skip_sync?
+            return true if SALESFORCE_AR_SYNC_CONFIG["SYNC_ENABLED"] == false
+            return (salesforce_skip_sync || !self.class.salesforce_sync_enabled || send(self.class.salesforce_skip_sync_method)) if self.class.salesforce_skip_sync_method.present?
+            return (salesforce_skip_sync || !self.class.salesforce_sync_enabled)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/salesforce_ar_sync/ip_constraint.rb

@@ -0,0 +1,17 @@
+require 'ipaddr'
+
+module SalesforceArSync
+  class IPConstraint
+    def initialize
+    	@ip_ranges = SALESFORCE_AR_SYNC_CONFIG["IP_RANGES"]
+    end
+ 
+    def matches?(request)
+    	if Rails.env == 'development' || Rails.env == 'test'
+  	  	true
+    	else
+    		@ip_ranges.any?{|r| IPAddr.new(r).include?(IPAddr.new(request.remote_ip)) }
+    	end
+    end
+  end
+end

data/lib/salesforce_ar_sync/salesforce_object_sync.rb

@@ -0,0 +1,16 @@
+module SalesforceArSync
+  # simple object to be serialized when asynchronously sending data to Salesforce
+  class SalesforceObjectSync < Struct.new(:web_object_name, :salesforce_object_name, :salesforce_id, :attributes)
+    def perform        
+      sf_object = "Databasedotcom::#{salesforce_object_name}".constantize.find_by_Id salesforce_id
+    
+      if sf_object
+        sf_object.update_attributes(attributes)
+        sf_object.reload
+    
+        web_object = "#{web_object_name}".constantize.find_by_salesforce_id salesforce_id
+        web_object.update_attribute(:salesforce_updated_at, sf_object.SystemModstamp) unless web_object.nil?
+      end
+    end
+  end
+end

data/lib/salesforce_ar_sync/salesforce_sync.rb

@@ -0,0 +1,197 @@
+require 'active_support/concern'
+
+module SalesforceArSync
+  module SalesforceSync  
+    extend ActiveSupport::Concern
+    
+    module ClassMethods    
+      # Optionally holds the value to determine if salesforce syncing is enabled. Defaults to true. If set 
+      # to false syncing will be disabled for the class
+      attr_accessor :salesforce_sync_enabled
+
+      # Hash mapping of Salesforce attributes to web attributes
+      # Example:
+      # { :Email => :login, :FirstName => :first_name, :LastName => :last_name }
+      #
+      # "Web" attributes can be actual method names to return a custom value
+      # If you are providing a method name to return a value, you should also implement a corresponding my_method_changed? to 
+      # return if the value has changed.  Otherwise it will always be synced.
+      attr_accessor :salesforce_sync_attribute_mapping
+        
+      # Returns an array of Salesforce attributes which should be synced asynchronously
+      # Example:  ["Last_Login_Date__c", "Login_Count__c" ]
+      # Note:  The model will fall back to synchronous sync if non-synchronous attributes are changed along with async attributes
+      attr_accessor :salesforce_async_attributes
+        
+      # Returns a hash of default attributes that should be used when we are creating a new record
+      attr_accessor :salesforce_default_attributes_for_create
+
+      # Returns the "Id" attribute of the corresponding Salesforce object
+      attr_accessor :salesforce_id_attribute_name
+
+      # Returns the name of the Web Objects class. A custom value can be provided if you wish
+      # to sync to a SF object and back to a different web object.  This would generally be used
+      # if you wanted to flatten a web object into a larger SF object like Contact     
+      attr_accessor :salesforce_web_class_name
+
+      attr_accessor :salesforce_web_id_attribute_name        
+      attr_accessor :salesforce_sync_web_id
+      
+      # Optionally holds the name of a method which will return the name of the Salesforce object to sync to
+      attr_accessor :salesforce_object_name_method
+      
+      # Optionally holds the name of a method which will retrieve a Salesforce object. Default implementation is called
+      # if no method is specified
+      attr_accessor :salesforce_object_method
+      
+      # Optionally holds the name of a method which can contain logic to determine if a record should be synced on save.
+      # If no method is given then only the salesforce_skip_sync attribute is used.
+      attr_accessor :salesforce_skip_sync_method
+      
+      # Accepts values from an outbound message hash and will either update an existing record OR create a new record
+      # Firstly attempts to find an object by the salesforce_id attribute
+      # Secondly attempts to look an object up by it's ID (WebId__c in outbound message)
+      # Lastly it will create a new record setting it's salesforce_id
+      def salesforce_update(attributes={})
+        raise ArgumentError, "#{salesforce_id_attribute_name} parameter required" if attributes[salesforce_id_attribute_name].blank?
+
+        object = self.find_by_salesforce_id attributes[salesforce_id_attribute_name]
+        object ||= self.find_by_id attributes[salesforce_web_id_attribute_name] if salesforce_sync_web_id? && attributes[salesforce_web_id_attribute_name]
+        
+        if object.nil?
+          object = self.new
+          salesforce_default_attributes_for_create.merge(:salesforce_id => attributes[salesforce_id_attribute_name]).each_pair do |k, v|
+            object.send("#{k}=", v)
+          end
+        end
+
+        object.salesforce_process_update(attributes) if object && (object.salesforce_updated_at.nil? || (object.salesforce_updated_at && object.salesforce_updated_at < Time.parse(attributes[:SystemModstamp])))
+      end
+    end
+
+    # if this instance variable is set to true, the salesforce_sync method will return without attempting
+    # to sync data to Salesforce
+    attr_accessor :salesforce_skip_sync
+    
+    # Salesforce completely excludes any empty/null fields from Outbound Messages
+    # We initialize all declared attributes as nil before mapping the values from the message
+    def salesforce_empty_attributes
+      {}.tap do |hash|
+        self.class.salesforce_sync_attribute_mapping.each do |key, value|
+          hash[key] = nil
+        end
+      end
+    end
+
+    # An internal method used to get a hash of values that we are going to set from a Salesforce outbound message hash
+    def salesforce_attributes_to_set(attributes = {})
+      {}.tap do |hash| 
+        # loop through the hash of attributes from the outbound message, and compare to our sf mappings and 
+        # create a reversed hash of value's and key's to pass to update_attributes
+        attributes.each do |key, value|
+          # make sure our sync_mapping contains the salesforce attribute AND that our object has a setter for it
+          hash[self.class.salesforce_sync_attribute_mapping[key.to_s].to_sym] = value if self.class.salesforce_sync_attribute_mapping.include?(key.to_s) && self.respond_to?("#{self.class.salesforce_sync_attribute_mapping[key.to_s]}=")
+        end
+
+        # remove the web_id from hash if it exists, as we don't want to modify a web_id
+        hash.delete(:id) if hash[:id]
+
+        # update the sf_updated_at field with the system mod stamp from sf
+        hash[:salesforce_updated_at] = attributes[:SystemModstamp]
+
+        # incase we looked up via the WebId__c, we should set the salesforce_id
+        hash[:salesforce_id] = attributes[self.class.salesforce_id_attribute_name]
+      end
+    end
+
+    # Gets passed the Salesforce outbound message hash of changed values and updates the corresponding model
+    def salesforce_process_update(attributes = {})
+      attributes_to_update = salesforce_attributes_to_set(self.new_record? ? attributes : salesforce_empty_attributes.merge(attributes)) # only merge empty attributes for updates, so we don't overwrite the default create attributes
+      attributes_to_update.each_pair do |k, v|
+        self.send("#{k}=", v)
+      end
+      
+      # we don't want to keep going in a endless loop.  SF has just updated these values.
+      self.salesforce_skip_sync = true 
+      self.save!
+    end
+
+    # This method will fetch the salesforce object and go looking for it if it doesn't exist
+    def salesforce_object_default
+      return @sf_object if @sf_object.present?
+
+      @sf_object = "Databasedotcom::#{self.salesforce_object_name}".constantize.send("find_by_#{self.class.salesforce_id_attribute_name.to_s}", salesforce_id) unless salesforce_id.nil?
+
+      # Look up and link object by web id
+      @sf_object ||= "Databasedotcom::#{self.salesforce_object_name}".constantize.send("find_by_#{self.class.salesforce_web_id_attribute_name.to_s}", id) if self.class.salesforce_sync_web_id? && !new_record?
+
+      return @sf_object
+    end
+
+    # Checks if the passed in attribute should be updated in Salesforce.com
+    def salesforce_should_update_attribute?(attribute)
+      !self.respond_to?("#{attribute}_changed?") || (self.respond_to?("#{attribute}_changed?") && self.send("#{attribute}_changed?"))
+    end
+
+    # create a hash of updates to send to salesforce
+    def salesforce_attributes_to_update(include_all = false)
+      {}.tap do |hash| 
+        self.class.salesforce_sync_attribute_mapping.each do |key, value|
+          if self.respond_to?(value)
+
+            #Checkboxes in SFDC Cannot be nil.  Here we check for boolean field type and set nil values to be false
+            attribute_value = self.send(value)
+            if is_boolean?(value) && attribute_value.nil?
+              attribute_value = false
+            end
+
+            hash[key] = attribute_value if include_all || salesforce_should_update_attribute?(value)
+          end
+        end
+      end    
+    end
+
+    def is_boolean?(attribute)
+      self.column_for_attribute(attribute) && self.column_for_attribute(attribute).type == :boolean
+    end
+
+    def salesforce_create_object(attributes)
+      attributes.merge!(self.class.salesforce_web_id_attribute_name.to_s => id) if self.class.salesforce_sync_web_id? && !new_record?
+      @sf_object = "Databasedotcom::#{self.salesforce_object_name}".constantize.create(attributes)
+    end
+
+    def salesforce_update_object(attributes)
+      attributes.merge!(self.class.salesforce_web_id_attribute_name.to_s => id) if self.class.salesforce_sync_web_id? && !new_record?
+      salesforce_object.update_attributes(attributes) if salesforce_object
+    end
+
+    # if attributes specified in the async_attributes array are the only attributes being modified, then sync the data 
+    # via delayed_job
+    def salesforce_perform_async_call?
+      return false if salesforce_attributes_to_update.empty? || self.class.salesforce_async_attributes.empty?
+      salesforce_attributes_to_update.keys.all? {|key| self.class.salesforce_async_attributes.include?(key) } && salesforce_id.present?
+    end
+
+    # sync model data to Salesforce, adding any Salesforce validation errors to the models errors
+    def salesforce_sync
+      return if self.salesforce_skip_sync?
+
+      if salesforce_perform_async_call?
+        Delayed::Job.enqueue(SalesforceArSync::SalesforceObjectSync.new(self.class.salesforce_web_class_name, self.salesforce_object_name, salesforce_id, salesforce_attributes_to_update), :priority => 50)
+      else
+        salesforce_update_object(salesforce_attributes_to_update) if salesforce_attributes_to_update.present? && salesforce_object
+        salesforce_create_object(salesforce_attributes_to_update(!new_record?)) if salesforce_id.nil? && salesforce_object.nil?
+
+        self.salesforce_id = salesforce_object.send(self.class.salesforce_id_attribute_name) unless salesforce_object.nil?
+      end
+    rescue Exception => ex
+      self.errors[:base] << ex.message
+      return false
+    end
+
+    def sync_web_id
+      return false if !self.class.salesforce_sync_web_id? || self.salesforce_skip_sync?
+      salesforce_object.update_attribute(self.class.salesforce_web_id_attribute_name.to_s, id) if salesforce_id && salesforce_object
+    end    
+  end
+end

data/lib/salesforce_ar_sync/soap_handler/base.rb

@@ -0,0 +1,57 @@
+module SalesforceArSync
+  module SoapHandler
+    class Base
+      attr_reader :xml_hashed, :options, :sobjects
+
+      def initialize organization, options = {}
+        @options = options
+        @xml_hashed = options
+        @organization = SALESFORCE_AR_SYNC_CONFIG["ORGANIZATION_ID"]
+        @sobjects = collect_sobjects if valid?
+      end
+
+      # queues each individual record from the message for update
+      def process_notifications(priority = 90)
+        batch_process do |sobject|
+          options[:klass].camelize.constantize.delay(:priority => priority, :run_at => 5.seconds.from_now).salesforce_update(sobject)
+        end
+      end
+
+      # ensures that the received message is properly formed, and that it comes from the expected Salesforce Org
+      def valid?
+        notifications = @xml_hashed.try(:[], "Envelope").try(:[], "Body").try(:[], "notifications")
+
+        organization_id = notifications.try(:[], "OrganizationId")
+        return !notifications.try(:[], "Notification").nil? && organization_id == @organization # we sent this to ourselves
+      end
+
+      def batch_process(&block)
+        return if sobjects.nil? || !block_given?
+        sobjects.each do | sobject |
+          yield sobject
+        end
+      end
+
+      #xml for SFDC response
+      #called from soap_message_controller
+      def generate_response(error = nil)      
+        response = "<Ack>#{sobjects.nil? ? false : true}</Ack>" unless error
+        if error 
+          response = "<soapenv:Fault><faultcode>soap:Receiver</faultcode><faultstring>#{error.message}</faultstring></soapenv:Fault>"
+        end
+        return "<?xml version=\"1.0\" encoding=\"UTF-8\"?><soapenv:Envelope xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"><soapenv:Body><notificationsResponse>#{response}</notificationsResponse></soapenv:Body></soapenv:Envelope>"
+      end
+    
+      private
+
+      def collect_sobjects
+        notification = @xml_hashed["Envelope"]["Body"]["notifications"]["Notification"] 
+        if notification.is_a? Array
+          return notification.collect{ |h| h["sObject"].symbolize_keys}
+        else
+          return [notification["sObject"].try(:symbolize_keys)]
+        end
+      end
+    end
+  end
+end

data/lib/salesforce_ar_sync/soap_handler/delete.rb

@@ -0,0 +1,19 @@
+module SalesforceArSync
+  module SoapHandler
+    class Delete < SalesforceArSync::SoapHandler::Base
+       def process_notifications(priority = 90)
+         batch_process do |sobject|
+           SalesforceArSync::SoapHandler::Delete.delay(:priority => priority, :run_at => 5.seconds.from_now).delete_object(sobject)
+         end
+       end
+
+       def self.delete_object(hash = {})
+         raise ArgumentError, "Object_Id__c parameter required" if hash[:Object_Id__c].blank?
+         raise ArgumentError, "Object_Type__c parameter required" if hash[:Object_Type__c].blank?
+     
+         object = hash[:Object_Type__c].constantize.find_by_salesforce_id(hash[:Object_Id__c])
+         object.destroy if object
+       end
+     end
+   end
+ end

data/lib/salesforce_ar_sync/version.rb

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

metadata

@@ -0,0 +1,212 @@
+--- !ruby/object:Gem::Specification
+name: salesforce_ar_sync
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Michael Halliday
+- Nick Neufeld
+- Andrew Coates
+- Devon Noonan
+- Liam Nediger
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-09-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ammeter
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.2.8
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.2.8
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: supermodel
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: databasedotcom
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ActiveRecord extension & rails engine for syncing data with Salesforce.com
+email:
+- mhalliday@infotech.com
+- nneufeld@infotech.com
+- acoates@infotech.com
+- dnoonan@infotech.com
+- lnediger@infotech.com.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- LICENSE
+- lib/generators/salesforce_ar_sync/configuration/configuration_generator.rb
+- lib/generators/salesforce_ar_sync/configuration/templates/salesforce_ar_sync.yml
+- lib/generators/salesforce_ar_sync/migrations/migrations_generator.rb
+- lib/generators/salesforce_ar_sync/migrations/templates/migration.rb
+- lib/salesforce_ar_sync/engine.rb
+- lib/salesforce_ar_sync/extenders/salesforce_syncable.rb
+- lib/salesforce_ar_sync/ip_constraint.rb
+- lib/salesforce_ar_sync/salesforce_object_sync.rb
+- lib/salesforce_ar_sync/salesforce_sync.rb
+- lib/salesforce_ar_sync/soap_handler/base.rb
+- lib/salesforce_ar_sync/soap_handler/delete.rb
+- lib/salesforce_ar_sync/version.rb
+- lib/salesforce_ar_sync.rb
+homepage: http://github.com/InfoTech/
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: ActiveRecord extension & rails engine for syncing data with Salesforce.com
+test_files: []