netsuite_rails 0.1.0

data/.gitignore

@@ -0,0 +1,2 @@
+Gemfile.lock
+vendor/

data/Gemfile

@@ -0,0 +1,11 @@
+source 'https://rubygems.org'
+gemspec
+
+# TODO would like to support easy NetSuite VCR recording in the future
+# group :test do
+#   gem 'vcr'
+#   gem 'rspec', '~> 2.14'
+#   gem 'rack-test'
+#   gem 'webmock'
+#   gem 'shoulda-matchers'
+# end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Michael Bianco
+
+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,57 @@
+# NetSuite Rails
+
+**Note:** Documentation is horrible... look at the code for details.
+
+Build custom rails application that sync to NetSuite.
+
+## Installation
+
+```ruby
+gem 'netsuite_rails'
+```
+
+Install the database migration for poll timestamps
+
+```bash
+rails g netsuite_rails:install
+```
+
+### Date & Time
+
+```ruby
+NetSuiteRails.configure do
+	
+end
+```
+
+## Usage
+
+modes: :read, :read_write, :aggressive
+
+When using a proc in a NS mapping, you are responsible for setting local and remote values
+
+for pushing tasks to DJ https://github.com/collectiveidea/delayed_job/wiki/Rake-Task-as-a-Delayed-Job
+
+### Syncing
+
+```bash
+rake netsuite:sync
+
+rake netsuite:fresh_sync
+```
+
+Caveats:
+
+* If you have date time fields, or custom fields that will trigger `changed_attributes` this might cause issues when pulling an existing record
+* `changed_attributes` doesn't work well with store
+
+## Testing
+
+```ruby
+# in spec_helper.rb
+require 'netsuite_rails/spec/spec_helper'
+```
+
+## Author
+
+* Michael Bianco @iloveitaly

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/lib/generators/netsuite_rails/install_generator.rb

@@ -0,0 +1,25 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+require 'rails/generators/active_record'
+
+module NetsuiteRails
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      # http://stackoverflow.com/questions/4141739/generators-and-migrations-in-plugins-rails-3
+
+      if Rails::VERSION::STRING.start_with?('3.2')
+        include Rails::Generators::Migration
+        extend ActiveRecord::Generators::Migration
+      else
+        include ActiveRecord::Generators::Migration
+      end
+
+      source_root File.expand_path('../templates', __FILE__)
+
+      def copy_migration
+        migration_template "create_netsuite_poll_timestamps.rb", "db/migrate/create_netsuite_poll_timestamps.rb"
+      end
+
+    end
+  end
+end

data/lib/generators/netsuite_rails/templates/create_netsuite_poll_timestamps.rb

@@ -0,0 +1,12 @@
+class CreateNetsuitePollTimestamps < ActiveRecord::Migration
+  def change
+    create_table :netsuite_poll_timestamps do |t|
+      t.string     :name, :limit => 100
+      t.text       :value
+      t.string     :key
+      t.timestamps
+    end
+
+    add_index :netsuite_poll_timestamps, [:key], :name => 'index_netsuite_poll_timestamps_on_key', :unique => true
+  end
+end

data/lib/netsuite_rails/configuration.rb

@@ -0,0 +1,54 @@
+module NetSuiteRails
+  module Configuration
+    extend self
+
+    def reset!
+      attributes.clear
+    end
+
+    def attributes
+      @attributes ||= {}
+    end
+
+    def netsuite_sync_mode(mode = nil)
+      if mode.nil?
+        attributes[:sync_mode] ||= :none
+      else
+        attributes[:sync_mode] = mode
+      end
+    end
+
+    def netsuite_push_disabled(flag = nil)
+      if flag.nil?
+        attributes[:flag] ||= false
+      else
+        attributes[:flag] = flag
+      end
+    end
+
+    def netsuite_pull_disabled(flag = nil)
+      if flag.nil?
+        attributes[:flag] ||= false
+      else
+        attributes[:flag] = flag
+      end
+    end
+
+    def netsuite_instance_time_zone_offset(zone_offset = nil)
+      if zone_offset.nil?
+        attributes[:zone_offset] ||= -8
+      else
+        attributes[:zone_offset] = zone_offset
+      end
+    end
+
+    def polling_page_size(size = nil)
+      if size.nil?
+        attributes[:size] ||= 1000
+      else
+        attributes[:size] = size
+      end
+    end
+
+  end
+end

data/lib/netsuite_rails/list_sync/pull_manager.rb

@@ -0,0 +1,33 @@
+module NetSuiteRails
+  module ListSync
+
+    class PullManager
+      class << self
+
+        def poll(klass, opts = {})
+          custom_list = NetSuite::Records::CustomList.get(klass.netsuite_list_id)
+
+          process_results(custom_list.custom_value_list.custom_value)
+        end
+
+        def process_results(klass, opts, list)
+          list.each do |custom_value|
+            local_record = klass.where(netsuite_id: custom_value.attributes[:value_id]).first_or_initialize
+
+            if local_record.respond_to?(:value=)
+              local_record.value = custom_value.attributes[:value]
+            end
+
+            if local_record.respond_to?(:inactive=)
+              local_record.inactive = custom_value.attributes[:is_inactive]
+            end
+
+            local_record.save!
+          end
+        end
+
+      end
+    end
+
+  end
+end

data/lib/netsuite_rails/list_sync.rb

@@ -0,0 +1,25 @@
+module NetSuiteRails
+  module ListSync
+
+    def self.included(klass)
+      klass.send(:extend, ClassMethods)
+
+      PollManager.attach(klass)
+    end
+
+    module ClassMethods
+      def netsuite_list_id(internal_id = nil)
+        if internal_id.nil?
+          @netsuite_list_id
+        else
+          @netsuite_list_id = internal_id
+        end
+      end
+
+      def netsuite_poll(opts = {})
+        NetSuiteRails::ListSync::PullManager.poll(self, opts)
+      end
+    end
+
+  end
+end

data/lib/netsuite_rails/netsuite_rails.rb

@@ -0,0 +1,22 @@
+require 'netsuite_rails/configuration'
+require 'netsuite_rails/poll_timestamp'
+require 'netsuite_rails/transformations'
+require 'netsuite_rails/poll_manager'
+require 'netsuite_rails/sync_trigger'
+require 'netsuite_rails/sub_list_sync'
+require 'netsuite_rails/record_sync'
+require 'netsuite_rails/record_sync/pull_manager'
+require 'netsuite_rails/record_sync/push_manager'
+require 'netsuite_rails/list_sync'
+require 'netsuite_rails/list_sync/pull_manager'
+require 'netsuite_rails/url_helper'
+
+module NetSuiteRails
+
+  class Railtie < ::Rails::Railtie
+    rake_tasks do
+      load 'netsuite_rails/tasks/netsuite.rb'
+    end
+  end
+
+end

data/lib/netsuite_rails/poll_manager.rb

@@ -0,0 +1,62 @@
+module NetSuiteRails
+  class PollManager
+
+    class << self
+
+      def attach(klass)
+        @record_models ||= []
+        @list_models ||= []
+
+        if klass.include? RecordSync
+          @record_models << klass
+        elsif klass.include? ListSync
+          @list_models << klass
+        end
+      end
+
+      def sync(opts = {})
+        record_models = opts[:record_models] || @record_models
+        list_models = opts[:list_models] || @list_models
+
+        list_models.each do |klass|
+          Rails.logger.info "NetSuite: Syncing #{klass}"
+          klass.netsuite_poll
+        end
+
+        record_models.each do |klass|
+          sync_frequency = klass.netsuite_sync_options[:frequency] || 1.day
+
+          if sync_frequency == :never
+            Rails.logger.info "Not syncing #{klass.to_s}"
+            next
+          end
+
+          Rails.logger.info "NetSuite: Syncing #{klass.to_s}"
+          
+          preference = PollTimestamp.where(key: "netsuite_poll_#{klass.to_s.downcase}timestamp").first_or_initialize
+
+          # check if we've never synced before
+          if preference.new_record?
+            klass.netsuite_poll({ import_all: true }.merge(opts))
+          else
+            # TODO look into removing the conditional parsing; I don't think this is needed
+            last_poll_date = preference.value
+            last_poll_date = DateTime.parse(last_poll_date) unless last_poll_date.is_a?(DateTime)
+
+            if DateTime.now - last_poll_date > sync_frequency
+              Rails.logger.info "NetSuite: Syncing #{klass} modified since #{last_poll_date}"
+              klass.netsuite_poll({ last_poll: last_poll_date }.merge(opts))
+            else
+              Rails.logger.info "NetSuite: Skipping #{klass} because of syncing frequency"
+            end
+          end
+
+          preference.value = DateTime.now
+          preference.save!
+        end
+      end
+      
+    end
+
+  end
+end

data/lib/netsuite_rails/poll_timestamp.rb

@@ -0,0 +1,11 @@
+module NetSuiteRails
+  class PollTimestamp < ActiveRecord::Base
+    serialize :value
+
+    validates :key, presence: true, uniqueness: true
+
+    def self.table_name_prefix
+      'netsuite_'
+    end
+  end
+end

data/lib/netsuite_rails/record_sync/pull_manager.rb

@@ -0,0 +1,147 @@
+module NetSuiteRails
+  module RecordSync
+
+    class PullManager
+      class << self
+
+        def poll(klass, opts = {})
+          opts = {
+            import_all: false,
+            page_size: NetSuiteRails::Configuration.polling_page_size,
+          }.merge(opts)
+
+          opts[:netsuite_record_class] ||= klass.netsuite_record_class
+
+          search = opts[:netsuite_record_class].search(
+            poll_criteria(klass, opts).merge({
+              preferences: {
+                body_fields_only: false,
+                page_size: opts[:page_size]
+              }
+            })
+          )
+
+          # TODO more robust error reporting
+          unless search
+            raise 'error running netsuite sync'
+          end
+
+          process_search_results(klass, opts, search)
+        end
+
+        def poll_criteria(klass, opts)
+          search_criteria = {
+            criteria: {
+              basic: poll_basic_criteria(klass, opts)
+            }
+          }
+
+          saved_search_id = opts[:saved_search_id] || klass.netsuite_sync_options[:saved_search_id]
+
+          if saved_search_id
+            search_criteria[:criteria][:saved] = saved_search_id
+          end
+
+          if needs_get_list?(opts)
+            search_criteria[:columns] = {
+              'listRel:basic' => [
+                'platformCommon:internalId/' => {},
+              ],
+            }
+          end
+
+          search_criteria
+        end
+
+        def poll_basic_criteria(klass, opts)
+          opts = {
+            criteria: [],
+            # last_poll: DateTime
+          }.merge(opts)
+
+          # allow custom criteria to be passed directly to the sync call
+          criteria = opts[:criteria] || []
+
+          # allow custom criteria from the model level
+          criteria += klass.netsuite_sync_options[:criteria] || []
+
+          if opts[:netsuite_record_class] == NetSuite::Records::CustomRecord
+            opts[:netsuite_custom_record_type_id] ||= klass.netsuite_custom_record_type_id
+            
+            criteria << {
+              field: 'recType',
+              operator: 'is',
+              value: NetSuite::Records::CustomRecordRef.new(internal_id: opts[:netsuite_custom_record_type_id])
+            }
+          end
+
+          unless opts[:import_all]
+            criteria << {
+              # CustomRecordSearchBasic uses lastModified instead of the standard lastModifiedDate
+              field: (klass.netsuite_custom_record?) ? 'lastModified' : 'lastModifiedDate',
+              operator: 'after',
+              value: opts[:last_poll]
+            }
+          end
+
+          criteria
+        end
+
+        def process_search_results(klass, opts, search)
+          opts = {
+            skip_existing: false,
+            full_record_data: -1,
+          }.merge(opts)
+
+          Rails.logger.info "NetSuite: Processing #{search.total_records} over #{search.total_pages} pages"
+
+          # TODO need to improve the conditional here to match the get_list call conditional belo
+          if opts[:import_all] && opts[:skip_existing]
+            synced_netsuite_list = klass.pluck(:netsuite_id)
+          end
+          
+          search.results_in_batches do |batch|
+            # a saved search is processed as a advanced search; advanced search often does not allow you to retrieve
+            # all of the fields (ex: addressbooklist on customer) that a normal search does
+            # the only way to get those fields is to pull down the full record again using getAll
+
+            if needs_get_list?(opts)
+              filtered_netsuite_id_list = batch.map(&:internal_id)
+
+              if opts[:skip_existing] == true
+                filtered_netsuite_id_list.reject! { |netsuite_id| synced_netsuite_list.include?(netsuite_id) }
+              end
+
+              opts[:netsuite_record_class].get_list(list: batch.map(&:internal_id))
+            else
+              batch
+            end.each do |netsuite_record|
+              self.process_search_result_item(klass, opts, netsuite_record)
+            end
+          end
+        end
+
+        def process_search_result_item(klass, opts, netsuite_record)
+          local_record = klass.where(netsuite_id: netsuite_record.internal_id).first_or_initialize
+
+          # when importing lots of records during an import_all skipping imported records is important
+          return if opts[:skip_existing] == true && !local_record.new_record?
+
+          local_record.netsuite_extract_from_record(netsuite_record)
+
+          # TODO optionally throw fatal errors; we want to skip fatal errors on intial import
+
+          unless local_record.save
+            Rails.logger.error "NetSuite: Error pulling record #{klass} NS ID #{netsuite_record.internal_id} #{local_record.errors.full_messages}"
+          end
+        end
+
+        def needs_get_list?(opts)
+          (opts[:saved_search_id].present? && opts[:full_record_data] != false) || opts[:full_record_data] == true
+        end
+
+      end
+    end
+
+  end
+end

data/lib/netsuite_rails/record_sync/push_manager.rb

@@ -0,0 +1,186 @@
+module NetSuiteRails
+  module RecordSync
+
+    class PushManager
+      class << self
+
+        def push(local_record, opts)
+          # TODO check to see if anything is changed before moving forward
+          # if changes_keys.blank? && local_record.netsuite_manual_fields
+
+          netsuite_record = build_netsuite_record(local_record)
+
+          local_record.netsuite_execute_callbacks(local_record.class.before_netsuite_push, netsuite_record)
+
+          if !local_record.new_netsuite_record?
+            push_update(local_record, netsuite_record)
+          else
+            push_add(local_record, netsuite_record)
+          end
+
+          # :aggressive is for custom fields which are based on input – need pull updated values after
+          # the push to netsuite to retrieve the calculated values
+
+          if local_record.netsuite_sync == :aggressive
+            local_record.netsuite_pull
+          end
+
+          local_record.netsuite_execute_callbacks(local_record.class.after_netsuite_push, netsuite_record)
+
+          true
+        end
+
+        def push_add(local_record, netsuite_record)
+          if netsuite_record.add
+            # update_column to avoid triggering another save
+            local_record.update_column(:netsuite_id, netsuite_record.internal_id)
+          else
+            # TODO use NS error class
+            raise "NetSuite: error creating record #{netsuite_record.errors}"
+          end
+        end
+
+        def push_update(local_record, netsuite_record)
+          # build change hash to limit the number of fields pushed to NS on change
+          # NS could have logic which could change field functionality depending on
+          # input data; it's safest to limit the number of field changes pushed to NS
+
+          custom_field_list = local_record.netsuite_field_map[:custom_field_list] || {}
+          all_field_list = eligible_local_fields(local_record)
+
+          update_list = {}
+
+          all_field_list.each do |local_field, netsuite_field|
+            if custom_field_list.keys.include?(local_field)
+              # if custom field has changed, mark and copy over customFieldList later
+              update_list[:custom_field_list] = true
+            else
+              update_list[netsuite_field] = netsuite_record.send(netsuite_field)
+            end
+          end
+
+          # manual field list is for fields manually defined on the NS record
+          # outside the context of ActiveRecord (e.g. in a before_netsuite_push)
+
+          (local_record.netsuite_manual_fields || []).each do |netsuite_field|
+            if netsuite_field == :custom_field_list
+              update_list[:custom_field_list] = true
+            else
+              update_list[netsuite_field] = netsuite_record.send(netsuite_field)
+            end
+          end
+
+          if update_list[:custom_field_list]
+            update_list[:custom_field_list] = netsuite_record.custom_field_list
+          end
+
+          if local_record.netsuite_custom_record?
+            update_list[:rec_type] = netsuite_record.rec_type
+          end
+
+          # TODO consider using upsert here
+
+          if netsuite_record.update(update_list)
+            true
+          else
+            raise "NetSuite: error updating record #{netsuite_record.errors}"
+          end
+        end
+
+        def build_netsuite_record(local_record)
+          netsuite_record = build_netsuite_record_reference(local_record)
+
+          # TODO need to normalize datetime fields
+
+          all_field_list = eligible_local_fields(local_record)
+          custom_field_list = local_record.netsuite_field_map[:custom_field_list] || {}
+          field_hints = local_record.netsuite_field_hints
+
+          all_field_list.each do |local_field, netsuite_field|
+            # allow Procs as field mapping in the record definition for custom mapping
+            if netsuite_field.is_a?(Proc)
+              netsuite_field.call(local_record, netsuite_record, :push)
+              next
+            end
+
+            # TODO pretty sure this will break if we are dealing with has_many 
+
+            netsuite_field_value = if local_record.reflections.has_key?(local_field)
+              if (remote_internal_id = local_record.send(local_field).try(:netsuite_id)).present?
+                { internal_id: remote_internal_id }
+              else
+                nil
+              end
+            else
+              local_record.send(local_field)
+            end
+
+            if field_hints.has_key?(local_field) && netsuite_field_value.present?
+              netsuite_field_value = NetSuiteRails::Transformations.transform(field_hints[local_field], netsuite_field_value)
+            end
+
+            # TODO should we skip setting nil values completely? What if we want to nil out fields on update?
+
+            # be wary of API version issues: https://github.com/NetSweet/netsuite/issues/61
+
+            if custom_field_list.keys.include?(local_field)
+              netsuite_record.custom_field_list.send(:"#{netsuite_field}=", netsuite_field_value)
+            else
+              netsuite_record.send(:"#{netsuite_field}=", netsuite_field_value)
+            end
+          end
+
+          netsuite_record
+        end
+
+        def build_netsuite_record_reference(local_record)
+          # must set internal_id for records on new; will be set to nil if new record
+
+          netsuite_record = local_record.netsuite_record_class.new(internal_id: local_record.netsuite_id)
+
+          if local_record.netsuite_custom_record?
+            netsuite_record.rec_type = NetSuite::Records::CustomRecord.new(internal_id: local_record.class.netsuite_custom_record_type_id)
+          end
+
+          netsuite_record
+        end
+
+        def eligible_local_fields(local_record)
+          custom_field_list = local_record.netsuite_field_map[:custom_field_list] || {}
+          all_field_list = local_record.netsuite_field_map.except(:custom_field_list) || {}
+
+          all_field_list.merge!(custom_field_list)
+
+          changed_keys = changed_attributes(local_record)
+
+          # filter out unchanged keys when updating record
+          unless local_record.new_netsuite_record?
+            all_field_list.select! { |k,v| changed_keys.include?(k) }
+          end
+
+          all_field_list
+        end
+
+        def changed_attributes(local_record)
+          # otherwise filter only by attributes that have been changed
+          # limiting the delta sent to NS will reduce hitting edge cases
+
+          # TODO think about has_many / join table changes
+
+          association_field_key_mapping = local_record.reflections.values.reject(&:collection?).inject({}) do |h, a|
+            h[a.association_foreign_key.to_sym] = a.name
+            h
+          end
+
+          # convert relationship symbols from :object_id to :object
+          local_record.changed_attributes.keys.map do |k|
+            association_field_key_mapping[k.to_sym] || k.to_sym
+          end
+        end
+
+
+      end
+    end
+
+  end
+end