Session and connection object attributes

This page provides detail on many of the attributes used when constructing request messages and processing response message. This are attributes of SDK objects, and not found on the QuickBooks objects.

There are several general types of attributes that are available:

• message set-level attributes
• request attributes
• response attributes
• query attributes

We’ll describe each of these in the following sections.

There are several attributes related to how QuickBooks responds to errors in processing requests sent by your application.

These are message set-level attributes governing how the message set is to processed. For example, the onError attribute specifies how to proceed with subsequent requests in a message set if an error occurs. The newMessageSetID and oldMessageSetID instruct QuickBooks to save processing information in its state until you are sure your request and its response have been successfully processed. The responseData attribute specifies how much of the response to include.

onError Attribute

• stopOnError - directs QuickBooks to process requests until an error occurs and then stop. Neither the current request that raised the error nor any subsequent requests will be processed. Any requests in the same message set that were previously processed successfully are retained. A nonzero status code is returned for the operation that caused the error condition. For messages in the message set subsequent to the one that raised the error, status code 3231 (“Status unprocessed”) is returned.
• continueOnError - directs QuickBooks to continue processing requests even if an error occurs in processing the current request message set.

responseData Attribute

The responseData attribute can have a value of includeAll (the default) or includeNone. Note that if a response is returned without data, it might be because of an error, or it might be the result of the setting for this attribute.

Attributes for Error Recovery

If your application modifies data in the QuickBooks company file, you need to include the error recovery attributes in your request messages:

• oldMessageSetID
• newMessageSetID
• messageSetStatusCode (see below)

The messageSetStatusCode attribute will be in the response message if error-recovery attributes were included in the message set request. It provides the status of the entire request message that was set in the QBXMLMsgsRq request.

For a complete discussion of the use of the oldMessageSetID and newMessageSetID attributes and how to implement an error recovery routine in your application, see Error Recovery. These attributes allow you to instruct QuickBooks to save state concerning processing of the request, to check the processing status of a given request, and to clear state for a given request when you are sure that you’re finished processing the response. Also see the error recovery example included with the QuickBooks SDK Samples.

For requests that are not queries, there is one optional attribute, requestID. This attribute is used in requests in message sets where there are more than one request. The request ID allows you to match up requests and responses (the response to a request will have the same requestID) when you receive them in the response message set. This is important, because the order of requests submitted in the request message set might not be the order of responses coming back in the response message set.

Notice that if you use QBFC, you don’t have to deal with requestIDs. QBFC automatically assigns the requestID to the requests inside the message set, and guarantees that the order of responses returned matches the order of the requests submitted.

Every response contains three types of status information:

• requestID - See above under ‘Request Attributes”
• statusCode - 0 for success; nonzero for information, warnings, and errors.
• statusSeverity - This attribute indicates how severe the error is. It can have one of three values:
  • Info - QuickBooks completed processing your qbXML request and has returned the corresponding data in the remainder of this message.
  • Warning - QuickBooks completed processing your request and has returned the corresponding data, but the results might not be consistent with what you expected.
  • Error - The request was not completed. No data will appear in the response after the status message.
• statusMessage - This attribute explains the error or warning condition that is indicated by the status code.

In addition to the general request and response attributes listed above, queries have several other attributes. These generally are intended to help you manage the amount of query data returned.

Query Request Attributes

These are attributes found in the query request

• iterator may have one of the following values: Start, Continue, Stop
• iteratorID is optional
• metaData is optional and may have one of the following values: NoMetaData, MetaDataOnly, MetaDataAndResponseData

Query Response Attributes

• iteratorID is optional
• iteratorRemainingCount
• retCount

For details on the query attributes, see Query requests and responses.