draisine 0.7.10

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d532674344caaa230a569619645f1741bc250576
+  data.tar.gz: dfa98a38eaace1c4358310a3580c87020d8ee016
+SHA512:
+  metadata.gz: 7c94c9310d3dea3f8d4a64f2c07bd162dc8409ad18fa715f575c80e271656d43e37e8335e2d146c27447ba6d6cfea50375313cf1503d76daa533508b2f37a1e9
+  data.tar.gz: df7c45a1aace9a9775ac5ea2bf0e3b1f8cecf260e72d3593c02778b602c647a08e65ed828930d02353ad4477d9172c6028e1ce8a0be90859e96bfb5aa497a8ca

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.2.1
+before_install: gem install bundler -v 1.11.2

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in draisine.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,70 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+## Uncomment and set this to only include directories you want to watch
+# directories %w(app lib config test spec features) \
+#  .select{|d| Dir.exists?(d) ? d : UI.warning("Directory #{d} does not exist")}
+
+## Note: if you are using the `directories` clause above and you are not
+## watching the project directory ('.'), then you will want to move
+## the Guardfile to a watched dir and symlink it back, e.g.
+#
+#  $ mkdir config
+#  $ mv Guardfile config/
+#  $ ln -s config/Guardfile .
+#
+# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+
+# Note: The cmd option is now required due to the increasing number of ways
+#       rspec may be run, below are examples of the most common uses.
+#  * bundler: 'bundle exec rspec'
+#  * bundler binstubs: 'bin/rspec'
+#  * spring: 'bin/rspec' (This will use spring if running and you have
+#                          installed the spring binstubs per the docs)
+#  * zeus: 'zeus rspec' (requires the server to be started separately)
+#  * 'just' rspec: 'rspec'
+
+guard :rspec, cmd: "bundle exec rspec" do
+  require "guard/rspec/dsl"
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # Feel free to open issues for suggestions and improvements
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+
+  # Rails files
+  rails = dsl.rails(view_extensions: %w(erb haml slim))
+  dsl.watch_spec_files_for(rails.app_files)
+  dsl.watch_spec_files_for(rails.views)
+
+  watch(rails.controllers) do |m|
+    [
+      rspec.spec.("routing/#{m[1]}_routing"),
+      rspec.spec.("controllers/#{m[1]}_controller"),
+      rspec.spec.("acceptance/#{m[1]}")
+    ]
+  end
+
+  # Rails config changes
+  watch(rails.spec_helper)     { rspec.spec_dir }
+  watch(rails.routes)          { "#{rspec.spec_dir}/routing" }
+  watch(rails.app_controller)  { "#{rspec.spec_dir}/controllers" }
+
+  # Capybara features specs
+  watch(rails.view_dirs)     { |m| rspec.spec.("features/#{m[1]}") }
+  watch(rails.layouts)       { |m| rspec.spec.("features/#{m[1]}") }
+
+  # Turnip features and steps
+  watch(%r{^spec/acceptance/(.+)\.feature$})
+  watch(%r{^spec/acceptance/steps/(.+)_steps\.rb$}) do |m|
+    Dir[File.join("**/#{m[1]}.feature")][0] || "spec/acceptance"
+  end
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Mark Abramov
+
+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,134 @@
+# Draisine
+
+![Cho-choo](https://upload.wikimedia.org/wikipedia/commons/thumb/3/3d/GAZ-13_Chaika_draisine.jpg/600px-GAZ-13_Chaika_draisine.jpg)
+
+A bi-directional syncing solution for Salesforce and ActiveRecord.
+
+Gem overall design is heavily inspired by InfoTech's [salesforce_ar_sync gem](https://github.com/InfoTech/salesforce_ar_sync), but with focus on clearer and more modular code.
+
+## Dependencies
+
+* Rails 4.2+ (for ActiveJob)
+* databasedotcom (for salesforce connections)
+
+
+## Installation and configuration
+
+After you've got the gem installed, you will need to setup the salesforce client. For example:
+
+```
+sf_client = Databasedotcom::Client.new("config/databasedotcom.yml")
+sf_client.authenticate :username => <username>, :password => <password>
+Draisine.salesforce_client = sf_client
+```
+
+You will also need to have your organization id set up:
+
+```
+Draisine.organization_id = '123456789012345678'
+```
+
+Use this [tool](https://cloudjedi.wordpress.com/no-fuss-salesforce-id-converter/) to convert your 15-char org id into 18-char.
+
+## Usage
+
+Draisine adds a `salesforce_syncable` macro to ActiveRecord models, used like this:
+
+```
+class Lead < Salesforce::Model
+  salesforce_syncable synced_attributes: [:FirstName, :LastName, ...],
+    mapping: { 'FirstName' => 'first_name', 'LastName' => 'last_name' },
+    operations: [:outbound_create, :outbound_update, :outbound_delete, :inbound_update, :inbound_delete],
+    salesforce_object_name: 'Lead',
+    sync: true
+end
+```
+
+Your model class must have `salesforce_id` string column for everything to work.
+
+### Available options
+
+#### salesforce_object_name (String)
+
+Self-explanatory. Defaults to the class name.
+
+#### synced_attributes (Array[Symbol|String], required)
+
+List of all Salesforce attributes that are required to be synced. If your ActiveRecord attributes should have different names, you can remap them later.
+
+#### mapping (Hash[String => String])
+
+#### sync (Boolean, default: true)
+
+When set to true, all jobs are launched inline (via `#perform_now`), otherwise, they are set to perform as soon as workers get to them (`#perform_later`).
+
+#### operations (Array[Symbol])
+
+List of operations that must be synced with Salesforce.
+
+Available operations: `[:outbound_create, :outbound_update, :outbound_delete, :inbound_update, :inbound_delete]`
+
+#### non_audited_attributes (Array[Symbol|String])
+
+## Setting up outbound messages
+
+In the left sidebar of salesforce interface, choose Create -> Workflow & Approvals -> Workflow Rules. Then click "New Rule". The rest is more or less self-explanatory. You would want to have all the necessary fields attached to your outbound message.
+
+Assuming you mount draisine engine to `/salesforce`, endpoint url would be `/salesforce/sf_soap/lead` (for Lead object). Make sure you use full proper URL since salesforce will not follow redirects.
+
+You can check out status for the latest sent messages in the Monitoring -> Outbound Messages section.
+
+## Handling special object types, e.g. `LeadHistory`
+
+Some object types in salesforce are not directly user-editable and can't be set up to send outbound messages. One example of such object is LeadHistory. That means you'll have to poll them yourselves. Easiest way to do so is sort by `Id` both on your model (also known as `salesforce_id`) and at salesforce and get only the records with Id > max(salesforce_id).
+
+## Handling inbound deletes
+
+Salesforce only sends outbound messages for record creates and updates, to sync deletes you'll have to go extra mile. You'll need to create a custom object, called `Deleted_Object` that has two fields: `Object_Id (text (18))` and `Object_Type (text (128))` and a trigger for every observed model that creates an instance of such object after every delete. Then you'll need to setup outbound messaging, like for a normal model, but use `/sf_soap/delete` instead of `/sf_soap/<modelname>` for endpoint.
+
+See a [trigger example](salesforce/sample_delete_trigger.apex) and a [corresponding test class](salesforce/sample_test_class_for_delete_trigger.apex).
+
+
+### How to create trigger on your production instance
+
+You might notice that unlike your sandbox instance, your production instance doesn't have "new trigger" button. Congratulations and welcome to Salesforce! You can't create new triggers on production instances directly, you'll have to use something called inbound/outbound change sets. In a nutshell, it's a protocol for generic object exchange between salesforce instances. Long story short, you'll need to export your apex trigger with its test class from sandbox to production instance.
+
+To do so, go Deploy -> Outbound Change Set -> New -> etc etc etc.
+
+If you export Deleted Object this way, don't forget to add custom fields to your change set. Also you must add test coverage for your trigger to the changeset or it won't apply. Good luck.
+
+
+## Error handling
+
+You can setup handling most transient errors using `Draisine.job_error_handler = proc {|exception, job, arguments| }` setter. It will be called every time a job, such as `InboundUpdateJob` fails with any error.
+
+## Roadmap
+
+
+* ~~ActiveRecord plugin and hooks~~
+* ~~ActiveRecord -> Salesforce synchronization (outbound creates, updates, deletes)~~
+* ~~ActiveJob delayed jobs~~
+* ~~Salesforce -> ActiveRecord inbound updates~~
+* ~~Salesforce -> ActiveRecord inbound deletes~~
+* ~~Error handling inside delayed jobs~~
+* ~~Auditing~~
+* ~~Migration generator~~
+* ~~Conflict resolution~~
+* Use restforce instead of / alongside databasedotcom
+
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/chloeandisabel/draisine.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/app/controllers/draisine/soap_controller.rb

@@ -0,0 +1,49 @@
+module Draisine
+  class SoapController < ApplicationController
+    protect_from_forgery with: :null_session
+
+    before_filter :validate_ip
+
+    def update
+      message = request.body.read
+      if Draisine.sync_soap_operations?
+        Draisine::SoapUpdateJob.perform_now(message)
+      else
+        Draisine::SoapUpdateJob.perform_later(message)
+      end
+
+      render xml: xml_response, status: :created
+    end
+
+    def delete
+      message = request.body.read
+      if Draisine.sync_soap_operations?
+        Draisine::SoapDeleteJob.perform_now(message)
+      else
+        Draisine::SoapDeleteJob.perform_later(message)
+      end
+
+      render xml: xml_response, status: :created
+    end
+
+    protected
+
+    def validate_ip
+      ip_checker = IpChecker.new(Draisine.allowed_ip_ranges)
+      unless ip_checker.check(request.remote_ip)
+        render nothing: true, status: :forbidden
+      end
+    end
+
+    def xml_response
+      <<-EOF
+<?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><Ack>true</Ack></notificationsResponse>
+</soapenv:Body>
+</soapenv:Envelope>
+EOF
+    end
+  end
+end

data/bin/console

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "draisine"
+require "pry"
+
+Pry.start

data/bin/setup

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install

data/config/routes.rb

@@ -0,0 +1,4 @@
+Draisine::Engine.routes.draw do
+  post '/sf_soap/delete' => 'draisine/soap#delete'
+  post '/sf_soap/*klass' => 'draisine/soap#update'
+end

data/draisine.gemspec

@@ -0,0 +1,32 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'draisine/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "draisine"
+  spec.version       = Draisine::VERSION
+  spec.authors       = ["Mark Abramov"]
+  spec.email         = ["mark.abramov@chloeandisabel.com"]
+
+  spec.summary       = %q{Synchronization machinery for salesforce}
+  spec.description   = %q{Bidirectional synchronization for salesforce / activerecord}
+  spec.homepage      = "https://github.com/chloeandisabel/draisine"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.11"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rspec-collection_matchers"
+  spec.add_development_dependency "guard"
+  spec.add_development_dependency "guard-rspec"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "sqlite3"
+  spec.add_runtime_dependency "rails", ">= 4.2"
+  spec.add_runtime_dependency "databasedotcom", "~> 1.3"
+end

data/lib/draisine/active_record.rb

@@ -0,0 +1,191 @@
+module Draisine
+  ALL_OPS = [:outbound_create, :outbound_update, :outbound_delete,
+             :inbound_update, :inbound_delete]
+
+  module ActiveRecordMacro
+    def salesforce_syncable(options)
+      include Draisine::ActiveRecordPlugin
+
+      self.salesforce_object_name = options.fetch(:salesforce_object_name, name)
+      salesforce_synced_attributes = options.fetch(:synced_attributes, []).map(&:to_s)
+      default_mapping = salesforce_synced_attributes.map {|k| [k, k] }.to_h
+      mapping = options.fetch(:mapping, {}).map {|k,v| [k.to_s, v.to_s] }.to_h
+      self.salesforce_mapping = default_mapping.merge(mapping)
+      self.salesforce_ops = Set.new(options.fetch(:operations, ALL_OPS))
+      self.salesforce_sync_mode = options.fetch(:sync, true)
+      non_audited_attrs = options.fetch(:non_audited_attributes, []).map(&:to_s)
+      self.salesforce_audited_attributes = salesforce_synced_attributes - non_audited_attrs
+
+      options.fetch(:array_attributes, []).each do |attr|
+        salesforce_array_setter(attr)
+      end
+
+      Draisine.registry.register(self, salesforce_object_name)
+    end
+  end
+
+  module ActiveRecordPlugin
+    extend ActiveSupport::Concern
+    include Draisine::Concerns::ArraySetter
+    include Draisine::Concerns::AttributesMapping
+    include Draisine::Concerns::Import
+
+    module ClassMethods
+      attr_accessor :salesforce_object_name
+      attr_accessor :salesforce_audited_attributes
+      attr_accessor :salesforce_ops
+      attr_accessor :salesforce_sync_mode
+
+      ALL_OPS.each do |op|
+        define_method("salesforce_#{op}?") do
+          salesforce_ops.include?(op)
+        end
+      end
+
+      def salesforce_enqueue_or_run(job_class, *args, &block)
+        if salesforce_sync_mode
+          job_class.perform_now(*args, &block)
+        else
+          job_class.perform_later(*args, &block)
+        end
+      end
+
+      def salesforce_on_inbound_update(attributes)
+        salesforce_enqueue_or_run(InboundUpdateJob, self.name, attributes)
+      end
+
+      def salesforce_inbound_update(attributes, add_blanks = true)
+        if salesforce_inbound_update?
+          attributes = attributes.with_indifferent_access
+          id = attributes.fetch('Id')
+          (find_by(salesforce_id: id) || new).tap do |m|
+            m.salesforce_id = id
+            m.salesforce_inbound_update(attributes, add_blanks)
+          end
+        end
+      end
+
+      def salesforce_on_inbound_delete(salesforce_id)
+        salesforce_enqueue_or_run(InboundDeleteJob, self.name, salesforce_id)
+      end
+
+      def salesforce_inbound_delete(salesforce_id)
+        if salesforce_inbound_delete?
+          record = find_by(salesforce_id: salesforce_id)
+          if record
+            record.salesforce_skip_sync = true
+            record.destroy
+            salesforce_callback(:inbound_delete, salesforce_id)
+          end
+        end
+      end
+
+      def salesforce_syncer
+        @salesforce_syncer || Syncer.new(salesforce_object_name)
+      end
+
+      def salesforce_callback(type, salesforce_id, options = {})
+        Draisine.sync_callback.call(type, salesforce_id, options)
+      end
+    end
+
+    attr_accessor :salesforce_skip_sync
+
+    included do
+      after_create :salesforce_on_create
+      after_update :salesforce_on_update
+      after_destroy :salesforce_on_delete
+    end
+
+    def salesforce_inbound_update(attributes, add_blanks = true)
+      return unless should_process_inbound_update?(attributes)
+      self.salesforce_skip_sync = true
+      if add_blanks
+        attributes = self.class.salesforce_synced_attributes
+          .map {|attr| [attr, attributes[attr]] }
+          .to_h
+      end
+      salesforce_assign_attributes(attributes)
+      salesforce_callback(persisted? ? :inbound_update : :inbound_create, attributes: attributes)
+      save!
+    end
+
+    def salesforce_on_create
+      if !salesforce_skip_sync && self.class.salesforce_outbound_create?
+        self.class.salesforce_enqueue_or_run(OutboundCreateJob, self)
+      end
+    end
+
+    def salesforce_outbound_create
+      attrs = salesforce_attributes.compact
+      response = salesforce_syncer.create(attrs)
+      self.salesforce_id = response.fetch('id')
+      salesforce_skipping_sync { save! } if persisted?
+      salesforce_callback(:outbound_create, attributes: attrs)
+    end
+
+    def salesforce_on_update
+      if !salesforce_skip_sync && self.class.salesforce_outbound_update?
+        self.class.salesforce_enqueue_or_run(
+          OutboundUpdateJob,
+          self,
+          salesforce_attributes.slice(*changed)
+        )
+      end
+    end
+
+    def salesforce_outbound_update(updated_attributes)
+      self.class.transaction do
+        salesforce_syncer.update(salesforce_id, updated_attributes)
+        timestamp = salesforce_syncer.get_system_modstamp(salesforce_id)
+        update_column(:salesforce_updated_at, timestamp)
+        salesforce_callback(:outbound_update, attributes: updated_attributes)
+      end
+    end
+
+    def salesforce_on_delete
+      if !salesforce_skip_sync && self.class.salesforce_outbound_delete?
+        self.class.salesforce_enqueue_or_run(OutboundDeleteJob, self)
+      end
+    end
+
+    def salesforce_outbound_delete
+      salesforce_syncer.delete(salesforce_id)
+      salesforce_callback(:outbound_delete)
+    end
+
+    def salesforce_skipping_sync(&block)
+      old_sync = self.salesforce_skip_sync
+      self.salesforce_skip_sync = true
+      instance_eval(&block)
+    ensure
+      self.salesforce_skip_sync = old_sync
+    end
+
+    def salesforce_callback(type, options = {})
+      self.class.salesforce_callback(type, salesforce_id, {
+        local_record_type: self.class.name,
+        local_record_id: id
+      }.merge(options))
+    end
+
+    protected
+
+    def should_process_inbound_update?(attributes)
+      !salesforce_updated_at || !attributes['SystemModstamp'] ||
+        Draisine.parse_time(attributes['SystemModstamp']) > salesforce_updated_at
+    end
+
+    def salesforce_syncer
+      self.class.salesforce_syncer
+    end
+  end
+
+  def self.register_ar_macro
+    ActiveRecord::Base.extend(Draisine::ActiveRecordMacro)
+  end
+end
+
+if defined?(ActiveRecord::Base)
+  Draisine.register_ar_macro
+end

data/lib/draisine/auditor/result.rb

@@ -0,0 +1,48 @@
+module Draisine
+  class Auditor
+    Discrepancy = Struct.new(:type, :salesforce_type, :salesforce_id, :local_type, :local_id, :local_attributes, :remote_attributes, :diff_keys)
+
+    class Result
+      attr_reader :discrepancies, :status, :error
+      def initialize
+        @discrepancies = []
+        @status = :running
+        @error = nil
+      end
+
+      def calculate_result!
+        if discrepancies.any?
+          @status = :failure
+        else
+          @status = :success
+        end
+        self
+      end
+
+      def error!(ex)
+        @error = ex
+        @status = :failure
+        self
+      end
+
+      def success?
+        @status == :success
+      end
+
+      def failure?
+        @status == :failure
+      end
+
+      def running?
+        @status == :running
+      end
+
+      def discrepancy(type:, salesforce_type:, salesforce_id:,
+          local_type: nil, local_id: nil, local_attributes: nil, remote_attributes: nil, diff_keys: nil)
+
+        discrepancies << Discrepancy.new(type, salesforce_type, salesforce_id,
+          local_type, local_id, local_attributes, remote_attributes, diff_keys)
+      end
+    end
+  end
+end