qbwc 0.0.5 → 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 29001e1940a32d3b067eccfb012a676fef8791e5
+  data.tar.gz: 5700d148297caecaf087fb73c8ac4aebe27f2cba
+SHA512:
+  metadata.gz: c12ab12caac68c60bbfc08977acc0c60346ee5d53870e45175ae1f02cd06d2237ed6b80e06a799129b8f41f5491ea00fae502fe74069d2d266b99e729ef15286
+  data.tar.gz: 1bece5acbd95f05a7eaf06f23df0c2726718e1082571e630ac0ba8fe296b708c7727fdcafa8d914bc5eb7f0299f7dda735baaa64895730026b3d186e8cd136ba

data/.gitignore

@@ -1 +1,5 @@
-.rvmrc 
+.rvmrc 
+Gemfile.lock
+pkg
+.ruby-gemset
+.ruby-version

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 1.9
+  - 2.0
+  - 2.1
+  - 2.2

data/README.md

@@ -1,182 +1,190 @@
-# Quickbooks Web Connector (QBWC)
+QBWC lets your Rails 4 application talk to QuickBooks Desktop.
 
-Be Warned, this code is still hot out of the oven. 
+[![Build Status](https://travis-ci.org/qbwc/qbwc.svg?branch=master)](https://travis-ci.org/qbwc/qbwc)
 
 ## Installation
 
-Install the gem
+`gem install qbwc`
 
-  `gem install qbwc`
+Or add it to your Gemfile
 
-Add it to your Gemfile
+`gem "qbwc"`
 
-  `gem "qbwc"`
+and run
+
+`bundle install`
+
+## Configuration
 
 Run the generator:
 
-  `rails generate qbwc:install`
+`rails generate qbwc:install`
+
+Then the migrations:
+
+`rake db:migrate`
+
+Open `config/initializers/qbwc.rb` and check the settings there. (Re-)start your app.
+
+Quickbooks *requires* HTTPS connections when connecting to remote machines. [ngrok](https://ngrok.com/) may be useful to fulfill this requirement.
+
+
+### Authentication and multiple company files ###
+
+If connecting to more than one company file or if you want different logins for different users, you can configure QBWC authentication. This is a `Proc` in `config/initializers/qbwc.rb` that accepts the username and password and returns the path to the QuickBooks company file to access:
+
+```ruby
+c.authenticator = Proc.new{|username, password|
+  # qubert can access Oceanic
+  next "C:\\QuickBooks\\Oceanic.QBW" if username == "qubert" && password == "brittany"
+  # quimby can access Veridian
+  next "C:\\QuickBooks\\Veridian.QBW" if username == "quimby" && password == "bethany"
+  # no one else has access
+  next nil
+}
+```
+
+## QuickBooks configuration
+
+Install [QuickBooks Web Connector](http://marketplace.intuit.com/webconnector/) on the machine that has QuickBooks installed.
+
+For a single-user, single-company install, on the QuickBooks machine, visit the path /qbwc/qwc on your domain over an HTTPS connection. Download the file it provides. In QuickBooks Web Connector, click "Add an application", and pick the file. Give Quickbooks the password you specified in `config/initializers/qbwc.rb`.
+
+At this point, QuickBooks Web Connector should be able to send requests to your app, but will have nothing to do, and say "No data exchange required".
+
+### Multiple users and multiple company files ###
+
+If you want to have more than one person to connect to the same QuickBooks company file, you will need to manually edit the QWC file to change the `OwnerID` (any GUID will do) before giving it to QuickBooks Web Connector.
+
+If you want each person to have their own login, set up authentication per [Authentication and multiple company files](#authentication-and-multiple-company-files). In the QWC file, you will need to change `UserName`.
+
+If you are connecting to multiple company files, you will additionally need to change `AppName` and `FileID` (any GUID) to be unique to each file.
+
+
+## Creating jobs
+
+QuickBooks Web Connector (the app you installed above) acts as the HTTP client, and your app acts as the HTTP server. To have QuickBooks perform tasks, you must add a qbwc job to your app, then get QuickBooks Web Connector to check your app for work to do.
 
-## Features
+To create a job (e.g. from `rails console` or wherever):
 
-QBWC was designed to add quickbooks web connector integration to your Rails 3 application. 
+```ruby
+require 'qbwc'
+QBWC.add_job(:list_customers, true, '', CustomerTestWorker)
+```
 
-* Implementation of the Soap WDSL spec for Intuit Quickbooks and Point of Sale
-* Integration with the [quickbooks_api](https://github.com/skryl/quickbooks_api) gem providing qbxml processing
+* The first argument is a unique name for the job. You can use this later to disable or delete the job.
+* The second argument indicates whether the job is initially enabled.
+* The third argument specifies the path to the QuickBooks company file this job affects. An empty string will make the job run against any company file.
+* The fourth argument is your worker class. See the next section for a description of workers.
 
-## Getting Started
+Your job will be persisted in your database and will remain active and run every time QuickBooks Web Connector runs an update. If you don't want this to happen, you can have have your job disable or delete itself after completion. For example:
 
-### Configuration
+```ruby
+	def handle_response(r, session, job, request, data)
+		QBWC.delete_job(job)
+	end
 
-All configuration takes place in the gem initializer. See the initializer for more details regarding the configuration options.
+```
 
-### Basics
+Alternately, you can custom logic in your worker's `requests` and `should_run?` methods, as described below.
 
-The QBWC gem provides a persistent work queue for the Web Connector to talk to.
-
-Every time the Web Connector initiates a new conversation with the application a
-Session will be created. The Session is a collection of jobs and the requests
-that comprise these jobs. A new Session will automatically queue up all the work
-available across all currently enabled jobs for processing by the web connector.
-The session instance will persist across all requests until the work it contains
-has been exhausted. You never have to interact with the Session class directly
-(unless you want to...) since creating a new job will automatically add it's
-work to the next session instance.
-
-A Job is just a named work queue. It consists of a name and a code block. The
-block can contain:
-
-  * A single qbxml request
-  * An array of qbxml requests
-  * Code that genrates a qbxml request
-  * Code that generates an array of qbxml requests
-
-*Note: All requests may be in ruby hash form, generated using quickbooks_api. 
-Raw requests are supported supported as of 0.0.3 (8/28/2012)*
-
-The code block is re-evaluated every time a session instance with that job is
-created. Only enabled jobs are added to a new session instance. 
-
-An optional response processor block can also be added to a job. Responses to
-all requests are either processed immediately after being received or saved for
-processing after the web connector closes its connection. The delayed processing
-configuration option decides this.
-
-Here is the rough order in which things happen:
-
-  1. The Web Connector initiates a connection
-  2. A new Session is created (with work from all enabled jobs)
-  3. The web connector requests work
-  4. The session responds with the next request in the work queue
-  5. The web connector provides a response
-  6. The session responds with the current progress of the work queue (0 - 100)
-  6. The response is processed or saved for later processing
-  7. If progress == 100 then the web connector closes the connection, otherwise goto 3
-  8. Saved responses are processed if any exist
 
-### Adding Jobs
+## Workers ##
 
-Create a new job
+A job is associated to a worker, which is an object descending from `QBWC::Worker` that can define three methods:
 
-    QBWC.add_job('my job') do
-      # work to do
-    end
+- `requests(job)` - defines the request(s) that QuickBooks should process - returns a `Hash` or an `Array` of `Hash`es.
+- `should_run?(job)` - whether this job should run (e.g. you can have a job run only under certain circumstances) - returns `Boolean` and defaults to `true`.
+- `handle_response(response, session, job, request, data)` - defines what to do with the response from Quickbooks.
 
-Add a response proc
+All three methods are not invoked until a QuickBooks Web Connector session has been established with your web service.
 
-    QBWC.jobs['my job'].set_response_proc do |r|
-      # response processing work here
-    end
+A sample worker to get a list of customers from QuickBooks:
 
-Caveats
-  * Jobs are enabled by default
-  * Using a non unique job name will overwrite the existing job
+```ruby
+require 'qbwc'
 
-###Sample Jobs
+class CustomerTestWorker < QBWC::Worker
 
-Add a Customer (Wrapped)
+	def requests(job)
+		{
+			:customer_query_rq => {
+				:xml_attributes => { "requestID" =>"1", 'iterator'  => "Start" },
+				:max_returned => 100
+			}
+		}
+	end
 
-          {  :qbxml_msgs_rq => 
-            [
-              {
-                :xml_attributes =>  { "onError" => "stopOnError"}, 
-                :customer_add_rq => 
-                [
-                  {
-                    :xml_attributes => {"requestID" => "1"},  ##Optional
-                    :customer_add   => { :name => "GermanGR" }
-                  } 
-                ] 
-              }
-            ]
-          }
-          
-Add a Customer (Unwrapped)
+	def handle_response(r, session, job, request, data)
+		# handle_response will get customers in groups of 100. When this is 0, we're done.
+		complete = r['xml_attributes']['iteratorRemainingCount'] == '0'
 
-        {
-          :customer_add_rq    => 
-          [
-            {
-              :xml_attributes => {"requestID" => "1"},  ##Optional
-              :customer_add   => { :name => "GermanGR" }
-            } 
-          ] 
-        }
+		r['customer_ret'].each do |qb_cus|
+			qb_id = qb_cus['list_id']
+			qb_name = qb_cus['name']
+			Rails.logger.info("#{qb_id} #{qb_name}")
+		end
+	end
 
-Get All Vendors (In Chunks of 5)
-
-        QBWC.add_job(:import_vendors) do
-          [
-            :vendor_query_rq  =>
-            {
-              :xml_attributes => { "requestID" =>"1", 'iterator'  => "Start" },
-      
-              :max_returned => 5,
-              :owner_id => 0,
-              :from_modified_date=> "1984-01-29T22:03:19"
-
-            }
-          ]
-        end
-        
-Get All Vendors (Raw QBXML)
-
-        QBWC.add_job(:import_vendors) do
-          '<QBXML>
-            <QBXMLMsgsRq onError="continueOnError">
-            <VendorQueryRq requestID="6" iterator="Start">
-            <MaxReturned>5</MaxReturned>
-            <FromModifiedDate>1984-01-29T22:03:19-05:00</FromModifiedDate>
-            <OwnerID>0</OwnerID>
-          </VendorQueryRq>
-          </QBXMLMsgsRq>
-          </QBXML>
-          '
-        end
-
-### Managing Jobs
-
-Jobs can be added, removed, enabled, and disabled. See the above section for
-details on adding new jobs. 
-
-Removing jobs is as easy as deleting them from the jobs hash.                   
-
-    QBWC.jobs.delete('my job')
-
-Disabling a job
-
-    QBWC.jobs['my job'].disable
-
-Enabling a job
-
-    QBWC.jobs['my job'].enable
+end
+```
 
 
+Use the [Onscreen Reference for Intuit Software Development Kits](https://developer-static.intuit.com/qbSDK-current/Common/newOSR/index.html) (use Format: qbXML) to see request and response formats to use in your jobs. Use underscored, lowercased versions of all tags (e.g. `customer_query_rq`, not `CustomerQueryRq`).
+
+### Referencing memory values when constructing requests ###
+
+A `QBWC::Worker#requests` method cannot access values that are in-memory (global variables, local variables, model attributes, etc.) at the time that `QBWC.add_job` is called; however, in lieu of using `QBWC::Worker#requests`, you can construct and pass requests directly to `QBWC.add_job` (`Hash`, `String`, or array of `Hash`es and `String`s). These requests will be immediately persisted by `QBWC.add_job` (in contrast to requests constructed by `QBWC::Worker#requests`, which are persisted during a QuickBooks Web Connector session).
+
+If requests are passed to `QBWC.add_job`, the `requests` method on your worker will be ignored.
+
+### Referencing memory values when handling responses ###
+
+Similarly, a `QBWC::Worker#handle_response` method cannot access variables that are in-memory at the time that `QBWC.add_job` is called; however, you can optionally pass a serializable value (for example, String, Array, or Hash) to `QBWC.add_job`. This data will immediately be persisted by `QBWC.add_job`, then later passed to `QBWC::Worker#handle_response` during a QuickBooks Web Connector session.
+
+## Sessions ##
+
+In certain cases, you may want to perform some initialization prior to each QuickBooks Web Connector session. For this purpose, you may optionally provide initialization code that will be invoked once when each QuickBooks Web Connector session is established, and prior to executing any queued jobs. This initialization code will not be invoked for any session in which no jobs are queued.
+
+You assign this initialization code either (a) during configuration, and/or (b) in application code by calling `set_session_initializer` (prior to any QuickBooks Web Connector session being established). For example:
+
+In config/initializers/qbwc.rb:
+
+```ruby
+c.session_initializer = Proc.new{|session|
+  puts "New QuickBooks Web Connector session has been established (configured session initializer)"
+}
+```
+
+In application code:
+```ruby
+        require 'qbwc'
+
+	QBWC.set_session_initializer() do |session|
+          puts "New QuickBooks Web Connector session has been established (overridden session initializer)"
+          @information_from_jobs = {}
+        end if the_application_needs_a_different_session_initializer
+
+        QBWC.add_job(:list_customers, false, '', CustomerTestWorker)
+
+```
+
+Note: If you `set_session initializer` in your application code, you're only affecting the process that your application code runs in. A request to another process (e.g. if you're multiprocess or you restarted the server) means that QBWC won't see the session initializer.
+
+Note: a QuickBooks Web Connector session is established when you manually run (update) an application's web service in QuickBooks Web Connector, or when QuickBooks Web Connector automatically executes a scheduled update.
+
+## Handling errors ##
+
+By default, when an error response is received from QuickBooks, `QBWC::Worker#handle_response` will be invoked but no further requests will be processed in the current job or in subsequent jobs. However, the job will remain persisted and so will be attempted again at next QuickBooks Web Connector session. Unless there is some intervention, presumably the job will fail again and block all remaining jobs and their requests from being serviced.
+
+To have qbwc continue with the next request after receiving an error, set `on_error` to `:continue` in `config/initializers/qbwc.rb`.
+
 ## Contributing to qbwc
- 
+
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
 * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
 * Fork the project
 * Start a feature/bugfix branch
 * Commit and push until you are happy with your contribution
 * Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
-* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+* Run tests - `rake test`.

data/Rakefile

@@ -1,3 +1,9 @@
 require "bundler/gem_tasks"
 
-Bundler::GemHelper.install_tasks
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+Rake::TestTask.new do |t|
+  t.pattern = 'test/**/*_test.rb'
+end
+task :default => :test

data/lib/generators/qbwc/install/install_generator.rb

@@ -1,24 +1,40 @@
 require 'rails/generators'
+require 'rails/generators/active_record'
 
 module QBWC
   module Generators
     class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      extend Rails::Generators::Migration
+
       namespace "qbwc:install"
       desc "Copy Quickbooks Web Connector default files"
       source_root File.expand_path('../templates', __FILE__)
+      argument :controller_name, :type => :string, :default => 'qbwc'
       
       def copy_config
          template('config/qbwc.rb', "config/initializers/qbwc.rb")
       end
 
       def copy_controller 
-         template('controllers/qbwc_controller.rb', "app/controllers/qbwc_controller.rb")
+         template('controllers/qbwc_controller.rb', "app/controllers/#{controller_name}_controller.rb")
+      end
+
+      def active_record
+        migration_template 'db/migrate/create_qbwc_jobs.rb',     'db/migrate/create_qbwc_jobs.rb'
+        migration_template 'db/migrate/create_qbwc_sessions.rb', 'db/migrate/create_qbwc_sessions.rb'
+      end
+
+      def self.next_migration_number(dirname)
+        ::ActiveRecord::Generators::Base.next_migration_number(dirname)
       end
 
-      def setup_routes
-        route("match 'apis/quickbooks/:action', :controller => 'qbwc', :as => 'quickbooks'")
+     def setup_routes
+        route("wash_out :#{controller_name}")
+        route("get '#{controller_name}/qwc' => '#{controller_name}#qwc'")
+        route("get '#{controller_name}/action' => '#{controller_name}#_generate_wsdl'")
       end
       
     end
   end
-end
+end

data/lib/generators/qbwc/install/templates/config/qbwc.rb

@@ -1,39 +1,55 @@
 QBWC.configure do |c|
-  
-  #Currently Only supported for single logins. 
+
+  # Credentials to be entered in QuickBooks Web Connector.
   c.username = "foo"
   c.password = "bar"
-  
-  #Path to Company File (blank for open or named path or function etc..)
+
+  # Path to QuickBooks company file on the client. Empty string to use whatever file is open when the connector runs.
   c.company_file_path = ""
+
+  # Instead of using hard coded username, password, and path, use a proc
+  # to determine who has access to what. Useful for multiple users or
+  # multiple company files.
+  # c.authenticator = Proc.new{|username, password|
+  #   # qubert can access Oceanic
+  #   next "C:\\QuickBooks\\Oceanic.QBW" if username == "qubert" && password == "brittany"
+  #   # quimby can access Veridian
+  #   next "C:\\QuickBooks\\Veridian.QBW" if username == "quimby" && password == "bethany"
+  #   # no one else has access
+  #   next nil
+  # }
+
+  # Code to execute after each session is authenticated
+  # Can be re-assigned by calling QBWC.set_session_initializer
+  # c.session_initializer = Proc.new{|session|
+  #   puts "New QuickBooks Web Connector session has been established"
+  # }
+
+  # QBXML version to use. Check the "Implementation" column in the QuickBooks Onscreen Reference to see which fields are supported in which versions. Newer versions of QuickBooks are backwards compatible with older QBXML versions.
+  c.min_version = "7.0"
   
-  #Minimum Quickbooks Version Required for use in QBXML Requests
-  c.min_version = 7.0
-  
-  #Quickbooks Type (either :qb or :qbpos)
+  # Quickbooks type (either :qb or :qbpos).
   c.api = :qb
+
+  # Storage module. Only :active_record is currently supported.
+  c.storage = :active_record
   
-  #Quickbooks Support URL provided in QWC File
-  c.support_site_url = "localhost:3000"
+  # Support URL shown in QuickBooks Web Connector. nil will use root path of the app.
+  c.support_site_url = nil
   
-  #Quickbooks Owner ID provided in QWC File
+  # Unique user GUID. If you want access by multiple users to the same file, you will need to modify this in the generated QWC file.
   c.owner_id = '{57F3B9B1-86F1-4fcc-B1EE-566DE1813D20}'
 
-  # Perform response processing after session termination. Enabling this option
-  # will speed up qbwc session time (and potentially fix timeout issues) but
-  # will necessarily eat up more memory since every response must be stored
-  # until it is processed. 
-  c.delayed_processing = false
-
-  # In the event of an error in the communication process do you wish the sync to stop or blaze through
-  #
-  # Options: 
-  # :stop
-  # :continue
+  # How often to run web service (in minutes) or nil to only run manually.
+  c.minutes_to_run = nil
+
+  # In the event of an error running requests, :stop all work or :continue with the next request?
   c.on_error = :stop
 
-  # Rails Cache Hot Boot  (Check the rails cache for existing API object to speed app boot) 
-  # This Feature is Unstable and is Extreme Alpha.  IT is known not to work
-  # c.warm_boot = false
-  
+  # Logger to use.
+  c.logger = Rails.logger
+
+  # Some log lines contain sensitive information
+  # (default false on production, true otherwise)
+  # c.log_requests_and_responses = false
 end