effective_qb_sync 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ad8ca346bd7681f4e298eab0a873b9d18381c5a8
+  data.tar.gz: 052fda34af7a8a95fd6a578ea588bf3adc32acd7
+SHA512:
+  metadata.gz: 2bf69833eb4ed99ac58b87470c693bd6435f83551e316e4fc0913507fe7ae0718f3346f6bf4ef8b13cf1f3eaa659b7e35f1ad4eb3e7126e8a17584f9d72aa385
+  data.tar.gz: b700597415767d5266091bf45dffbc7f5aa487ab3665994d068e583140cdd2a9702963d7fbf5523c7db7b6ba85b1c08e078946aeacb20b7fd558df59d58fa667

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2016 Code and Effect Inc.
+
+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,94 @@
+# Effective Quickbooks Sync
+
+Synchronize [effective_orders](https://github.com/code-and-effect/effective_orders) with [Quickbooks Web Connector](https://developer.intuit.com/docs/quickbooks_web_connector).
+
+## Getting Started
+
+Make sure [effective_orders](https://github.com/code-and-effect/effective_orders) is installed.
+
+Ensure all your `acts_as_purchasable` objects respond to `qb_item_name`.
+
+
+Add to your Gemfile:
+
+```ruby
+gem 'effective_qb_sync'
+```
+
+Run the bundle command to install it:
+
+```console
+bundle install
+```
+
+Then run the generator:
+
+```ruby
+rails generate effective_qb_sync:install
+```
+
+The generator will install an initializer which describes all configuration options and creates a database migration.
+
+If you want to tweak the table name (to use something other than the default 'qb_requests', 'qb_tickets', 'qb_logs' and 'qb_order_items'), manually adjust both the configuration file and the migration now.
+
+Then migrate the database:
+
+```ruby
+rake db:migrate
+```
+
+### Admin Screen
+
+To use the Admin screen, please also install the effective_datatables gem:
+
+```ruby
+gem 'effective_datatables'
+```
+
+Then visit:
+
+```ruby
+link_to 'Quickbooks', effective_qb_sync.admin_qb_syncs_path   # /admin/qb_syncs
+```
+
+### Permissions
+
+The Quickbooks synchronization controller does not require a logged in user, or any other rails permissions.
+
+The sync itself checks that the Quickbooks user performing the sync has a username/password that matches the values in the config/initializers/effective_qb_sync.rb file.
+
+For the admin screen, a logged in user is required (devise) and the user should be able to (CanCan):
+
+```ruby
+can :admin, :effective_qb_sync
+```
+
+Devise is a required dependency, but CanCan is not.  Please see the authorization_method in the initializer.
+
+## Setting up Quickbooks
+
+Once the gem is installed, visit the /admin/qb_syncs/instructions page for setup instructions.
+
+## License
+
+MIT License.  Copyright [Code and Effect Inc.](http://www.codeandeffect.com/)
+
+Code and Effect is the product arm of [AgileStyle](http://www.agilestyle.com/), an Edmonton-based shop that specializes in building custom web applications with Ruby on Rails.
+
+## Testing
+
+Run tests by:
+
+```ruby
+rspec
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Bonus points for test coverage
+6. Create new Pull Request
+

data/Rakefile

@@ -0,0 +1,21 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+# Testing tasks
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+require "bundler/vendored_thor"
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+desc "Run all specs in spec directory (excluding plugin specs)"
+RSpec::Core::RakeTask.new(:spec => 'app:db:test:prepare')
+
+task :default => :spec

data/app/controllers/admin/qb_syncs_controller.rb

@@ -0,0 +1,60 @@
+module Admin
+  class QbSyncsController < ApplicationController
+    before_filter :authenticate_user!   # This is devise, ensure we're logged in.
+    before_filter :restrict_access
+
+    layout (EffectiveQbSync.layout.kind_of?(Hash) ? EffectiveQbSync.layout[:admin_qb_tickets] : EffectiveQbSync.layout)
+
+    def index
+      @datatable = Effective::Datatables::QbSyncs.new() if defined?(EffectiveDatatables)
+      @page_title = 'Quickbooks Synchronizations'
+    end
+
+    def show
+      @qb_ticket = Effective::QbTicket.includes(:qb_requests, :qb_logs).find(params[:id])
+      @page_title = "Quickbooks Sync ##{@qb_ticket.id}"
+
+      @qb_order_items_form = Effective::QbOrderItemsForm.new(id: @qb_ticket.id, orders: @qb_ticket.orders)
+    end
+
+    def update
+      @qb_ticket = Effective::QbTicket.includes(:qb_requests, :qb_logs).find(params[:id])
+      @page_title = "Quickbooks Sync ##{@qb_ticket.id}"
+
+      @qb_order_items_form = Effective::QbOrderItemsForm.new(id: @qb_ticket.id, orders: @qb_ticket.orders)
+      @qb_order_items_form.qb_order_items_attributes = permitted_qb_order_items_params[:qb_order_items_attributes].values
+
+      if @qb_order_items_form.save
+        flash[:success] = 'Successfully updated Quickbooks item names'
+        redirect_to effective_qb_sync.admin_qb_sync_path(@qb_ticket)
+      else
+        flash.now[:danger] = 'Unable to update Quickbooks item names'
+        render action: :show
+      end
+    end
+
+    def instructions
+      @page_title = 'Quickbooks Setup Instructions'
+    end
+
+    def qwc
+      @filename = Rails.application.class.parent_name.downcase + '.qwc'
+
+      response.headers['Content-Disposition'] = "attachment; filename=\"#{@filename}\""
+
+      render '/effective/qb_web_connector/quickbooks.qwc', layout: false
+    end
+
+    private
+
+    def restrict_access
+      EffectiveQbSync.authorized?(self, :admin, :effective_qb_sync)
+    end
+
+    def permitted_qb_order_items_params
+      params.require(:effective_qb_order_items_form).permit(:id, qb_order_items_attributes: [:name, :id, :order_item_id])
+    end
+
+
+  end
+end

data/app/controllers/effective/qb_sync_controller.rb

@@ -0,0 +1,40 @@
+module Effective
+  class QbSyncController < ApplicationController
+    skip_authorization_check if defined?(CanCan)
+    skip_before_filter :verify_authenticity_token
+
+    def api
+      # respond successfully to a GET which some versions of the Web Connector send to verify the url
+      (render(nothing: true) and return) if request.get?
+
+      # Examine raw post and determine which API call to process
+      doc = Nokogiri::XML(request.raw_post)
+      @qbwcSupervisor = QbwcSupervisor.new
+
+      api_verb = (doc.at_xpath('//soap:Body').children.first.node_name rescue '')
+
+      case api_verb
+      when 'serverVersion'
+        @version = '1.0'
+      when 'clientVersion'
+        @version = nil
+      when 'authenticate'
+        @token, @message = @qbwcSupervisor.authenticate(doc)
+      when 'sendRequestXML'
+        @message = @qbwcSupervisor.sendRequestXML(doc)
+      when 'receiveResponseXML'
+        @message = @qbwcSupervisor.receiveResponseXML(doc)
+      when 'getLastError'
+        @message = @qbwcSupervisor.getLastError(doc)
+      when 'connectionError'
+        @message = @qbwcSupervisor.connectionError(doc)
+      when 'closeConnection'
+        @message = @qbwcSupervisor.closeConnection(doc)
+      else
+        ''
+      end
+
+      render(template: "/effective/qb_sync/#{api_verb}.erb", layout: false, content_type: 'text/xml')
+    end
+  end
+end

data/app/models/effective/access_denied.rb

@@ -0,0 +1,17 @@
+unless defined?(Effective::AccessDenied)
+  module Effective
+    class AccessDenied < StandardError
+      attr_reader :action, :subject
+
+      def initialize(message = nil, action = nil, subject = nil)
+        @message = message
+        @action = action
+        @subject = subject
+      end
+
+      def to_s
+        @message || I18n.t(:'unauthorized.default', :default => 'Access Denied')
+      end
+    end
+  end
+end

data/app/models/effective/datatables/qb_syncs.rb

@@ -0,0 +1,30 @@
+if defined?(EffectiveDatatables)
+  module Effective
+    module Datatables
+      class QbSyncs < Effective::Datatable
+        datatable do
+          default_order :created_at, :desc
+
+          table_column :created_at
+          table_column :state, filter: { values: QbTicket::STATES }
+
+          array_column :num_orders, visible: false do |qb_ticket|
+            qb_ticket.qb_requests.length
+          end
+
+          array_column :orders do |qb_ticket|
+            qb_ticket.qb_requests.select { |qb_request| qb_request.order.present? }
+              .map { |qb_request| link_to "##{qb_request.order.to_param}", effective_orders.admin_order_path(qb_request.order) }
+              .join('<br>').html_safe
+          end
+
+          table_column :actions, sortable: false, filter: false, partial: 'admin/qb_syncs/actions', partial_local: :qb_sync
+        end
+
+        def collection
+          Effective::QbTicket.includes(qb_requests: :order)
+        end
+      end
+    end
+  end
+end

data/app/models/effective/qb_log.rb

@@ -0,0 +1,13 @@
+module Effective
+  class QbLog < ActiveRecord::Base
+    belongs_to :qb_ticket
+
+    # structure do
+    #   message       :text
+    #   timestamps
+    # end
+
+    validates :qb_ticket, presence: true
+    validates :message, presence: true
+  end
+end

data/app/models/effective/qb_machine.rb

@@ -0,0 +1,281 @@
+# a state controller that will help orchestrate the different state transitions in the dance with the QBWC
+# Note that all methods that are prefixed with op_ should correspond directly to the QuickBooks web connector API.
+
+module Effective
+  class QbMachine
+
+    attr_reader :ticket
+    attr_reader :last_log_message
+
+    # creates a new machine. this implicitly creates a new ticket unless one is supplied
+    def initialize(ticket_id = nil)
+      if ticket_id
+        @ticket = Effective::QbTicket.find_by_id(ticket_id)
+      else
+        @ticket = Effective::QbTicket.create
+      end
+    end
+
+    # authenticates a user for a particular session
+    #
+    # returns
+    # - 'nvu' if the user login was invalid
+    # - 'none' if the user login was valid but there is no work to be done
+    # - '' if the user login was valid and there is work to be done
+    def op_authenticate(username, password)
+      return 'nvu' unless valid?
+
+      unless authentication_valid?(username, password)
+        log "Authentication failed for user #{username}"
+        @ticket.update_attributes!(username: username, state: 'Finished', last_error: @last_log_message)
+        return 'nvu' # not valid user
+      end
+
+      if has_work?
+        log "Authentication successful. Reporting to QuickBooks that there is work to be done."
+        @ticket.update_attributes!(username: username, state: 'Authenticated')
+        ''  # "Any other string value = use this name for company file"
+      else
+        log "Authentication successful, but there is no work to be done"
+        @ticket.update_attributes!(username: username, state: 'Finished')
+        'none'
+      end
+    end
+
+    # processes a message from the QBWC that corresponds to
+    #
+    # string sendRequestXML(ticket, hcpresponse, company, country, major_ver, minor_ver)
+    #
+    # in the QBWC api
+    #
+    # The params input should have members that correspond to the above parameters except for ticket, since
+    # the ticket has already been used to build this state machine.
+    #
+    # Returns:
+    # - '' if there is no work to be done
+    # - Some qbXML if there is work to be done
+    def op_send_request_xml(params)
+      return '' unless valid?
+
+      # update the ticket with the metadata sent at the first request for XML (i.e. if not blank)
+      @ticket.update_attributes!(
+        hpc_response: (@ticket.hpc_response || params[:hcpresponse]),
+        company_file_name: (@ticket.company_file_name || params[:company]),
+        country: (@ticket.country || params[:country]),
+        qbxml_major_version: (@ticket.qbxml_major_version || params[:major_ver]),
+        qbxml_minor_version: (@ticket.qbxml_minor_version || params[:minor_ver])
+      )
+
+      # only process when in the Authenticated or Processing states
+      unless ['Authenticated', 'Processing'].include?(@ticket.state)
+        @ticket.request_error!(@last_log_message)
+        return ''
+      end
+
+      # either grab the current request or create a new one
+      request = @ticket.qb_request
+      unless request
+        request = create_request
+        @ticket.qb_request = request
+      end
+
+      # if we don't have a request, then we are done.
+      unless request
+        log "There is no more work to be done. Marking ticket state as finished"
+        @ticket.update_attributes!(state: 'Finished')
+        return ''
+      end
+
+      request.update_attributes!(qb_ticket: @ticket, request_sent_at: Time.zone.now)
+      qb_xml = request.to_qb_xml
+      request.update_attributes!(request_qbxml: qb_xml)
+
+      # set the ticket into a Processing state
+      @ticket.state = 'Processing'
+
+      # save the changes.
+      @ticket.save!
+
+      log "Sending request [#{request.state}] XML to QuickBooks"
+
+      qb_xml
+    end
+
+    # processes a message from the QBWC that corresponds to
+    #
+    # int receiveResponseXML(ticket, response, hresult, message)
+    #
+    # in the QBWC api
+    #
+    # The params input should have members that correspond to the above parameters except for ticket
+    #
+    # Returns:
+    #    - negative value for error
+    #    - postive value < 100 for percent complete (more work is to be done)
+    #    - 100 if there is no more work
+    def op_receive_response_xml(params)
+      return -1 unless valid?
+
+      # only process when in the 'Processing' state
+      unless @ticket.state == 'Processing'
+        log "Ticket state #{@ticket.state} not valid for processing responses"
+        @ticket.request_error! @last_log_message
+        return -1
+      end
+
+      responseXML = params[:response]
+      log "Received response XML from QuickBooks"
+
+      # handle a connection error
+      unless params[:hresult].blank? and params[:message].blank?
+        log "Connection error with QuickBooks: #{params[:hresult]} : #{params[:message]}"
+
+        @ticket.request_error!(@last_log_message, connection_error_hresult: params[:hresult], connection_error_message: params[:message])
+
+        # also update the request if it is able to be found
+        request = find_outstanding_request(responseXML)
+        request.update_attributes!(response_qbxml: responseXML, state: 'Error') if request
+
+        return -1
+      end
+
+      # find the corresponding request
+      request = find_outstanding_request(responseXML)
+
+      unless request
+        log "Received response back from QuickBooks but it did not correspond to any outstanding ticket request"
+        @ticket.request_error! @last_log_message
+        return -1
+      end
+
+      log "Found corresponding request [#{request.state}]"
+
+      # safety check. we should always get a response back for the current request
+      unless request == @ticket.qb_request
+        log "Received response from QuickBooks but it references a request other than the current request"
+        @ticket.request_error! @last_log_message
+        return -1
+      end
+
+      # process the response XML now
+      unless request.consume_response_xml(responseXML)
+        # this request for some reason did not succeeed. Update the request and the ticket
+        log "Request [#{request.state}] could not process the QuickBooks response: #{request.error}"
+        request.update_attributes!(response_qbxml: responseXML, state: 'Error')
+        @ticket.error! @last_log_message
+        return -1
+      end
+
+      request.update_attributes!(response_qbxml: responseXML) # This was changed for effective_qb_sync
+
+      # the request has processed the response XML. if it does not have any more work to do, then detach it
+
+      if request.has_more_work?
+        log "Request [#{request.state}] has more work to do on the next request"
+      else
+        # detach the current request
+        @ticket.update_attributes!(qb_request: nil)
+        log "Request [#{request.state}] has completed its work"
+      end
+
+      work_done = @ticket.qb_requests.size
+      work_left = how_much_more_work
+      work_left = work_left + 1 if @ticket.qb_request # if there is still a current request we need to add that to the work_left
+
+      work_left == 0 ? 100 : (work_done * 100 / (work_done + work_left))
+    end
+
+    # processes a message from the QBWC that corresponds to
+    #
+    # string connectionError(string ticket, string hresult, string message)
+    #
+    # in the QBWC api, signfiying that the connection with QuickBooks was lost
+    #
+    # The params input should have members that correspond to the above parameters except for ticket
+    #
+    # Returns: 'done' to indicate that activity on this ticket should not be resumed
+    def op_connection_error(hresult,message)
+      if valid?
+        @ticket.connection_error_hresult = hresult
+        @ticket.connection_error_message = message
+        @ticket.state = 'ConnectionError'
+      end
+
+      'done'
+    end
+
+    # processes a message from the QBWC that corresponds to
+    #
+    # string closeConnection(string ticket)
+    #
+    # in the QBWC api, signifying that this connection should be terminated.
+    #
+    # returns the connection closing result (e.g. 'OK')
+    def op_close_connection
+      return 'Close error: invalid ticket' unless valid?
+
+      @ticket.update_attributes!(state: 'Finished') unless ['ConnectionError', 'RequestError'].include?(@ticket.state)
+      log "Closed connection with QuickBooks"
+
+      'OK'
+    end
+
+    # processes a message from the QBWC that corresponds to
+    #
+    # string getLastError(string ticket)
+    #
+    # in the QBWC api
+    #
+    # Returns: the last error recorded for that ticket
+    def op_last_error
+      return 'Invalid Ticket Id' unless valid?
+      @ticket.last_error || ''
+    end
+
+    # returns true if this machine is a valid machine
+    def valid?
+      @ticket.present?
+    end
+
+    # logs a message to the ticket if it exists
+    def log(message)
+      @ticket.log(message) unless message.blank?
+      # always save the last log message
+      @last_log_message = message
+    end
+
+    # sets the ticket as failed and records the message
+    def fail_unexpectedly(message)
+      log "An unexpected error occurred: #{message}"
+      @ticket.request_error! @last_log_message
+    end
+
+    protected
+
+    # determines if this username and password is valid
+    def authentication_valid?(username,password)
+      (username == EffectiveQbSync.quickbooks_username) && (password == EffectiveQbSync.quickbooks_password)
+    end
+
+    # returns how much more work is to be done. If there is no more work to be done, it will return 0, else,
+    # the number of requests that need to be processed.
+    def how_much_more_work
+      Effective::QbRequest.new_requests_for_unsynced_items.size
+    end
+
+    # returns true if there is work to be done
+    def has_work?
+      how_much_more_work > 0
+    end
+
+    # creates a new request object for a unit of work to be done. returns nil if no work can be found
+    def create_request
+      Effective::QbRequest.new_requests_for_unsynced_items.first
+    end
+
+    # returns a qb request that corresponds to the first element in the response with a requestID
+    def find_outstanding_request(responseXML)
+      Effective::QbRequest.find_using_response_qbxml(responseXML)
+    end
+  end
+end