quickbooks 0.0.2 → 0.0.3

data/lib/quickbooks.rb

@@ -1,2 +1,7 @@
+require 'rubygems'
 require 'quickbooks/connection'
-require 'quickbooks/models/models'
+require 'quickbooks/base'
+require 'quickbooks/models/list_item'
+require 'quickbooks/models/transaction'
+
+require 'quickbooks/models/customer'

data/lib/quickbooks/base.rb

@@ -0,0 +1,282 @@
+# Contains Quickbooks::Base. Two models inherit directly from Quickbooks::Base: ListItem and Transaction.
+# All other models inherit from one of these.
+# 
+# Inheriting from ListItem:
+# - Account
+# - Account List
+# - BillingRate
+# - Class
+# - Currency
+# - Customer
+# - CustomerMessage
+# - CustomerType
+# - DateDrivenTerms
+# - Employee
+# - ItemDiscount
+# - ItemFixedAsset
+# - ItemGroup
+# - ItemInventory
+# - ItemInventoryAssembly
+# - ItemNonInventory
+# - ItemOtherCharge
+# - ItemPayment
+# - ItemSalesTax
+# - ItemSalesTaxGroup
+# - ItemService
+# - ItemSubtotal
+# - JobType
+# - OtherName
+# - PaymentMethod
+# - PayrollItemNonWage
+# - PayrollItemWage
+# - PriceLevel
+# - SalesRep
+# - SalesTaxCode
+# - ShipMethod
+# - StandardTerms
+# - TaxCode
+# - Template
+# - ToDo
+# - Vehicle
+# - Vendor
+# - VendorType
+# Inheriting from Transaction:
+# - Bill
+# - BillPaymentCheck
+# - BillPaymentCreditCard
+# - BuildAssembly
+# - Charge
+# - Check
+# - CreditCardCharge
+# - CreditCardCredit
+# - CreditCardRefund
+# - CreditMemo
+# - Deposit
+# - Estimate
+# - InventoryAdjustment
+# - Invoice
+# - ItemReceipt
+# - JournalEntry
+# - PurchaseOrder
+# - ReceivePayment
+# - SalesOrder
+# - SalesReceipt
+# - SalesTaxPaymentCheck
+# - TimeTracking
+# - VehicleMileage
+# - VendorCredit
+
+require 'activesupport'
+require 'quickbooks/connection'
+require 'quickbooks/qbxml/request'
+require 'quickbooks/qbxml/response'
+
+module Quickbooks
+  class Base
+    # Stores a log of Quickbooks::Qbxml::Response objects that were a result of methods performed on this object.
+    attr_accessor :response_log
+    def response_log #:nodoc:
+      @response_log || (@response_log = [])
+    end
+
+    # Returns success (true/false) status of the last quickbooks communication called from this object.
+    def success?
+      @response_log.last.success?
+    end
+    def inspect #:nodoc:
+      "#<#{self.class.name}:#{self.object_id} #{instance_variables.reject {|i| i.is_one_of?('@response_log', '@original_values')}.map {|i| "#{i}=#{instance_variable_get(i).inspect}"}.join(' ')}>"
+    end
+    class << self
+
+      # Establishes a connection to the Quickbooks RDS Server for all Model Classes
+      def establish_connection(application_name='RubyApplication', file='', user='', password='', connection_type='localQBD', connection_mode='DoNotCare')
+        @@connection = Connection.new(application_name, file, user, password, connection_type, connection_mode)
+      end
+
+      # Returns the current Connection
+      def connection
+        @connection || (@@connection ||= self.establish_connection())
+      end
+
+      # Sets the current Connection.
+      # 
+      # This is normally not needed, but in the case that you may want to connect a separate connection to Quickbooks,
+      # you can use this method to explicitly set the connection in a class that inherits from Quickbooks::Base.
+      #   Quickbooks::Models::Base.connection = Quickbooks::Connection.new('My Test App', 'C:\\Some File.QBW', 'user', 'pass')
+      def connection=(conn)
+        raise ArgumentError, "Cannot set connection to anything but a Quickbooks::Connection object" unless conn.is_a?(Quickbooks::Connection)
+        @connection = conn
+      end
+
+      # Register a property in the current class. For example in the Customer class:
+      #   property :first_name
+      def property(*args)
+        raise ArgumentError, "must include a property name" unless args.length > 0
+        properties(*args)
+      end
+      # Register multiple properties at once. For example:
+      #   properties :first_name, :last_name, :phone, :alt_phone
+      def properties(*args)
+        if args.blank?
+          @properties || (@properties = [])
+        else
+          args.each do |property|
+            properties << property
+            attr_accessor property
+          end
+        end
+      end
+
+      # Generates a request by sending *args to Quickbooks::Qbxml::Request.new, sends the request over the current connection,
+      # and interprets the response using Quickbooks::Qbxml::ResponseSet.
+      # The response is then instantiated into an object or an array of objects.
+      # 
+      # This method is used mostly internally, but it is the yoke of this library - use it to perform custom requests.
+      def request_and_instantiate(obj_or_args,*args)
+        if obj_or_args.is_a?(Quickbooks::Base)
+          reinstantiate = obj_or_args
+        else
+          reinstantiate = nil
+          args.unshift(obj_or_args)
+        end
+
+        objects = [] # This will hold and return the instantiated objects from the quickbooks response
+        self.request(*args).each { |response| objects << response.instantiate(reinstantiate) } # Does not instantiate if it's an error, but simply records response into response_log
+        objects.length == 1 ? objects[0] : objects
+      end
+
+      # Generates a request using Quickbooks::Qbxml::Request, sends it, and returns a Quickbooks::Qbxml::ResponseSet object containing the response(s).
+      def request(*args)
+        Qbxml::ResponseSet.new(
+          self.connection.send_xml(
+            Qbxml::Request.new(*args).to_xml
+          )
+        )
+      end
+
+      # Instantiate a new object with just attributes, or an existing object replacing the attributes
+      def instantiate(obj_or_attrs={},attrs={})
+        if obj_or_attrs.is_a?(Quickbooks::Base)
+          obj = obj_or_attrs
+        else
+          obj = allocate
+          attrs = obj_or_attrs
+        end
+        attrs.each do |key,value|
+          if obj.respond_to?(key.to_s.underscore+'=')
+            obj.send(key.to_s.underscore+'=', value)
+            obj.original_values[key.to_s.underscore] = value
+          end
+        end if attrs
+        obj # Will be either a nice object, or a Quickbooks::Qbxml::Error object.
+      end
+
+      # Queries Quickbooks for all of the objects of the current class's type. For example, Quickbooks::Customer.all will return an array of Quickbooks::Customer objects representing all customers.
+      def all(filters={})
+        [request_and_instantiate(self.class_leaf_name, :query, filters)].flatten
+      end
+
+      # Queries Quickbooks for the first object of the current class's type. For example, Quickbooks::Customer.first will return a Quickbooks::Customer object representing the first customer.
+      def first(filters={})
+        filters.merge!(:MaxReturned => 1) unless filters.keys.include?(:ListID) || filters.keys.include?(:TxnID) || filters.keys.include?(:FullName)
+        request_and_instantiate(self.class_leaf_name, :query, filters)
+      end
+
+      # Creates a new object of the current class's type. For example, Quickbooks::Customer.create(:name => 'Tommy') will create a customer object with a Name of Tommy.
+      def create(*args)
+        new(*args).save
+      end
+    end
+
+    # The default for all subclasses is simply to apply the attributes given, and mark the object as a new_record?
+    def initialize(args={})
+      self.attributes = args
+      @new_record = true
+    end
+
+    # Returns a hash that represents all this object's attributes.
+    def attributes
+      attrs = {}
+      self.class.properties.each do |column|
+        attrs[column.to_s] = instance_variable_get('@' + column.to_s)
+      end
+      attrs
+    end
+    # Updates all attributes included in _attrs_ to the values given. The object will now be dirty?.
+    def attributes=(attrs)
+      raise ArgumentError, "attributes can only be set to a hash of attributes" unless attrs.is_a?(Hash)
+      attrs.each do |key,value|
+        if self.respond_to?(key.to_s.underscore+'=')
+          self.send(key.to_s.underscore+'=', value)
+        end
+      end
+    end
+
+    # Keeps track of the original values the object had when it was instantiated from a quickbooks response. dirty? and dirty_attributes compare the current values with these ones.
+    def original_values
+      @original_values || (@original_values = {})
+    end
+
+    # Returns true if any attributes have changed since the object was last loaded or updated from Quickbooks.
+    def dirty?
+      # Concept: For each column that the current model includes, has the value been changed?
+      self.class.properties.any? do |column|
+        self.instance_variable_get('@' + column.to_s) != original_values[column.to_s]
+      end
+    end
+
+    # Returns a hash of the attributes and their (new) values that have been changed since the object was last loaded or updated from Quickbooks.
+    def dirty_attributes
+      pairs = {}
+      self.class.properties.each do |column|
+        value = instance_variable_get('@' + column.to_s)
+        if value != original_values[column.to_s]
+          pairs[column.to_s] = value
+        end
+      end
+      pairs
+    end
+
+    # Returns true if the object is a new object (that doesn't represent an existing object in Quickbooks).
+    def new_record?
+      @new_record
+    end
+
+    # Saves the attributes that have changed.
+    # 
+    # If the EditSequence is out of date but none of the changes conflict, the object will be saved to Quickbooks.
+    # But if there are conflicts, the updated values from Quickbooks will be written to the original_values, and false is returned.
+    # This way you can deal with the differences (conflicts), if you so desire, and simply call save again to commit your changes.
+    def save
+      return false unless dirty?
+      if new_record?
+        self.class.request_and_instantiate(self, self.class.class_leaf_name, :add, dirty_attributes.camelize_keys!)
+        @new_record = false if !dirty?
+      else
+        # Smart system that respects EditSequences and other people's changes.
+        # 1) Try to save
+        # 2) When we get a status of 3200, that means our EditSequence is not up to date
+        # 3) Replace self's original_attributes with those just retrieved, and update the automatic attributes, like EditSequence and TimeModified
+        # 4) Return false, return the object dirty but ready to save
+        old_originals = original_values.dup
+        self.class.request_and_instantiate(self, self.class.class_leaf_name, :mod, dirty_attributes.camelize_keys!.merge(:ListID => self.list_id, :EditSequence => self.edit_sequence))
+        # If save failed because of old record, but none of the fields conflict, re-save.
+        if dirty? && self.response_log.last.status == 3200
+          # puts "Now Dirty: #{dirty_attributes.keys.join(', ')}\nUpdated: #{old_originals.diff(original_values).keys.join(', ')}"
+          return self.save if dirty_attributes.keys.length == (dirty_attributes.keys - old_originals.diff(original_values).keys).length
+        end
+      end
+      !dirty?
+    end
+
+    # Reloads the record from Quickbooks, discarding any changes that have been made to it.
+    def reload
+      self.class.request_and_instantiate(self, self.class.class_leaf_name, :query, :ListID => self.list_id)
+    end
+
+    # Destroys a record in Quickbooks. Note that even though Quickbooks will destroy the record, the record's ListID and DeletedTime can be accessed by doing a query for deleted objects of the appropriate type.
+    def destroy
+      self.class.request_and_instantiate(self, self.class.class_leaf_name, :delete, self.is_a?(Quickbooks::ListItem) ? {:ListID => self.list_id} : {:TxnID => self.txn_id}).success?
+    end
+  end
+end

data/lib/quickbooks/connection.rb

@@ -1,72 +1,106 @@
+require 'win32ole'
+require 'quickbooks/ole_helper'
 
-module QuickBooks
-  # Connection is  used to communicate with QuickBooks RDS Server.  You need to configure
-  # your QuickBooks software to allow RDS connection from your application.
-  # <code>
-  #   require 'quickbooks'
-  #   
-  #   connection = QuickBooks::Connection.new('admin', 'pass', 'My Test App')
-  #   connection.open
-  #   xml = <<END
-  #   <?xml version="1.0"?>
-  #   <?qbxml version="3.0"?>
-  #   <QBXML>
-  #   <QBXMLMsgsRq onError="continueOnError">
-  #    <InvoiceQueryRq requestID="1">
-  #      <RefNumber>81</RefNumber>
-  #      <IncludeLineItems>true</IncludeLineItems>
-  #    </InvoiceQueryRq>
-  #   </QBXMLMsgsRq>
-  #   </QBXML>
-  #   <<END
-  #   connection.send(xml)
-  #   connection.close
+module Quickbooks
+  # Connection is used internally by Quickbooks::Base to automatically manage a the communication with quickbooks.
+  # Currently the only connection mode supported is WIN32OlE, which means your application must be running on the
+  # same computer as Quickbooks.
+  # 
+  # Quickbooks does not allow the user to close the company or exit the program until all outside applications are
+  # disconnected from its API. Therefore, this class includes an at_exit hook that automatically closes all open
+  # connections for you when your program exits.
   class Connection
-    require 'cgi'
-    require 'soap/wsdlDriver'
-    
-    attr_accessor :user, :password, :application_name, :host, :port
-    
-    # Initializes an instance of QuickBooks::Session
-    def initialize(user, password, application_name, host="localhost", port=3790, mode='multiUser')
+    include QBHelpers
+
+    class << self #:nodoc: all
+      def connections
+        @connections || (@connections = [])
+      end
+      def connections=(v)
+        # raise ArgumentError, "Quickbooks::Connection.connections can only contain Quickbooks::Connection objects, but contains #{v.collect {|c| c.class.name}.uniq.join(', ')} objects" unless v.collect {|c| c.class.name}.uniq == ['Quickbooks::Connection']
+        @connections = v
+      end
+
+      at_exit do
+        Quickbooks::Connection.connections.each do |conn|
+          conn.close
+        end
+      end
+    end
+
+    # Initializes an instance of Quickbooks::Session.
+    # - _application_name_ is required.
+    # - _file_ is optional, in which case the connection will be made to the currently open company file in the Quickbooks application.
+    # - _user_ and _password_ may be required if you have specified a specific file to open.
+    # - _connection_type_ can be one of: ['unknown', 'localQBD', 'remoteQBD', 'localQBDLaunchUI', 'remoteQBOE']
+    # - _connection_mode_ can be one of: ['SingleUser', 'MultiUser', 'DoNotCare']
+    def initialize(application_name='RubyApplication', file='', user='', password='', connection_type='localQBD', connection_mode='DoNotCare')
+      @file = file
       @user = user
       @password = password
       @application_name = application_name
-      @host = host
-      @port = port
-      @mode = mode
-      @ticket = nil
-      @soap_client = nil      
+      @quickbooks = Ole.new('QBXMLRP2.RequestProcessor', 'QBXMLRP2 1.0 Type Library')
+      @connection_type = @quickbooks.get_variable(connection_type)
+      @connection_mode = @quickbooks.get_variable('qbFileOpen'+connection_mode)
+      connection # Just to make it fail now instead of later if it can't connect properly.
     end
-    
-    # Determines if the Session is connected to a QuickBooks RDS Server
+
+    # Returns true if there is an open connection to Quickbooks, false if not. Use session? to determine an open session.
     def connected?
-      if @ticket && @soap_client
-        return true
+      @connected ||= false
+    end
+
+    # Returns true if there is an active session. Use connected? to determine whether you are connected or not.
+    def session?
+      !@session.nil?
+    end
+
+    # Sends a request to Quickbooks. This request should be a valid QBXML request. Use Quickbooks::Qbxml::Request to generate valid requests.
+    def send_xml(xml)
+      connection.ProcessRequest(session, xml)
+    rescue => e
+      warn "ERROR processing request:\n#{xml}"
+      raise # Reraises the original error, only this way we got the xml output
+    end
+
+    # Returns the active connection to Quickbooks, or creates a new one if none exists.
+    def connection
+      @connection || begin
+        @connection = @quickbooks.ole
+        @connection.OpenConnection2('',@application_name,@connection_type)
+        Quickbooks::Connection.connections << self
+        @connected = true
+        @connection
       end
-      return false
     end
-    
-    # Opens a connection to a QuickBooks RDS Server
-    def open
-      @soap_client = SOAP::WSDLDriverFactory.new("https://#{@host}:#{@port}/QBXMLRemote?wsdl").create_rpc_driver
-      @ticket = @soap_client.OpenConnectionAndBeginSession(@user, @password, '', @application_name, '', @mode)
-      return @ticket
+
+    # Begin a session to Quickbooks.
+    def session
+      @session || begin
+        @session = connection.BeginSession(@file,@connection_mode)
+      end
     end
-    
-    # Send a QBXML message to QuickBooks RDS Server
-    def send(xml)
-      @soap_client.ProcessRequest(@ticket, xml)      
+
+    # End the current Quickbooks session. After ending a session, a new session may be reopened if desired.
+    def end_session
+      if !@session.nil?
+        connection.EndSession(@session)
+        @session = nil
+        true
+      else
+        false
+      end
     end
-    
-    # Close the session to QuickBooks RDS Server
+
+    # Close the connection to Quickbooks. Automatically ends the session, if there is one.
     def close
-      if connected? && @soap_client
-        @soap_client.CloseConnection(@ticket)
-        @soap_client = nil
-        @ticket = nil
-      end        
+      end_session
+      if connected? && connection.CloseConnection(@session)
+        @connected = false
+        @connection = nil
+        Quickbooks::Connection.connections = Quickbooks::Connection.connections - [self]
+      end
+      return !@connected # Returns false if CloseConnection failed.
     end
-    
   end
 end