Class QBFC::Element
In: lib/qbfc/element.rb
Parent: Base

An Element is a Transaction or a List; that is any QuickBooks objects that can be created, edited (possibly), deleted and read. Contrast to a Report or Info which are read-only.

Inheritance from Element implies a set of shared methods, such as find, but the only shared implementation defined here is custom, for getting custom field information.


custom   find   is_base_class?   new   new_record?   save  

Public Class methods

Find a QuickBooks record for the given session.

session.[qb_name] aliases this functionality. The following pairs are equivalent:

  QBFC::Vendor.find(session, :first) <-> session.vendor
  QBFC::Vendor.find(session, "Supply Shop") <-> session.vendor("Supply Shop")
  QBFC::Vendor.find(session, :all) <-> session.vendors.find(:all)

Find requires a session (representing a QBFC::Session) and a what argument. what can be one of:

  • :first - finds the first record fitting any given conditions.
  • :finds - finds all records fitting any given conditions.
  • An unique identifier, such as a ListID, FullName, RefNumber or TxnID

.find can also receive a optional Request object followed by an optional options Hash. Valid argument sets are:

  QBFC::Vendor.find(session, :first)
  QBFC::Vendor.find(session, :first, request)
  QBFC::Vendor.find(session, :first, request, options)
  QBFC::Vendor.find(session, :first, options)

The options hash accepts the following:

  • :owner_id: One or more OwnerIDs, used in accessing custom fields (aka private data extensions).
  • :limit: The maximum number of records to be returned.
  • :include: Elements to include (see below for details)
  • :conditions: A hash of conditions (generally ‘Filters’ in QuickBooks SDK. See below:

Additional options are planned, but not really supported in this version. Passing a Request object is the current recommended way of applying unsupported conditions (Filters) or other options to the Query Request.


The :include option accepts an Array of elements to include in the return of the Query. The array may include either or both of elements that are additional to normal returns (such as Line Items, Linked Transactions) or elements that are normally included (to be added to the IncludeRetElementList).

If elements are given that would be added to IncludeRetElementList, this limits the elements returned to only those included in the array.

Another option is to give :all as the argument, which will always return as many elements as possible.

  @sess.checks.find(:all, :include => [:linked_txns]) -> Include linked transactions
  @sess.checks.find(:all, :include => [:txn_id]) -> Include +only+ TxnID
  @sess.checks.find(:all, :include => :all) ->
    Includes all elements, including LinkedTxns and LineItems.


Conditions are dependent on the particular Request. See the QuickBooks SDK documentation for applicable filters for each Query Request. Note that not all Filters are supported.

Typically the condition is given as :filter_name => value where filter_name is the name of the filter less the word ‘Filter’ (see examples below).

Here are some general rules:

List filters
These are filters that end in List. They take an Array of values.
  :ref_number_list => ["1001", "1003", "1003a"]
  :txn_id_list => ["123-456"]
Range Filters
Filters which take a range of values. These accept any object which responds to first and last, such as a Range or Array. first is used to set the From value, last sets the To value. If a scalar value is given (or a single element Array), To is set and From is left empty. nil can also be given for either value.
  :txn_date_range => ['2008-01', nil]
  :txn_date_range => ['2008-01']
  :txn_date_range => '2008-01'

  :ref_number_range => "1001".."1003"
  :ref_number_range => ["1001", "1003"]
Reference Filters
Filters which reference another object (belongs to filters). These current only accept Name arguments, as a single value or an Array.
  :account => 'Checking'
  :entity => ['ABC Supplies', 'CompuStuff']


     # File lib/qbfc/element.rb, line 121
121:       def find(sess, what, *args)       
122:         if what.kind_of?(String) # Single FullName or ListID

123:           return find_by_unique_id(sess, what, *args)
124:         end
126:         # Setup q, options and base_options arguments

127:         q, options, base_options = parse_find_args(*args)
128:         q ||= create_query(sess)
129:         ignore_base_class = options.kind_of?(Hash) ? options.delete(:ignore_base_class) : false
131:         q.apply_options(options)
133:         # QuickBooks only needs to return one record if .find is

134:         # only returning a single record.

135:         if what == :first && q.filter_available?
136:           q.add_limit(1)
137:         end
139:         # Send the query so far to base_class_find if this is

140:         # a base class to handle special base class functionality.

141:         if is_base_class? && !ignore_base_class
142:           return base_class_find(sess, what, q, base_options)
143:         end
145:         # Get response and return an Array, a QBFC::Element-inherited

146:         # object, or nil, depending on <tt>what</tt> argument and whether

147:         # the query returned any records.

148:         list = q.response
150:         if list.nil?
151:           (what == :all) ? [] : nil
152:         elsif what == :all
153:           (0..(list.Count - 1)).collect { |i|
154:             new(sess, list.GetAt(i))
155:           }
156:         else
157:           new(sess, list.GetAt(0))
158:         end
159:       end

Check if this is a "base class" (see is_base_class)


    # File lib/qbfc/element.rb, line 23
23:       def is_base_class?
24:         @is_base_class ? true : false
25:       end

Extends Base#initialize to allow for an Add Request if .new is called directly (instead of by .find)


     # File lib/qbfc/element.rb, line 199
199:     def initialize(sess, ole_object = nil)
200:       super
202:       if @ole.nil?
203:         add_rq =, "#{qb_name}Add")
204:         @ole =
205:         @new_record = true
206:         @setter = add_rq
207:       end
208:     end

Public Instance methods

Access information from a custom field.


     # File lib/qbfc/element.rb, line 216
216:     def custom(field_name, owner_id = '0')
217:       if @ole.DataExtRetList
218:         @ole.data_ext.each do |field|
219:           if field.data_ext_name == field_name && field.owner_id == owner_id.to_s
220:             return field.data_ext_value
221:           end
222:         end
223:       end
225:       return nil
226:     end

Is this a new record, i.e. are we doing an Add Request?


     # File lib/qbfc/element.rb, line 211
211:     def new_record?
212:       @new_record ? true : false
213:     end

Save (create or update) this record


     # File lib/qbfc/element.rb, line 229
229:     def save
230:       if @setter
231:         @setter.submit
232:       else
233:         raise NotSavableError, "This record cannot be saved (Probably because it does not support Mod Requests)."
234:       end
235:     end