netsuite_rails 0.2.2 → 0.3.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    YTVkYzk2NDQyNzI5MGZjODkxOTM4MWFkYjExYTNlZWZkNGFjNjFmMQ==
+  data.tar.gz: !binary |-
+    NjdmOWIxMmE0MjNkYjE2MTU2ZDBmMzg4MDViNWZjMzdmZGIwZjgzOQ==
+SHA512:
+  metadata.gz: !binary |-
+    OWJlMzFhMGJhNTM1NGZkMjRmMGMwNmU2ZmUzZTFhODQxMGQzYjZhMWNmMjE2
+    M2NlYjgwMTc0MWU4Y2FhMTBjNWVjZGM0NzU2NWIxNDY1NjMzYTE2N2ZlYWM4
+    N2NkOTY2ZTJhNzBiMDg2NjY0MTY4ZWYyYmMxNjk4NDc3NzQ5NjQ=
+  data.tar.gz: !binary |-
+    MDE5NmE5OWZmYjhjYzIyMGQ3ZmFmMzljZDc1ZTkwZDQ1MjRjYjUyZTk4MjAx
+    YjI2NTM1YmZmNWE5NjE0MGZhMzg1NmZlOTA5ZDA0NWU0OWU2ODgyNmM4NzMx
+    YzUxOTY5ODQ1MDQ0YWE3NTNkY2YwYjA1NmY4YThlNjUyNTgwMDc=

data/Gemfile

@@ -8,6 +8,8 @@ group :test do
   # gem 'rack-test'
   # gem 'webmock'
 
+  gem 'simplecov', :require => false
+
   gem 'faker'
   gem 'shoulda-matchers'
   gem 'rails', '3.2.16'
@@ -15,7 +17,7 @@ group :test do
 
   gem 'rspec-rails', '~> 3.1'
   gem 'pry-nav'
-  
+
   gem 'rerun'
   gem 'rb-fsevent'
-end
+end

data/README.md

@@ -1,10 +1,90 @@
-[![Build Status](https://travis-ci.org/NetSweet/netsuite_rails.svg?branch=master)](https://travis-ci.org/NetSweet/netsuite_rails)
+[![Circle CI](https://circleci.com/gh/NetSweet/netsuite_rails.svg?style=svg)](https://circleci.com/gh/NetSweet/netsuite_rails)
+[![Slack Status](https://opensuite-slackin.herokuapp.com/badge.svg)](http://opensuite-slackin.herokuapp.com)
 
 # NetSuite Rails
 
-**Note:** Documentation is horrible... look at the code for details.
+**<span style="color: red">Note:</span>** Documentation is horrible: PRs welcome. Look at the code for details.
 
-Build custom Ruby on Rails applications that sync to NetSuite.
+Build Ruby on Rails applications that sync ActiveRecord (ActiveModel and plain old ruby objects too) in real-time to NetSuite. Here's an example:
+
+```ruby
+class Item < ActiveRecord::Base
+  include NetSuiteRails::RecordSync
+
+  # specify the NS record that your rails model maps to
+  netsuite_record_class NetSuite::Records::InventoryItem
+
+  netsuite_sync :read_write,
+    # specify the frequency that your app should poll NetSuite for updates
+    frequency: 1.day,
+    # it's possible to base syncing off of a saved search. Be sure that "Internal ID" is one of your search result columns
+    saved_search_id: 123,
+    # limit pushing to NetSuite based on conditional
+    if: -> { self.a_condition? },
+    # limit pulling from NetSuite based on conditional. This is only
+    # considered when handling a single pull
+    pull_if: -> { self.another_condition? },
+
+    # accepted values are :async and :sync. Default is :async
+    mode: :sync
+
+
+  # local => remote field mapping
+  netsuite_field_map({
+    :item_number => :item_id,
+    :name => :display_name,
+
+    # the corresponding NetSuite field must be manually specified in before_netsuite_push
+    :user => Proc.new do |local_rails_record, netsuite_record, sync_direction|
+    	if direction == :pull
+
+    	elsif direction == :push
+
+    	end
+    end,
+
+    :custom_field_list => {
+    	:a_local_field => :custrecord_remote_field
+    	:a_special_local_field => Proc.new do |local, ns_record, direction|
+    		if direction == :push
+    		  # if proc is used with a field mapping, the field must be specified in `netsuite_manual_fields`
+    		  ns_record.custom_field_list.custentity_special_long = 1
+          ns_record.custom_field_list.custentity_special_long.type = 'platformCore:LongCustomFieldRef'
+    		end
+    	end
+    }
+  })
+
+  # sanitizes input from rails to ensure NS doesn't throw a fatal error
+  netsuite_field_hints({
+    :phone => :phone,
+    :email => :email
+  })
+
+  before_netsuite_push do |netsuite_record|
+    self.netsuite_manual_fields = [ :entity, :custom_field_list ]
+  end
+end
+```
+
+Your ruby model:
+
+* Needs to have a `netsuite_id` and `netsuite_id=` method
+* Does not need to be an `ActiveRecord` model. If you don't use ActiveRecord it is your responsibility
+  to trigger `Model#netsuite_push`.
+
+Notes:
+
+* If `sync_mode == :async` `model.save` will be run if a record is created referencing an existing NetSuite object: `model.create! netsuite_id: 123`
+* If you are using `update`, a `update` call will not be run if no changed fields are detected. If you are manually using fields specify them with `netsuite_manual_fields`
+
+## Using Upsert
+
+TODO generating external ID tag
+
+TODO configuring upsert
+
+TODO add vs upsert consideration
 
 ## Installation
 
@@ -12,43 +92,121 @@ Build custom Ruby on Rails applications that sync to NetSuite.
 gem 'netsuite_rails'
 ```
 
-Install the database migration for poll timestamps
+Install the database migration to persist poll timestamps:
 
 ```bash
 rails g netsuite_rails:install
 ```
 
-### Date & Time
+This helps netsuite_rails to know when the last time your rails DB was synced with the NS.
+
+## Date
+
+
+## Time
+
+"Time of Day" fields in NetSuite are especially tricky. To ensure that times don't shift when you push them to NetSuite here are some tips:
+
+1. Take a look at the company time zone setup. This is in Setup
+2. Ensure your WebService's Employee record has either:
+  * No time zone set
+  * The same time zone as the company
+3. Ensure that the WebService's GUI preferences have the same time zone settings as the company. This effects how times are translated via SuiteTalk.
+4. Set the `netsuite_instance_time_zone_offset` setting to your company's time zone
 
 ```ruby
 # set your timezone offset
 NetSuiteRails::Configuration.netsuite_instance_time_zone_offset(-6)
 ```
 
+### Changing WebService User's TimeZone Preferences
+
+It might take a couple hours for time zone changes to take effect. [From my experience](http://mikebian.co/netsuite-suitetalk-user-role-edits-are-delayed/), either the time zone changes have some delay associated with them or the time zone implementation is extremely buggy.
+
 ## Usage
 
-modes: :read, :read_write, :aggressive
+### Syncing Options
+
+```
+netsuite_record_class NetSuite::Records::Customer
+netsuite_record_class NetSuite::Records::CustomRecord, 123
+
+netsuite_sync: :read
+netsuite_sync: :read_write
+# TODO not after_netsuite_push replacement for aggressive sync
+
+netsuite_sync: :read, frequency: :never
+netsuite_sync: :read, frequency: 5.minutes
+netsuite_sync: :read, if: -> { self.condition_met? }
+
+```
 
 When using a proc in a NS mapping, you are responsible for setting local and remote values
 
+The default sync frequency is [one day](https://github.com/NetSweet/netsuite_rails/blob/c453326a4190e68a2fd9d7690b2b1f2f105ec8b9/lib/netsuite_rails/poll_trigger.rb#L27).
+
 for pushing tasks to DJ https://github.com/collectiveidea/delayed_job/wiki/Rake-Task-as-a-Delayed-Job
 
 `:if` for controlling when syncing occurs
 
-TODO hooks for before/after push/pull
+Easily disable/enable syncing via env vars:
+
+```ruby
+NetSuiteRails.configure do
+  netsuite_pull_disabled ENV['NETSUITE_PULL_DISABLED'].present? && ENV['NETSUITE_PULL_DISABLED'] == "true"
+  netsuite_push_disabled ENV['NETSUITE_PUSH_DISABLED'].present? && ENV['NETSUITE_PUSH_DISABLED'] == "true"
+
+  if ENV['NETSUITE_DISABLE_SYNC'].present? && ENV['NETSUITE_DISABLE_SYNC'] == "true"
+    netsuite_pull_disabled true
+    netsuite_push_disabled true
+  end
+end
+
+```
+
+### Hooks
+
+```ruby
+# the netsuite record is passed a single argument to this block (or method reference)
+# this provides the opportunity to set custom fields or run custom logic to prepare
+# the record for the NetSuite envoirnment
+before_netsuite_push
+after_netsuite_push
+
+# netsuite_pulling? is true when this callback is executed
+after_netsuite_pull
+```
 
-### Syncing
+### Rake Tasks for Syncing
 
 ```bash
+# update & create local records modified in netsuite sync the last sync time
 rake netsuite:sync
 
+# pull all records in NetSuite and update/create local records
 rake netsuite:fresh_sync
+
+# only update records that have already been synced
+rake netsuite:sync_local RECORD_MODELS=YourModel LIST_MODELS=YourListModel
 ```
 
 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
+* `changed_attributes` doesn't work well with `store`s
+
+### Delayed Job
+
+The more records that use netsuite_rails, the longer you'll need your job timeout to be:
+
+```ruby
+# config/initializers/delayed_job.rb
+Delayed::Worker.max_run_time = 80.minutes
+```
+
+## Non-AR Backed Model
+
+Implement `changed_attributes` in your non-AR backed model
 
 ## Testing
 
@@ -57,6 +215,24 @@ Caveats:
 require 'netsuite_rails/spec/spec_helper'
 ```
 
+# Syncing Using Rake Tasks
+
+```ruby
+# clockwork.rb
+every(1.minutes, 'netsuite sync') {
+  # prevent multiple netsuite:sync DJ commands from being added; only one is needed in the queue at a time
+  unless Delayed::Job.where(failed_at: nil, locked_by: nil).detect { |j| j.payload_object.class == DelayedRake && j.payload_object.task == 'netsuite:sync'}
+    Delayed::Job.enqueue DelayedRake.new("netsuite:sync")
+  end
+}
+
+# schedule.rb
+# DelayedRake: https://github.com/collectiveidea/delayed_job/wiki/Rake-Task-as-a-Delayed-Job
+every 2.minutes do
+  runner 'Delayed::Job.enqueue(DelayedRake.new("netsuite:sync"),priority:1,run_at: Time.now);'
+end
+```
+
 ## Author
 
-* Michael Bianco @iloveitaly
+* Michael Bianco @iloveitaly

data/circle.yml

@@ -0,0 +1,3 @@
+database:
+  override:
+    - echo "no database setup"

data/lib/netsuite_rails/configuration.rb

@@ -14,7 +14,7 @@ module NetSuiteRails
 
     def netsuite_sync_mode(mode = nil)
       if mode.nil?
-        attributes[:sync_mode] ||= :none
+        attributes[:sync_mode] ||= :async
       else
         attributes[:sync_mode] = mode
       end
@@ -22,17 +22,19 @@ module NetSuiteRails
 
     def netsuite_push_disabled(flag = nil)
       if flag.nil?
-        attributes[:flag] ||= false
+        attributes[:push_disabled] = false if attributes[:push_disabled].nil?
+        attributes[:push_disabled]
       else
-        attributes[:flag] = flag
+        attributes[:push_disabled] = flag
       end
     end
 
     def netsuite_pull_disabled(flag = nil)
       if flag.nil?
-        attributes[:flag] ||= false
+        attributes[:pull_disabled] = false if attributes[:pull_disabled].nil?
+        attributes[:pull_disabled]
       else
-        attributes[:flag] = flag
+        attributes[:pull_disabled] = flag
       end
     end
 

data/lib/netsuite_rails/netsuite_rails.rb

@@ -14,6 +14,8 @@ require 'netsuite_rails/record_sync/poll_manager'
 require 'netsuite_rails/record_sync/pull_manager'
 require 'netsuite_rails/record_sync/push_manager'
 
+require 'netsuite_rails/routines/company_contact_match'
+
 require 'netsuite_rails/list_sync'
 require 'netsuite_rails/list_sync/poll_manager'
 
@@ -23,14 +25,32 @@ module NetSuiteRails
     Rails::VERSION::MAJOR >= 4
   end
 
+  def self.configure_from_env(&block)
+    self.configure do
+      reset!
+
+      netsuite_pull_disabled ENV['NETSUITE_PULL_DISABLED'].present? && ENV['NETSUITE_PULL_DISABLED'] == "true"
+      netsuite_push_disabled ENV['NETSUITE_PUSH_DISABLED'].present? && ENV['NETSUITE_PUSH_DISABLED'] == "true"
+
+      if ENV['NETSUITE_DISABLE_SYNC'].present? && ENV['NETSUITE_DISABLE_SYNC'] == "true"
+        netsuite_pull_disabled true
+        netsuite_push_disabled true
+      end
+      
+      polling_page_size if ENV['NETSUITE_POLLING_PAGE_SIZE'].present?
+    end
+
+    self.configure(&block) if block
+  end
+
+  def self.configure(&block)
+    NetSuiteRails::Configuration.instance_eval(&block)
+  end
+
   class Railtie < ::Rails::Railtie
     rake_tasks do
       load 'netsuite_rails/tasks/netsuite.rb'
     end
-
-    config.before_configuration do
-      require 'netsuite_rails/netsuite_configure'
-    end
   end
 
 end

data/lib/netsuite_rails/poll_trigger.rb

@@ -27,32 +27,33 @@ module NetSuiteRails
           sync_frequency = klass.netsuite_sync_options[:frequency] || 1.day
 
           if sync_frequency == :never
-            Rails.logger.info "Not syncing #{klass.to_s}"
+            Rails.logger.info "NetSuite: Not syncing #{klass.to_s}"
             next
           end
 
-          Rails.logger.info "NetSuite: Syncing #{klass.to_s}"
-          
-          preference = PollTimestamp.for_class(klass)
+          last_class_poll = PollTimestamp.for_class(klass)
+          poll_execution_time = DateTime.now
 
           # check if we've never synced before
-          if preference.new_record?
+          if last_class_poll.new_record?
+            Rails.logger.info "NetSuite: Syncing #{klass} for the first time"
             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 = last_class_poll.value
             last_poll_date = DateTime.parse(last_poll_date) unless last_poll_date.is_a?(DateTime)
 
             if DateTime.now.to_i - last_poll_date.to_i > sync_frequency
-              Rails.logger.info "NetSuite: Syncing #{klass} modified since #{last_poll_date}"
+              Rails.logger.info "NetSuite: #{klass} is due to be synced, last checked #{last_poll_date}"
               klass.netsuite_poll({ last_poll: last_poll_date }.merge(opts))
             else
               Rails.logger.info "NetSuite: Skipping #{klass} because of syncing frequency"
+              next
             end
           end
 
-          preference.value = DateTime.now
-          preference.save!
+          last_class_poll.value = poll_execution_time
+          last_class_poll.save!
         end
       end
 

data/lib/netsuite_rails/record_sync/poll_manager.rb

@@ -19,7 +19,7 @@ module NetSuiteRails
           end
 
           unless netsuite_batch
-            binding.pry
+            raise "NetSuite: #{klass}. Error running NS search. No Netsuite batch found. Most likely a search timeout."
           end
 
           netsuite_batch.each do |netsuite_record|
@@ -35,12 +35,14 @@ module NetSuiteRails
         }.merge(opts)
 
         opts[:netsuite_record_class] ||= klass.netsuite_record_class
+        opts[:netsuite_custom_record_type_id] ||= klass.netsuite_custom_record_type_id if opts[:netsuite_record_class] == NetSuite::Records::CustomRecord
         opts[:saved_search_id] ||= klass.netsuite_sync_options[:saved_search_id]
+        opts[:body_fields_only] ||= false
 
         search = opts[:netsuite_record_class].search(
           poll_criteria(klass, opts).merge({
             preferences: {
-              body_fields_only: false,
+              body_fields_only: opts[:body_fields_only],
               page_size: opts[:page_size]
             }
           })
@@ -48,7 +50,7 @@ module NetSuiteRails
 
         # TODO more robust error reporting
         unless search
-          raise 'error running netsuite sync'
+          raise "NetSuite: #{klass}. Error running NS search. Most likely a search timeout."
         end
 
         process_search_results(klass, opts, search)
@@ -90,7 +92,7 @@ module NetSuiteRails
 
         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',
@@ -116,14 +118,14 @@ module NetSuiteRails
           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|
+          Rails.logger.info "NetSuite: Syncing #{klass}. Current Page: #{search.current_page}. Processing #{search.total_records} over #{search.total_pages} pages."
+
           # 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
@@ -136,7 +138,16 @@ module NetSuiteRails
             end
 
             if filtered_netsuite_id_list.present?
-              opts[:netsuite_record_class].get_list(list: filtered_netsuite_id_list)
+              Rails.logger.info "NetSuite: Syncing #{klass}. Running get_list for #{filtered_netsuite_id_list.length} records"
+
+              if opts[:netsuite_record_class] == NetSuite::Records::CustomRecord
+                NetSuite::Records::CustomRecord.get_list(
+                  list: filtered_netsuite_id_list,
+                  type_id: opts[:netsuite_custom_record_type_id]
+                )
+              else
+                opts[:netsuite_record_class].get_list(list: filtered_netsuite_id_list)
+              end
             else
               []
             end
@@ -164,7 +175,8 @@ module NetSuiteRails
       end
 
       def needs_get_list?(opts)
-        (opts[:saved_search_id].present? && opts[:full_record_data] != false) || opts[:full_record_data] == true
+        (opts[:saved_search_id].present? && opts[:full_record_data] != false) ||
+        opts[:full_record_data] == true
       end
 
       # TODO this should remain in the pull manager
@@ -180,7 +192,7 @@ module NetSuiteRails
 
         custom_field_value
       end
-      
+
     end
   end
-end
+end

data/lib/netsuite_rails/record_sync/pull_manager.rb

@@ -3,6 +3,8 @@ module NetSuiteRails
     module PullManager
       extend self
 
+      # TODO pull relevant methods out of poll manager and into this class
+
       def extract_custom_field_value(custom_field_value)
         if custom_field_value.present? && custom_field_value.is_a?(Hash) && custom_field_value.has_key?(:name)
           custom_field_value = custom_field_value[:name]