Class QBFC::Request
In: lib/qbfc/request.rb
Parent: Object

A QBFC::Request handles creating and sending a Request, including creating the RequestSet. Most often, RubyQBFC classes create and execute the Request internally, however, the Base.find, for example, accepts a QBFC::Request object as an argument if greater control is needed.

The WIN32OLE Request object is wrapped in OLEWrapper, so Ruby-esque methods can be used.

  req = QBFC::Request.new(qb_session, "CustomerQuery").
    or_customer_list_query.customer_list_filter.max_returned = 2
  puts req.response

Methods

Public Class methods

session is a QBFC::Session object (or a Session object not created through Ruby QBFC) request_type is the name of the request, not including trailing ‘Rq’, e.g. ‘CustomerQuery’, ‘CustomerMod‘

[Source]

    # File lib/qbfc/request.rb, line 18
18:     def initialize(sess, request_type, country = 'US', major_version = 6, minor_version = 0)
19:       @sess = sess
20:       
21:       begin
22:         @request_set = sess.CreateMsgSetRequest(country, major_version, minor_version)
23:       rescue WIN32OLERuntimeError => error
24:         if error.to_s =~ /error code:8004030A/
25:           raise QBFC::QBXMLVersionError, "Unsupported qbXML version"
26:         else
27:           raise
28:         end
29:       end
30:       
31:       begin
32:         @name = request_type
33:         @request = @request_set.send("Append#{request_type}Rq")
34:       rescue WIN32OLERuntimeError => error
35:         if error.to_s =~ /error code:0x80020006/
36:           raise QBFC::UnknownRequestError, "Unknown request name '#{request_type}'"
37:         else
38:           raise
39:         end
40:       end
41:     end

Public Instance methods

add_includes accepts an Array of elements to include in the return of the Request. 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.

add_includes is typically called by apply_options, typically called from Element.find, as seen in the examples below:

  @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.

[Source]

     # File lib/qbfc/request.rb, line 173
173:     def add_includes(inc)
174:       return if inc.nil?
175:       
176:       inc = [inc] if (!inc.respond_to?(:each) || inc.kind_of?(String))
177:       
178:       if inc.include?(:all)
179:         ole_methods.each do |m|
180:           m = m.to_s
181:           if m =~ /\AInclude/ && m != 'IncludeRetElementList'
182:             @request.__send__("#{m.underscore}=", true)
183:           end
184:         end
185:         return
186:       end
187:       
188:       inc.each do |item|
189:         cam_item = item.to_s.camelize.gsub(/Id/, "ID")
190:         if @request.respond_to_ole?("Include#{cam_item}")
191:           @request.__send__("include_#{item}=", true)
192:         else
193:           @request.IncludeRetElementList.Add(cam_item)
194:         end
195:       end
196:     end

Set MaxReturned to limit the number of records returned.

[Source]

     # File lib/qbfc/request.rb, line 150
150:     def add_limit(limit)
151:       filter.max_returned = limit if limit
152:     end

Add one or more OwnerIDs to the Request. Used in retrieving custom fields (aka private data extensions). Argument should be a single ID or an Array of IDs.

[Source]

     # File lib/qbfc/request.rb, line 140
140:     def add_owner_ids(ids)
141:       return if ids.nil?
142:       
143:       ids = [ids] unless ids.respond_to?(:each)
144:       ids.each do | id |
145:         @request.OwnerIDList.Add(id)
146:       end
147:     end

Applies options from a Hash. This method is generally used by find methods (see Element.find for details)

[Source]

     # File lib/qbfc/request.rb, line 87
 87:     def apply_options(options)      
 88:       if options.kind_of? Hash
 89:         conditions = options.delete(:conditions) || {}
 90:         
 91:         conditions.each do | c_name, c_value |
 92:           c_name = c_name.to_s
 93:           
 94:           case c_name
 95:           when /list\Z/i
 96:             # List filters

 97:             list = query.__send__(c_name.camelize)
 98:             c_value = [c_value] unless c_value.kind_of?(Array)
 99:             c_value.each { |i| list.Add(i) }
100:           when /range\Z/i
101:             # Range filters

102:             c_value = parse_range_value(c_value)
103:             range_filter = filter_for(c_name)
104:             range_name = c_name.match(/(.*)_range\Z/i)[1]
105:             if range_name == 'modified_date'
106:               # Modified Date Range use the IQBDateTimeType which requires a\

107:               # boolean 'asDateOnly' value.

108:               range_filter.__send__("from_#{range_name}=", c_value.first, true) if c_value.first
109:               range_filter.__send__("to_#{range_name}=", c_value.last, true) if c_value.last
110:             else
111:               range_filter.__send__("from_#{range_name}=", c_value.first) if c_value.first
112:               range_filter.__send__("to_#{range_name}=", c_value.last) if c_value.last
113:             end
114:           when /status\Z/i
115:             # Status filters

116:             filter.__send__("#{c_name}=", c_value)
117:           else
118:             # Reference filters - Only using FullNameList for now

119:             ref_filter = filter_for(c_name)
120:             c_value = [c_value] unless c_value.respond_to?(:each)
121:             c_value.each do | val |
122:               ref_filter.FullNameList.Add(val)
123:             end
124:           end
125:         end
126:           
127:         add_owner_ids(options.delete(:owner_id))
128:         add_limit(options.delete(:limit))
129:         add_includes(options.delete(:include))
130: 
131:         options.each do |key, value|
132:           self.send(key.to_s.camelize).SetValue(value)
133:         end
134:       end
135:     end

Get the *Filter object of the given Request For example, the ListFilter

[Source]

    # File lib/qbfc/request.rb, line 69
69:     def filter
70:       q = self.query
71:       return nil if q.nil?
72:       filter_name = q.ole_methods.detect{|m| m.to_s =~ /Filter\Z/}
73:       return nil if filter_name.nil?
74:       q.send(filter_name.to_s.to_sym)
75:     end

Returns where the filter is available for use. That is, that none of the query options other than filter have been used

[Source]

    # File lib/qbfc/request.rb, line 79
79:     def filter_available?
80:       # -1 = unused, 2 = Filter used

81:       self.query.ole_object.ortype == -1 ||
82:         self.query.ole_object.ortype == 2
83:     end

Is this Query for a Report? The ‘conditions’ are treated differently

[Source]

    # File lib/qbfc/request.rb, line 55
55:     def for_report?
56:       @name =~ /Report$/
57:     end

Return Array of ole_methods for request WIN32OLE object. This is mostly useful for debugging.

[Source]

     # File lib/qbfc/request.rb, line 274
274:     def ole_methods
275:       @request.ole_methods
276:     end

Return actual WIN32OLE object

[Source]

     # File lib/qbfc/request.rb, line 291
291:     def ole_object
292:       @request.ole_object
293:     end

Get the OR*Query object of the given Request For example, the ORListQuery

[Source]

    # File lib/qbfc/request.rb, line 61
61:     def query
62:       query_name = @request.ole_methods.detect{|m| m.to_s =~ /Query\Z/}
63:       return nil if query_name.nil?
64:       @request.send(query_name.to_s.to_sym)
65:     end

Submit the Request and return the response Detail, wrapped in OLEWrapper (unless nil). The response does not include any MsgSetResponse attributes.

[Source]

    # File lib/qbfc/request.rb, line 50
50:     def response
51:       submit.ResponseList.GetAt(0).Detail
52:     end

Submit Request and return full response as XML. This is mostly useful for debugging.

[Source]

     # File lib/qbfc/request.rb, line 286
286:     def response_xml
287:       @sess.DoRequests(@request_set).ToXMLString
288:     end

Submit the requests. This returns the full (not wrapped) response object.

[Source]

    # File lib/qbfc/request.rb, line 44
44:     def submit
45:       @sess.DoRequests(@request_set)
46:     end

Return XML for the request WIN32OLE object. This is mostly useful for debugging.

[Source]

     # File lib/qbfc/request.rb, line 280
280:     def to_xml
281:       @request_set.ToXMLString
282:     end

[Validate]