ObjSearch Component

Properties   Methods   Events   Config Settings   Errors  

ObjSearch is used to search the QuickBooks database.

Syntax

TiqbObjSearch

Remarks

ObjSearch is used to search the QuickBooks database. When ObjSearch is called a QuickBooks search is initiated using the specified search filters.

Example (Querying for Invoices) ObjSearch1.QueryType = qtInvoiceSearch ObjSearch1.TransactionDateStart = "10/01/2002" ObjSearch1.EntityName = "Joe Reckless" ObjSearch1.PaidStatus = psUnpaid ObjSearch1.Search() Invoice1.QBResponseAggregate = ObjSearch1.ResultAggregate(0) Invoice2.QBResponseAggregate = ObjSearch1.ResultAggregate(1) ' etc. ObjSearch may only be used to search for one type of object at a time. The type of search should be specified in QueryType before beginning the search. The maximum number of returned objects may also be specified in MaxResults.

The search may be executed by calling the Search method. After Search is called ResultCount will hold the number of results, ResultId will hold the Ids returned and Aggregate will hold information for the objects returned. To instantiate an object, set its QBResponseAggregate property to the appropriate Aggregate.

One or more search filters may be specified. These filters limit the search to records meeting specified criteria. If no filters are specified, ObjSearch will return all objects in the database, up to the limit specified by MaxResults.

The following filter may be specified in all searches:

The following filters may be specified when searching for entities (a Customer, Vendor, or Employee). The Name filter may also be specified for Item searches. The following filters may be specified when searching for transactions: Note that for TimeTracking searches the Account and RefNumber filters are not used.

The following additional filter may be specified for Bill and Invoice objects.

The additional filters may be specified for Item objects.

Property List

---

The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the component with short descriptions. Click on the links for further details.

IncludeLineItems Property (ObjSearch Component)

Indicates whether to include line items in the response.

Syntax

property IncludeLineItems: Boolean read get_IncludeLineItems write set_IncludeLineItems;

Default Value

true

Remarks

This filter allows you to omit line items from a query response to get a smaller result. The default value is true, so line items are returned by default. Set IncludeLineItems to false to exclude line items in the response if you don't need to read line item data.

IncludeLinkedTxns Property (ObjSearch Component)

Indicates whether to include linked transactions in the response.

Syntax

property IncludeLinkedTxns: Boolean read get_IncludeLinkedTxns write set_IncludeLinkedTxns;

Default Value

false

Remarks

If you set IncludeLinkedTxns to true, then the returned object will include a list of all the transactions linked to the queried object (this list is similar to the History view of a transaction in the user interface, but not identical, as the SDK list contains only linked transactions, not items). Each linked transaction will be represented by a LinkedTxn aggregate, which will be part of the Aggregate. Passing this aggregate to the corresponding component will parse the linked transactions into their respective properties.

IterateResults Property (ObjSearch Component)

Indicates whether to perform iterative searches when QBXMLVersion = 5.0 or greater.

Syntax

property IterateResults: Boolean read get_IterateResults write set_IterateResults;

Default Value

true

Remarks

This property allows the user to enable or disable iterative searching (Query Iterators) when QBXMLVersion is 5.0 or greater. Please see GetNextResults for more info.

MaxResults Property (ObjSearch Component)

The maximum number of results to be returned from a search.

Syntax

property MaxResults: Integer read get_MaxResults write set_MaxResults;

Default Value

0

Remarks

The maximum number of records to return from QuickBooks.

If MaxResults is set to 0, all records matching the search criteria will be returned.

QBConnectionString Property (ObjSearch Component)

An aggregate consisting of various QuickBooks connection properties.

Syntax

property QBConnectionString: String read get_QBConnectionString write set_QBConnectionString;

Default Value

''

Remarks

QBConnectionString allows the user to customize the application's interaction with QuickBooks.

The connection properties should be formatted in a sequence as follows:

propertyname = "propertyvalue" propertyname = "propertyvalue" ...

The order is irrelevant, and the whitespace around the equal sign is optional.

The following properties are currently supported:

QBRequestAggregate Property (ObjSearch Component)

The request aggregate.

Syntax

property QBRequestAggregate: String read get_QBRequestAggregate write set_QBRequestAggregate;

Default Value

''

Remarks

This property will be populated when QBRequestMode is set to rmOffline and a method is called. This is used when working with the QBWCServer component to generate requests to be sent to QuickBooks Web Connector.

This property is not available at design time.

QBRequestMode Property (ObjSearch Component)

Defines whether the request is made online or stored offline.

Syntax

property QBRequestMode: TiqbQBRequestModes read get_QBRequestMode write set_QBRequestMode;

TiqbQBRequestModes = (
  rmOnline,
  rmOffline
);

Default Value

rmOnline

Remarks

This property defines the behavior of the component when calling a method. Possible values are:

The use of offline mode is required when using the QBWCServer component. This allows requests to be generated and passed to QuickBooks Web Connector through the QBWCServer component.

For normal communication to QuickBooks either directly or through the QBConnector application use the default online mode.

QBResponseAggregate Property (ObjSearch Component)

The last QBXML response aggregate received from QuickBooks.

Syntax

property QBResponseAggregate: String read get_QBResponseAggregate write set_QBResponseAggregate;

Default Value

''

Remarks

The last QBXML response aggregate received from QuickBooks. This property is set whenever a response is received from QuickBooks.

This property may also be set to a response aggregate. When set to a QBXML aggregate, such as a response from ObjSearch or QBWCServer the component will parse the response as if it had been received directly from QuickBooks and the applicable properties will be updated.

This property is not available at design time.

QBXMLVersion Property (ObjSearch Component)

The version of QBXML used in the outgoing message.

Syntax

property QBXMLVersion: String read get_QBXMLVersion write set_QBXMLVersion;

Default Value

'3.0'

Remarks

The version of QBXML used in the outgoing message. Except as noted in the documentation, a value of "1.1" will suffice for all requests, and for all versions of QuickBooks which support integrated applications.

With each release of QuickBooks since 2002, a corresponding version of the QuickBooks SDK has also been released: 1.0 for QuickBooks 2002, 2.0 for QuickBooks 2003, 3.0 for QuickBooks 2004, etc., up to 8.0 for QuickBooks 2009. In addition, each release of QuickBooks continues to support all earlier versions of the SDK, meaning that requests using version 1.1 of the QuickBooks SDK are supported by all versions of QuickBooks. However, new requests and newer fields in existing requests are only supported in later versions of the QuickBooks SDK. As such, it is recommended that you set the QBXMLVersion property to correspond to the version of QuickBooks you are interacting with. These values are:

In addition, versions of QuickBooks outside of the U.S. released before Quickbooks 2008 adhere to a different version of the QuickBooks SDK. These versions were updated with less frequency than the U.S. SDK, and may omit features introduced in later releases: With the exception of Province in Address (set State) or EligibleForT4A in Vendor (set EligibleFor1099), Canadian-only fields are read-only and may be accessed with Config.

This property is not available at design time.

QueryType Property (ObjSearch Component)

The type of search to perform.

Syntax

property QueryType: TiqbTQueryTypes read get_QueryType write set_QueryType;

TiqbTQueryTypes = (
  qtNone,
  qtVendorSearch,
  qtEmployeeSearch,
  qtBillSearch,
  qtInvoiceSearch,
  qtCreditMemoSearch,
  qtVendorCreditSearch,
  qtSalesReceiptSearch,
  qtPurchaseOrderSearch,
  qtCheckSearch,
  qtCCCreditSearch,
  qtCCChargeSearch,
  qtCustomerSearch,
  qtEstimateSearch,
  qtSalesOrderSearch,
  qtTimeTrackingSearch,
  qtReceivePaymentSearch,
  qtJournalEntrySearch,
  qtItemSearch,
  qtAccountSearch,
  qtDepositSearch,
  qtInventoryAdjustmentSearch,
  qtPriceLevelSearch,
  qtClass,
  qtCustomerType,
  qtJobType,
  qtPaymentMethod,
  qtPayrollItemWage,
  qtSalesTaxCode,
  qtShipMethod,
  qtSalesRep,
  qtVendorType,
  qtBillToPayQuery,
  qtItemAssembliesCanBuildQuery,
  qtListDeletedQuery,
  qtPreferencesQuery,
  qtReceivePaymentToDepositQuery,
  qtSalesTaxPaymentCheckQuery,
  qtTxnDeletedQuery,
  qtItemReceiptQuery,
  qtBillPaymentCheckQuery,
  qtBillPaymentChargeQuery,
  qtStatementChargeQuery,
  qtMileageQuery,
  qtOtherTransactionSearch,
  qtOtherListSearch
);

Default Value

qtNone

Remarks

The type of search to perform.

The following values are permitted:

If QueryType is set to qtOtherTransactionSearch or OtherListSearch, SpecialQueryType should be set as well.

This property is required.

RemainingResults Property (ObjSearch Component)

Indicates the number of results left in an iterative search.

Syntax

property RemainingResults: Integer read get_RemainingResults;

Default Value

0

Remarks

A new feature in QuickBooks 2006 allows you to search iteratively. What this basically means is that you can search a customer or transaction list for all transactions, but receive them in chunks of 50 or 100 at a time, instead of one large response potentially containing thousands of entries. This greatly improves response time and also assures that your application does not appear to hang while QuickBooks is putting together the response.

To accomplish such a search, you must set QBXMLVersion to 5.0 or higher. MaxResults will indicates the size of the chunks returned (if set to 0 an iterative search will not be performed). RemainingResults will indicate the number of results remaining. You must also must open and maintain a persistent connection, as searches cannot be continued across sessions. For example:

component.QueryType = qtCustomerSearch() component.MaxResults = 10 component.QBXMLVersion = "5.0" component.OpenQBConnection() component.Search() ' Process first set of results here While (component.RemainingResults > 0) component.GetNextResults() ' Process results here Wend component.CloseQBConnection()

Note that if you wish searches to operate the same way as they did with previous QBXMLVersions, you may set the IterateResults configuration setting to "False". See Config for more information.

This property is read-only.

Results Property (ObjSearch Component)

Contains a collection of search results.

Syntax

property Results: TiqbObjSearchResultList read get_Results;

Remarks

The results of a search will be contained in this property. The Aggregate field contains the XML aggregate of a single search result, and may be passed to the QBResultAggregate property of the component associated with the QueryType of the result.

This property is read-only.

Please refer to the ObjSearchResult type for a complete list of fields.

RetrieveNamesOnly Property (ObjSearch Component)

Return only the names and Ids in the results.

Syntax

property RetrieveNamesOnly: Boolean read get_RetrieveNamesOnly write set_RetrieveNamesOnly;

Default Value

false

Remarks

If RetrieveNamesOnly is True, entity searches (Customer, Employee, etc) will return only the FullName and ListID for each result. The component will silently ignore this property if it is not applicable to the search being performed. This property requires a QBXMLVersion of "4.0" or greater, and is set to False by default.

SearchCriteria Property (ObjSearch Component)

Criteria used to limit a search to specific set of transactions.

Syntax

property SearchCriteria: TiqbSearchCriteria read get_SearchCriteria write set_SearchCriteria;

Remarks

Any number of fields may be combined in a single search. However, some fields are applicable only to specific QueryTypes.

Please refer to the SearchCriteria type for a complete list of fields.

SpecialQueryType Property (ObjSearch Component)

The special query type; for example ItemService.

Syntax

property SpecialQueryType: String read get_SpecialQueryType write set_SpecialQueryType;

Default Value

''

Remarks

This property may be used to query QuickBooks for items supported by the QuickBooks SDK, but not by the component set.

The property should be set to the name of the object being queried for. A list of the objects supported for query operations by the SDK may be found in the SDK documentation.

When performing a special query the QueryType property should be set to qtOtherTransactionSearch or qtOtherListSearch, as appropriate. After searching, the QBObject component may be used to view and/or edit the results.

It is recommended that users using this property first read the SDK documentation.

CloseQBConnection Method (ObjSearch Component)

Closes a persistent connection to QuickBooks.

Syntax

procedure CloseQBConnection();

Remarks

Invoking CloseQBConnection closes the QuickBooks connection specified in QBConnectionString. After the connection has been closed, the component will revert to its default behavior, and a new connection will be established for each request until QBConnectionString is invoked again.

In case the connection is already closed invoking CloseQBConnection will have no effect. Moreover, if multiple connections are open CloseQBConnection will only close the connection specified in QBConnectionString.

Be sure to always invoke this method after calling OpenQBConnection.

Config Method (ObjSearch Component)

Sets or retrieves a configuration setting.

Syntax

function Config(ConfigurationString: String): String;

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

GetNextResults Method (ObjSearch Component)

Retrieves the next set of results (only applicable for iterative searches).

Syntax

procedure GetNextResults();

Remarks

A new feature in QuickBooks 2006 allows you to search iteratively. What this basically means is that you can search a customer or transaction list for all transactions, but receive them in chunks of 50 or 100 at a time, instead of one large response potentially containing thousands of entries. This greatly improves response time and also assures that your application does not appear to hang while QuickBooks is putting together the response.

To accomplish such a search, you must set QBXMLVersion to 5.0 or higher. MaxResults will indicates the size of the chunks returned (if set to 0 an iterative search will not be performed). RemainingResults will indicate the number of results remaining. You must also must open and maintain a persistent connection, as searches cannot be continued across sessions. For example:

component.QueryType = qtCustomerSearch component.MaxResults = 10 component.QBXMLVersion = "5.0" component.OpenQBConnection() component.Search() ' Process first set of results here While (component.RemainingResults > 0) component.GetNextResults() ' Process additional results here Wend component.CloseQBConnection()

Note that if you wish searches to operate the same way as they did with previous QBXMLVersions, you may set the IterateResults configuration setting to "False". See Config for more information.

ImportQBXML Method (ObjSearch Component)

Imports a QBXML response aggregate.

Syntax

procedure ImportQBXML(XMLData: String);

Remarks

This method imports a QBXML response aggregate. When called with a QBXML aggregate, such as a response from ObjSearch or QBWCServer the component will parse the response as if it had been received directly from QuickBooks and the applicable properties will be updated.

OpenQBConnection Method (ObjSearch Component)

Opens a persistent connection to QuickBooks.

Syntax

procedure OpenQBConnection();

Remarks

Invoking OpenQBConnection will open a persistent connection to QuickBooks. After invoking OpenQBConnection, all requests such as Get, Add, etc. will use the established connection until CloseQBConnection is invoked.

The effect of OpenQBConnection is to increase performance. If OpenQBConnection is not invoked, a connection to QuickBooks will automatically be created and destroyed each time the component communicates with QuickBooks. Using OpenQBConnection will be faster, particularly in the case of automatic login.

After OpenQBConnection is invoked, QuickBooks will issue a connection ticket, and it will be stored in QBConnectionString. When CloseQBConnection is invoked the ticket will be invalidated, and any further attempts to use it will fail.

Be sure to invoke CloseQBConnection when you have finished communicating with QuickBooks. Leaving an open QuickBooks connection may lock out other integrated applications, affect QuickBooks performance, or cause other problems.

Reset Method (ObjSearch Component)

Resets all properties to their defaults.

Syntax

procedure Reset();

Remarks

This method resets the values of all properties (and all special fields) to their defaults.

After calling this method, the component may be reused as if it were newly created.

Search Method (ObjSearch Component)

Submits a query request to QuickBooks.

Syntax

procedure Search();

Remarks

Submits a query request to QuickBooks, of the type specified in QueryType.

The number of results may be limited by setting the value of MaxResults. The results will also be limited to objects meeting the search criteria specified. If no search filters are specified, all objects of the requested type will be returned.

After the search, ResultCount will contain the number of results, and Aggregate will contain the returned XML aggregates. These may be assigned to the QBResponseAggregate property of the appropriate control to instantiate the objects.

Error Event (ObjSearch Component)

Information about errors during data delivery.

Syntax

type TErrorEvent = procedure (
  Sender: TObject;
  ErrorCode: Integer;
  const Description: String
) of Object;

property OnError: TErrorEvent read FOnError write FOnError;

Remarks

The Error event is fired in case of exceptional conditions during message processing.

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

SSLServerAuthentication Event (ObjSearch Component)

Fired after the server presents its certificate to the client.

Syntax

type TSSLServerAuthenticationEvent = procedure (
  Sender: TObject;
  const CertEncoded: String;
  const CertEncodedB: TBytes;
  const CertSubject: String;
  const CertIssuer: String;
  const Status: String;
  var Accept: Boolean
) of Object;

property OnSSLServerAuthentication: TSSLServerAuthenticationEvent read FOnSSLServerAuthentication write FOnSSLServerAuthentication;

Remarks

During this event, the client can decide whether or not to continue with the connection process. The Accept parameter is a recommendation on whether to continue or close the connection. This is just a suggestion: application software must use its own logic to determine whether or not to continue.

When Accept is False, Status shows why the verification failed (otherwise, Status contains the string OK). If it is decided to continue, you can override and accept the certificate by setting the Accept parameter to True.

SSLStatus Event (ObjSearch Component)

Fired when secure connection progress messages are available.

Syntax

type TSSLStatusEvent = procedure (
  Sender: TObject;
  const Message: String
) of Object;

property OnSSLStatus: TSSLStatusEvent read FOnSSLStatus write FOnSSLStatus;

Remarks

The event is fired for informational and logging purposes only. This event tracks the progress of the connection.

Status Event (ObjSearch Component)

Shows the progress of the QuickBooks connection.

Syntax

type TStatusEvent = procedure (
  Sender: TObject;
  const Message: String
) of Object;

property OnStatus: TStatusEvent read FOnStatus write FOnStatus;

Remarks

The event is fired for informational and logging purposes only. Used to track the progress of the connection.

Warning Event (ObjSearch Component)

Fired when a warning occurs.

Syntax

type TWarningEvent = procedure (
  Sender: TObject;
  Code: Integer;
  const Description: String
) of Object;

property OnWarning: TWarningEvent read FOnWarning write FOnWarning;

Remarks

The Warning event is fired when the component has produced, or will produce, possibly unexpected results.

Warnings may be generated by QuickBooks or the component. Starred warning codes correspond to warnings and warning codes generated by QuickBooks.

Unlisted QuickBooks warnings will cause the component to throw an exception instead.

Warning 801 will be thrown if the user attempts to Update properties that cannot be updated. For example, the following code will cause this warning to be fired: Customer1.GetByName("Joe Smith") Customer1.Email = "joe@abc.com" 'ok Customer1.CreditLimit = "200.00" 'Not used in Update operations! Customer1.Update() Only the email address will be updated, and the credit limit will be unchanged. Each property description for entity objects lists whether or not it is used in Update operations.

ObjSearchResult Type

Results of a search made with the OBJSEARCH component.

Remarks

This type contains a single result after issuing a search with the ObjSearch component. The Aggregate field contains the XML result aggregate, which you may then pass to a corresponding component to parse.

• Aggregate
• ResultId
• ResultName

Fields

Constructors

constructor Create();

SearchCriteria Type

Criteria used to limit a search to specific set of transactions.

Remarks

This type is used by the ObjSearch component, and describes the transactions the user is looking for.

• AccountId
• AccountName
• AccountType
• ActiveStatus
• EntityId
• EntityName
• ItemType
• ModifiedDateEnd
• ModifiedDateStart
• NameContains
• NameEndsWith
• NameRangeEnd
• NameRangeStart
• NameStartsWith
• PaidStatus
• RefNumber
• RefNumberContains
• RefNumberEndsWith
• RefNumberRangeEnd
• RefNumberRangeStart
• RefNumberStartsWith
• TotalBalanceMaximum
• TotalBalanceMinimum
• TransactionDateEnd
• TransactionDateStart

Fields

Constructors

constructor Create();

Config Settings (ObjSearch Component)

The component accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

ObjSearch Config Settings

Base Config Settings

Trappable Errors (ObjSearch Component)

Errors

The following errors may be generated by the component. Note that frequently the error message will contain more specific information than what is listed here.

ObjSearch Errors