QBSDK_ProGuide Pro Guide

sdk-guide

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 598 [warning: Documents this large are best viewed by clicking the View PDF Link!]

Intuit QuickBooks
®
SDK
Programmer’s Guide
Version 13.0
SDK version 13.0, released November 2013. (c) 2013 Intuit Inc. All rights
reserved.
QuickBooks and Intuit are registered trademarks of Intuit Inc. All other
trademarks are the property of their respective owners and should be treated
as such.
Acknowledgement: This product includes software developed by the Apache
Software Foundation (<http://www.apache.org>) (c) 1999-2006 The Apache
Software Foundation. All rights reserved.
Intuit Inc.
P.O. Box 7850
Mountain View, CA 94039-7850
For more information about the QuickBooks SDK and the SDK documentation,
visit http://developer.intuit.com/.
Contents
3
(c) 2013 Intuit Inc. All rights reserved.
C
ONTENTS
About This Manual
Who Should Read This Manual? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Whats New in This Guide?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Chapter 1: Introduction to QBSDK Programming
What is the SDK? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
What Kinds of Integrations are Possible with the SDK? . . . . . . . . . . . . . . . . . . . . . . 22
Which QuickBooks Editions/Versions Support My Application? . . . . . . . . . . . . . . . . . 23
Whats Included in the QuickBooks SDK Package? . . . . . . . . . . . . . . . . . . . . . . . . . 23
What is the Onscreen Reference OSR? Why Must I Use It? . . . . . . . . . . . . . . . . . . . 24
How Does QuickBooks Toggling Affect My Application? . . . . . . . . . . . . . . . . . . . . . . 24
Do I Have to Use XML? Or are Convenience Libraries Available? . . . . . . . . . . . . . . . . 24
Which Programming Languages Can I Use? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
What Do I Need to Know Before I Start Programming? . . . . . . . . . . . . . . . . . . . . . . 25
What Kind of Technical Support is Available? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Chapter 2: Jumpstart
After the Tech Overview and the SDK Essentials Video... . . . . . . . . . . . . . . . . . . . . . 27
Chapter 3: The Communication Model and Ways of Implementing It
The Basic Communication Pattern. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Authorizations You Need to Know About . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Company Owner Authorization of SDK Applications . . . . . . . . . . . . . . . . . . . . . . 30
Intuit Gateway Authorization of SDK Applications . . . . . . . . . . . . . . . . . . . . . . . 30
Messages: The Content of the Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Whats in a Message?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Ways to Implement Communication With QuickBooks . . . . . . . . . . . . . . . . . . . . . . . 31
Desktop Applications Accessing Local QuickBooks . . . . . . . . . . . . . . . . . . . . . . . 32
Web Services Accessing QuickBooks via QB Web Connector . . . . . . . . . . . . . . . . 32
Chapter 4: Specifying Authorization Preferences
How the QuickBooks UI Supports Authorization/Access . . . . . . . . . . . . . . . . . . . . . . 35
When is the Authorization Dialog Displayed?. . . . . . . . . . . . . . . . . . . . . . . . . . . 35
The Default Authorization Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
How the AuthPreferences Object Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
How to Use the AuthPreferences Functionality. . . . . . . . . . . . . . . . . . . . . . . . . . 38
What Happens as a Result of the AuthPreference Settings? . . . . . . . . . . . . . . . . 40
Setting Authorization Preferences Within QuickBooks. . . . . . . . . . . . . . . . . . . . . 42
4
Contents
(c) 2013 Intuit Inc. All rights reserved.
Chapter 5: Accessing Desktop QuickBooks Editions
Using Java with QB SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
A Note About the Request Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
How to Access QuickBooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
VB Code Snippets for Access if You Use qbXML . . . . . . . . . . . . . . . . . . . . . . . . . 46
VB Code Snippets for Access if You Use QBFC . . . . . . . . . . . . . . . . . . . . . . . . . . 47
What Happens in the Call to BeginSession? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Troubleshooting Errors in the BeginSession Call . . . . . . . . . . . . . . . . . . . . . . . . . 48
Multiple Sessions versus a Single Session. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Using AuthFlags to Specify Support for QuickBooks Editions . . . . . . . . . . . . . . . . . . . 49
Setting AuthFlags to Specify Support for a QuickBooks Edition. . . . . . . . . . . . . . . 50
More Information about Login Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Setting Up Auto-Login. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Only One Auto-Login User per Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Limitations on Accessing Company Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Allowing Application Access to Personal Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Single-User vs. Multi-User Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Trade-offs of Using Single-User Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Microsoft Windows Vista & Windows 7 and UAC. . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Chapter 6: Building Requests In QBFC and in qbXML
A Few Notes About Using QBFC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Building a Request using QBFC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
What You Need to Do in QBFC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Sample: Building a SalesOrder Using QBFC . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
The Importance of the CreateMsgSetRequest Call . . . . . . . . . . . . . . . . . . . . . . . 59
Background Details About the MsgSetRequest Object . . . . . . . . . . . . . . . . . . . . . 60
Another View of the Message Set Request Structure . . . . . . . . . . . . . . . . . . . . . . 61
Building a qbXML Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
What You Need to Do in qbXML using a DOM Document . . . . . . . . . . . . . . . . . . . 62
Chapter 7: Handling Responses Using QBFC or qbXML
Processing a Response Using QBFC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Background Information: Understanding IMsgSetResponse . . . . . . . . . . . . . . . . . 68
Background Information II: IResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Processing a qbXML Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
What You Need to Do to Process a Response in qbXML . . . . . . . . . . . . . . . . . . . . 73
Processing a Response Message Set: Sample Code. . . . . . . . . . . . . . . . . . . . . . . 73
Chapter 8: Creating Queries
When to Use a Query vs a Report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Different Ways of Using Queries to Get the Same Data . . . . . . . . . . . . . . . . . . . . 75
Getting a Count of Query Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Contents
5
(c) 2013 Intuit Inc. All rights reserved.
Limiting the Number of Objects Returned . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Using Iterators to Walk Through Large Query Returns . . . . . . . . . . . . . . . . . . . . 77
Limiting Returned Data Using IncludeRetElement . . . . . . . . . . . . . . . . . . . . . . . 79
Using MaxReturned . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
List Queries: Commonly Used Filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
ListID or FullName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Active Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Filtering by Date Modified. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Match Criterion for Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Ranges for Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Special Information Contained in an AccountRet Object . . . . . . . . . . . . . . . . . . . 84
Special Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Transaction Queries: Commonly Used Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
TxnID or Reference Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Date Filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Entity Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Account Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Reference Number Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Paid Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Requesting Additional Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Special Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
The Generic TransactionQuery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
TransactionQuery and Access Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Filters for TransactionQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Chapter 9: Generating Reports
Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Categories of Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
General Summary Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Job Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Time Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Aging Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Budget Summary Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
General Detail Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Payroll Summary Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Payroll Detail Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Custom Summary and Detail Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Default Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
A Practical Approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Creating a Report Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Modifying a Profit and Loss Standard Report . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Setting Up Filters for a Profit and Loss Standard Report . . . . . . . . . . . . . . . . . . .103
“IncludeColumn” Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
Required Filter for Certain Job Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
Required Filter for Missing Checks Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
Example of a Report Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
Creating Requests for Budget Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
6
Contents
(c) 2013 Intuit Inc. All rights reserved.
Interpreting the Report Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Report Meta-data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Report Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Enumerated Values for “ClearedStatus” Column . . . . . . . . . . . . . . . . . . . . . . . . 110
Transaction Detail Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Order Column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Including Personal Data in Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Including Payroll Data in Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
My Report Has No Data! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Valid Request Options for Individual Report Types . . . . . . . . . . . . . . . . . . . . . . . . . 115
Chapter 10: Modifying and Deleting Transactions and List Objects
Modifying Objects in General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Edit Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
One Way to Delete an Element’s Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Clearing References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Clearing Aggregates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
How to Modify Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Parts of a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Modifying the Body of a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Modifying Transaction Body Without Modifying Line Items . . . . . . . . . . . . . . . . . 130
Shortcut Way to Retaining a Line Item Exactly As Is . . . . . . . . . . . . . . . . . . . . . 130
Modifying a Line Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Inserting a New Line Item In a Mod Operation . . . . . . . . . . . . . . . . . . . . . . . . . 131
Deleting a Line Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Example: Modifying Transaction Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Example: Modifying Groups within the Line Item Table . . . . . . . . . . . . . . . . . . . 132
Example: Modifying Item Lines in an Item Group . . . . . . . . . . . . . . . . . . . . . . . 133
About Modifying Rate, Quantity, and Amount Line Item Fields. . . . . . . . . . . . . . . . . 134
Deleting an Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Must be in Single-User Mode (Except for Enterprise). . . . . . . . . . . . . . . . . . . . . 135
Accountant Copy Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Locked Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
About Closed Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
About Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Voiding an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Chapter 11: Data Ext: Using Custom Fields and Private Data
Core Differences Between Custom Fields and Private Data . . . . . . . . . . . . . . . . . . . 137
How Do I Create Data Extensions? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Enough Pictures: Show Me Some Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
What Makes a Data Ext Definition a Custom Field vs Private? . . . . . . . . . . . . . . . . . 143
But There is More To It . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
A Cool Feature: Transactions Inherit From Customer, Item . . . . . . . . . . . . . . . . . . . 143
Inheriting from Customer to Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Contents
7
(c) 2013 Intuit Inc. All rights reserved.
Inheriting from Item to Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
Do Individual Transactions Also Inherit Custom Field Values? . . . . . . . . . . . . . . .146
Writing to Custom Fields Only Affects the Current Transaction . . . . . . . . . . . . . .146
How Do I Get DataExt Data Back Using Queries? . . . . . . . . . . . . . . . . . . . . . . . . . .146
Writing Data to a Data Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147
Clearing a Value from a Data Extension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148
Deleting a Data Extension Definition: Limitations . . . . . . . . . . . . . . . . . . . . . . . . . .148
Deleting Custom Fields From the QuickBooks UI . . . . . . . . . . . . . . . . . . . . . . . .148
Making Custom Fields Show Up In QuickBooks and in Print . . . . . . . . . . . . . . . . . . .148
I Want to Use Private Data: How Do I Use GUIDs? . . . . . . . . . . . . . . . . . . . . . . . . .151
The Format of the GUID within the Request . . . . . . . . . . . . . . . . . . . . . . . . . . .151
How Do I Retrieve OwnerIDs? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151
What is an OwnerIDList? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151
Using Other, Other1, Other2 in Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151
Writing Custom Field Data to Transaction Lines . . . . . . . . . . . . . . . . . . . . . . . . . . .152
Modifying Custom Field Data in Transaction Item Lines . . . . . . . . . . . . . . . . . . . . . .153
Chapter 12: Using Macros In Requests
What is a Macro? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
Must Macro Names be Unique? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
A Sample Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156
Where Can You Define a Macro? Use a Macro? . . . . . . . . . . . . . . . . . . . . . . . . . . . .157
Using Macros to Set Cleared Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157
Chapter 13: Objects, ObjectRefs, Fullnames, and Attributes
Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159
Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161
Identifiers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162
ListID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162
FullName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .164
Object References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167
About DateTimes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167
Templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167
Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167
Adding an Object: Example of a Request and Response . . . . . . . . . . . . . . . . . . .168
Querying for Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .170
Attributes in the SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171
Message Set-Level Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171
Request Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172
Response Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172
Query Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173
Chapter 14: Event Notification
Using the C# App Template to Implement Eventing . . . . . . . . . . . . . . . . . . . . . . . .175
What Requests Do I Use and How Do I Invoke These? . . . . . . . . . . . . . . . . . . . . . .175
8
Contents
(c) 2013 Intuit Inc. All rights reserved.
How Do I Invoke Subscription Events? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Overview: The Event Notification Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
QuickBooks Events and Event Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Subscribing to Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Authorizing a Callback Application to Receive Events . . . . . . . . . . . . . . . . . . . . 181
Processing Events in a Callback Application . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Handling Special QuickBooks Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Putting it All Together: The Event Notification Flow . . . . . . . . . . . . . . . . . . . . . . 191
Implementing Event-Awareness in qbXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Subscribing, Unsubscribing, and Querying Subscriptions in qbXML . . . . . . . . . . . 191
Implementing a qbXML-based Callback (IQBEventCallback) . . . . . . . . . . . . . . . . 196
Chapter 15: Integrating with the QuickBooks UI
Using the C# App Template to Implement UI Events . . . . . . . . . . . . . . . . . . . . . . . 199
What Types of Integrations Can I Do? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Before Your Application Can Extend the QuickBooks UI . . . . . . . . . . . . . . . . . . . . . 200
Subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Authorization Scenarios Affecting UI Extensions . . . . . . . . . . . . . . . . . . . . . . . . 201
UI Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Menu-Extension Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Adding a Menu Item to QuickBooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Where Your Menu Item Will Appear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Menu Item Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Display Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Getting QuickBooks Context Information From a Menu Item Click . . . . . . . . . . . 211
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
When the Authorization Level Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Lost UI Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Invoking the QuickBooks UI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Opening Transaction Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Opening and Prefilling a New Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Opening List Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Displaying Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Chapter 16: Handling Receive Payment, Bill Payment, and Deposit
Transactions
Core Concepts for Receive Payment and Bill Payment . . . . . . . . . . . . . . . . . . . . . . 217
Applying Payments, Credits, and Discounts . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Linked Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Returned Object for AppliedToTxnAdd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Creating Links Instead of Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Receive Payment Transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Applying a Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Setting Discounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Setting Credits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Contents
9
(c) 2013 Intuit Inc. All rights reserved.
Using ReceivePayment for Credit Card Authorization and Capture . . . . . . . . . . . .224
Modifying a ReceivePayment Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .224
Bill Payment Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .224
Payment Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225
Paying the Bill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225
Setting a Credit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .226
Setting a Discount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .227
Bill Payment Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .227
Modifying a BillPaymentCheck Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .229
Deposits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230
Chapter 17: Linking ItemReceipt/Bill to PurchaseOrder, Invoice to
Sales Order
Important Note about Querying for Linked Transactions . . . . . . . . . . . . . . . . . . . . .233
Linking Bill or ItemReceipt to PurchaseOrder . . . . . . . . . . . . . . . . . . . . . . . . . . . . .234
The Basic User Scenario in the QuickBooks UI . . . . . . . . . . . . . . . . . . . . . . . . .234
Linking an ItemReceipt or Bill to PurchaseOrder Using the SDK. . . . . . . . . . . . . .237
Rules For Linking a Bill or ItemReceipt to a PurchaseOrder . . . . . . . . . . . . . . . . . . .242
Why Does the OSR List LinkToTxn for Unsupported Transactions?. . . . . . . . . . . . . . .242
Converting ItemReceipts to Bills . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .243
Limitations and Pitfalls of Modifying a Bill or ItemReceipt . . . . . . . . . . . . . . . . . . . .243
ItemReceipt and Bill Split Option for QuickBooks Enterprise. . . . . . . . . . . . . . . . . . .243
Re: “Is Manually Closed” in Purchase Orders and Sales Orders. . . . . . . . . . . . . . . . .244
Linking Invoices to SalesOrders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .244
The Basic User Scenario in the QuickBooks UI . . . . . . . . . . . . . . . . . . . . . . . . .245
Linking Invoices to SalesOrders in the SDK. . . . . . . . . . . . . . . . . . . . . . . . . . . .248
Chapter 18: Using SalesReceipt Functionality
Adding a SalesReceipt. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .255
Some Expected Data May be Missing from the Response . . . . . . . . . . . . . . . . . .262
Adding a SalesReceipt in QBFC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .262
Adding a SalesReceipt in qbXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .265
Modifying a SalesReceipt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .266
Special Limitations Imposed By Credit Card Payment Method . . . . . . . . . . . . . . .267
Which SalesReceipt Fields Can Be Modified? . . . . . . . . . . . . . . . . . . . . . . . . . . .267
Which SalesReceipt Fields Can Be Cleared?. . . . . . . . . . . . . . . . . . . . . . . . . . . .267
Modifying a SalesReceipt in qbXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .268
Modifying a SalesReceipt in QBFC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .269
Querying for SalesReceipts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273
Querying for SalesReceipts in qbXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273
Querying for SalesReceipts in QBFC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273
Deleting and Voiding SalesReceipts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273
Chapter 19: Using Credit Card Refund Functionality
Adding a Credit Card Refund Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .275
10
Contents
(c) 2013 Intuit Inc. All rights reserved.
Adding a Credit Card Refund in QBFC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Adding a Credit Card Refund in qbXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Querying for ARRefundCreditCard Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Deleting and Voiding ARRefundCreditCard Transactions . . . . . . . . . . . . . . . . . . . . . 282
Chapter 20: Using Price Levels in Transactions
What is a Price Level? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
The Two Types of Price Levels Supported by QuickBooks . . . . . . . . . . . . . . . . . . 284
Why Are Price Levels Useful? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Are Price Levels Automatically Available? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Using Price Level Functionality in Your Application . . . . . . . . . . . . . . . . . . . . . . . . . 284
How to Create a Price Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Creating a Fixed Percent Price Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Creating a Per Item Price Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
How to Apply a Price Level to a Customer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
How to Apply a Price Level to a Line Item. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Chapter 21: Using Billing Rates To Bill For Time
Which QuickBooks Editions Support Billing Rates? . . . . . . . . . . . . . . . . . . . . . . 291
Key SDK Limitations You Need to Know Before You Start. . . . . . . . . . . . . . . . . . 291
What Happens If I Use Both Price Levels and Billing Rates? . . . . . . . . . . . . . . . . 292
What is a Billing Rate? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
What is the Workflow? How Do I use a Billing Rate?. . . . . . . . . . . . . . . . . . . . . . . . 292
A Detailed Look at the Billing Rates Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Creating Service Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Creating Billing Rates in the UI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Creating Billing Rates in the QB SDK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Assigning Billing Rates to Employees, Vendors, Other Names. . . . . . . . . . . . . . . 303
Using Billing Rates in Time Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Invoicing Customers for Billable Time (UI Only) . . . . . . . . . . . . . . . . . . . . . . . . 305
Chapter 22: Using the Multicurrency Feature in the SDK
Impact of Multicurrency on Existing Applications . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Company Preferences and Multicurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Getting Multicurrency and Home Currency from PreferencesQuery . . . . . . . . . . . 310
QuickBooks Currencies/Exchange Rates and the SDK. . . . . . . . . . . . . . . . . . . . . . . 310
“Built-in” Vs. User Defined Currencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Active Vs. Inactive Currencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
How Do You Set Currency Exchange Rates? . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
What Happens in Transactions When You Change Exchange Rate? . . . . . . . . . . . 311
Multicurrency Effect on Transaction Amounts and Balances. . . . . . . . . . . . . . . . . . . 311
Multicurrency Effect on List Objects Amounts and Balances . . . . . . . . . . . . . . . . . . 311
Multicurrency Effects on Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
ARAccountRef/APAccountRef Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Contents
11
(c) 2013 Intuit Inc. All rights reserved.
Chapter 23: Using the Multi-Location Inventory Feature in the SDK
Impact of Multi-Location Inventory on Existing Applications. . . . . . . . . . . . . . . . . . .313
Company Preferences and Multi-Location Inventory . . . . . . . . . . . . . . . . . . . . . . . .313
Getting Multi-Location Inventory from PreferencesQuery . . . . . . . . . . . . . . . . . .313
InventorySite features for Multi-Location Inventory . . . . . . . . . . . . . . . . . . . . . . . .314
Transfer Inventory Transactions Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .314
Site Attributes for Transaction with Multi-Location Inventory . . . . . . . . . . . . . . . . . .315
Multi-Location Inventory Support for Group Items . . . . . . . . . . . . . . . . . . . . . . . . .316
Chapter 24: Using the Quickbooks Vehicle Mileage Feature
Key Limitations of QB SDK Support for Vehicle Mileage . . . . . . . . . . . . . . . . . . .318
How the Vehicle Mileage Feature Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .319
Setting Up an Item to be Used In Billable Mileage Transactions . . . . . . . . . . . . . . . .321
What Happens to Mileage Charges When I Create Invoices? . . . . . . . . . . . . . . . . . .322
Mileage Charges and Invoices in the UI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .322
Mileage Charges and Invoices in the SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . .323
Adding a Vehicle Mileage Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .324
Adding Vehicle Mileage in qbXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .324
Adding Vehicle Mileage in QBFC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .324
Querying and Deleting Vehicle Mileage Transactions . . . . . . . . . . . . . . . . . . . . . . . .325
Modifying Vehicle Mileage Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .325
Adding, Modifying, Querying Vehicles in the Vehicle List . . . . . . . . . . . . . . . . . . . . .325
Chapter 25: Adding, Modifying, Querying Worker Comp Codes
What Can I Do With the Comp Codes I Create? . . . . . . . . . . . . . . . . . . . . . . . . . . .327
Workers’ Comp Code Feature Requires Payroll Subscription . . . . . . . . . . . . . . . . . . .327
How Can I Tell Whether the Company is Subscribed to Payroll?. . . . . . . . . . . . . .328
Workers Comp Codes in the UI and in the SDK . . . . . . . . . . . . . . . . . . . . . . . . . . .328
Adding a Comp Code with Several Rates Possible via SDK . . . . . . . . . . . . . . . . .329
Current Effective Date and Current Rate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .329
Rate History: Visible Only Through the SDK . . . . . . . . . . . . . . . . . . . . . . . . . . .329
Adding a Workers Comp Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .330
Adding a Comp Code Using QBFC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .330
Adding a Comp Code Using qbXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .331
Querying for Workers Comp Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .331
Querying for Comp Codes in qbXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .331
Modifying Workers Comp Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .332
Modifying a Comp Code in qbXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .333
Chapter 26: Using the Unit of Measure Feature Via the SDK
How Can I Tell If the UOM Feature is Available? . . . . . . . . . . . . . . . . . . . . . . . . . . .335
Which SDK Requests Support UOM? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .335
How Does the UOM Feature Work? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .336
Creating a UOM Set in the UI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .340
12
Contents
(c) 2013 Intuit Inc. All rights reserved.
How Do I Create a UOM Set in the SDK? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Why Do I Need to Follow the UOM Set Naming Convention? . . . . . . . . . . . . . . . 342
Can I Modify a UOM Set in the SDK?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Can I Set UOM Set Defaults for Purchase, Sales, and Shipping? . . . . . . . . . . . . . 342
How Do I Specify Which Units the UOM Set Contains?. . . . . . . . . . . . . . . . . . . . 342
What Does the Abbreviation Field Do? Whys it Required? . . . . . . . . . . . . . . . . . 343
Creating a UOM Set in QBFC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Creating a UOM Set in qbXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
Specifying a UOM Set for an Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
What You Must Do in an Item Mod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Specifying a UOM Set in an Item* Add Request . . . . . . . . . . . . . . . . . . . . . . . . 345
Specifying a UOM Set in an Item* Mod Requst. . . . . . . . . . . . . . . . . . . . . . . . . 346
Using UOM in Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Using UOM in a Transaction Add Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Using UOM in a Transaction Mod Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Chapter 27: Merging Accounts, Customers, Vendors, Classes
What Does ListMerge Do?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
What Happens in the ListMerge Operation? . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
When Can I NOT Do a ListMerge? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Can I Undo or Reverse a ListMerge? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
What Must I Do Before Merging? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Merging Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Comparing AccountType and Changing Sublevel. . . . . . . . . . . . . . . . . . . . . . . . 354
Merging Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Merging Customers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Code Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
Merging Vendors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Chapter 28: Using Assembly Item and BuildAssembly Functionality
Overview of QuickBooks Assembly Items and Build Assembly . . . . . . . . . . . . . . . . . 361
You Must Have Sufficient Components for the BuildAssembly. . . . . . . . . . . . . . . 362
QB Activities that Change BuildAssembly Transactions into Pending . . . . . . . . . . 363
Consequences of Modifying an Existing Inventory Assembly Item. . . . . . . . . . . . 363
Impact of SalesReceipts and Invoices on Assemblies in Inventory . . . . . . . . . . . 364
Disassembling Inventory Assemblies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
Getting BuildAssembly and Assembly Item Reports . . . . . . . . . . . . . . . . . . . . . 365
Adding an Inventory Assembly Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Adding an ItemInventoryAssembly in qbXML . . . . . . . . . . . . . . . . . . . . . . . . . . 369
Adding an Assembly Item in QBFC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Modifying an Existing Inventory Assembly Item . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Modifying an Assembly Item in qbXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Modifying an Assembly Item in QBFC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Querying for Inventory Assembly Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
Querying for Assembly Items in qbXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
Querying for Assembly Items in QBFC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Contents
13
(c) 2013 Intuit Inc. All rights reserved.
Adding a BuildAssembly Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .376
Adding a BuildAssembly Transaction in qbXML . . . . . . . . . . . . . . . . . . . . . . . . .378
Adding a BuildAssembly Transaction in QBFC . . . . . . . . . . . . . . . . . . . . . . . . . .380
Modifying an Existing BuildAssembly Transaction . . . . . . . . . . . . . . . . . . . . . . . . . .380
Modifying a BuildAssembly in qbXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .381
Modifying a BuildAssembly in QBFC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .383
Querying for BuildAssembly Transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .384
Querying For BuildAssembly Transactions in qbXML . . . . . . . . . . . . . . . . . . . . . .385
Querying For BuildAssembly Transactions in QBFC. . . . . . . . . . . . . . . . . . . . . . .385
Chapter 29: Taxes and Discounts (US Versions)
Calculating Sales Tax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .387
Applying Multiple Taxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .387
Applying Discounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .388
Flat vs. Percentage Discounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .389
Nontaxable Flat Discount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .389
Taxable Flat Discount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .390
Chapter 30: Remote Data Sharing and Your Application
What is Remote Data Sharing?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .391
Using RDS Client for Remote Access with QuickBooks Installed Locally . . . . . . . .391
RDS and Event Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .391
Compatibility with Older Versions of RDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . .392
About the RDS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .392
About the RDS Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .394
Distributing RDS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .395
How to Use the SDK Installers and Merge Modules . . . . . . . . . . . . . . . . . . . . . .396
Choices in Implementing Your Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .398
Supporting RDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .399
What Your Application Must Do to Use RDS. . . . . . . . . . . . . . . . . . . . . . . . . . . .399
Which Versions of QuickBooks Support RDS? . . . . . . . . . . . . . . . . . . . . . . . . . .400
What You Need to Tell Your Customers about RDS . . . . . . . . . . . . . . . . . . . . . . .400
RDS-Specific HRESULTs Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .400
Chapter 31: Error Recovery
The General Error Recovery Mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .403
When to Invoke Error Recovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .403
HRESULTs Returned by QuickBooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .403
Automated Error Recovery in QBFC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .404
Implementing Automated Error Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . .404
Using Error Recovery in qbXML-based Applications . . . . . . . . . . . . . . . . . . . . . . . . .405
Error Recovery Using Old and New Message IDs . . . . . . . . . . . . . . . . . . . . . . . .405
How to Clear All Error Recovery Information . . . . . . . . . . . . . . . . . . . . . . . . . . .405
Steps for Using Error Recovery in qbXML-based Applications. . . . . . . . . . . . . . . .405
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .406
14
Contents
(c) 2013 Intuit Inc. All rights reserved.
Message Set Status Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
Request ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
Comparing Requests (Performing a Checksum) . . . . . . . . . . . . . . . . . . . . . . . . 408
Status for Individual Requests within a Message Set. . . . . . . . . . . . . . . . . . . . . 408
Clearing State (oldMessageSetID) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
Maintaining State within Your Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Clearing Error Recovery Records Maintained by QuickBooks. . . . . . . . . . . . . . . . 411
Chapter 32: How to Use the QBFC Convenience Library
Understanding QBFC Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
Objects, Objects Everywhere: Where Do I Start? . . . . . . . . . . . . . . . . . . . . . . . 413
Which Objects Do I Need to Create a Request? . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
How Do I Use the OSR to Fully Construct the Request? . . . . . . . . . . . . . . . . . . . 415
Other Useful IMsgSetRequest Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
Which Objects Do I Need to Process a Response? . . . . . . . . . . . . . . . . . . . . . . . . . 418
Getting Data from the Ret Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
Objects and Methods Used in Processing Response Data . . . . . . . . . . . . . . . . . . 420
Chapter 33: QBFC Language Reference
QBSessionManager Object and Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
QBSessionManager.BeginSession. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
QBSessionManager.ClearErrorRecovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
QBSessionManager.CloseConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
QBSessionManager.CommunicateOutOfProcess . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
QBSessionManager.ConnectionType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
QBSessionManager.CreateMsgSetRequest. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
QBSessionManager.CreateSubscriptionMsgSetRequest . . . . . . . . . . . . . . . . . . . . . . 433
QBSessionManager.DoRequests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
QBSessionManager.DoRequestsFromXMLString . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
QBSessionManager.DoSubscriptionRequests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
QBSessionManager.DoSubscriptionRequestsFromXMLString . . . . . . . . . . . . . . . . . . 437
QBSessionManager.EnableErrorRecovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
QBSessionManager.EndSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
QBSessionManager.ErrorRecoveryID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
QBSessionManager.GetCurrentCompanyFileName . . . . . . . . . . . . . . . . . . . . . . . . . 441
QBSessionManager.GetErrorRecoveryStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
QBSessionManager.GetSavedMsgSetRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
QBSessionManager.GetVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
QBSessionManager.IsErrorRecoveryInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
QBSessionManager.OpenConnection2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
QBSessionManager.QBAuthPreferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
QBSessionManager.QBXMLVersionsForSession. . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
QBSessionManager.QBXMLVersionsForSubscription . . . . . . . . . . . . . . . . . . . . . . . . 449
QBSessionManager.SaveAllMsgSetRequestInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
QBSessionManager.ToEventsMsgSet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
QBSessionManager.ToMsgSetRequest. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
Contents
15
(c) 2013 Intuit Inc. All rights reserved.
QBSessionManager.ToMsgSetResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .453
QQBSessionManager.ToSubscriptionMsgSetResponse . . . . . . . . . . . . . . . . . . . . . . .454
IQBAuthPreferences Object and Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .455
IQBAuthPreferences.GetIsReadOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .456
IQBAuthPreferences.GetPersonalDataPref . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .457
IQBAuthPreferences.GetUnattendedModePref . . . . . . . . . . . . . . . . . . . . . . . . . . . .458
IQBAuthPreferences.PutAuthFlags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .459
IQBAuthPreferences.PutIsReadOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .460
IQBAuthPreferences.PutPersonalDataPref . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .461
IQBAuthPreferences.PutUnattendedModePref. . . . . . . . . . . . . . . . . . . . . . . . . . . . .462
IQBAuthPreferences.WasAuthPreferencesObeyed . . . . . . . . . . . . . . . . . . . . . . . . . .463
IMsgSetRequest Object and Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .464
IMsgSetRequest.Append* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .466
IMsgSetRequest.Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .467
IMsgSetResponse Object and Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .468
IRequest Object and Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .468
IResponse Object and Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .469
Chapter 34: Digitally Signing Your Code
Can I Sign ActiveX or Java Applications? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .471
About Microsoft Authenticode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .471
What is a Digital Certificate? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .471
The Certificate Authority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .472
Code Signing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .472
Obtaining a Digital Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .472
Commercial CA Entities You Can Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .473
Obtaining the Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .473
Signing Your Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .473
Do You Have Everything You Need? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .473
An Example Using a Test Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .474
Signing Code With the Internet Client Software Developers Kit . . . . . . . . . . . . .475
Chapter 35: Tips and Techniques
Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .481
Validating Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .483
Investigating the Problem Thoroughly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .483
Building a Test Case to Make Available to Developer Support . . . . . . . . . . . . . . . . . .483
Sending a Test Case and the Log File to Developer Support . . . . . . . . . . . . . . . . . . .484
Chapter 36: Supporting Your User
Using the SDKDiag Tool to Support Your User . . . . . . . . . . . . . . . . . . . . . . . . . . . .485
Helping Users Troubleshoot and Resolve Problems . . . . . . . . . . . . . . . . . . . . . . . . .485
Multiple Installed Versions of QuickBooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . .486
Incompatible Versions: QuickBooks and Company File . . . . . . . . . . . . . . . . . . . .486
Different Company File Is Already Open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .486
16
Contents
(c) 2013 Intuit Inc. All rights reserved.
Warn Your Users to Complete Error Recovery
before Upgrading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
Versions of Integrated Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
Provide a Means for Breaking Out of Error Recovery . . . . . . . . . . . . . . . . . . . . . 487
Topics to Include in Your Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
Permissions Required for Auto-Login. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
QuickBooks User Permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
Application Access to Personal Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
Complete Error Recovery before Upgrading . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
Chapter 37: Making Your Application Robust
Types of Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491
Appendix A for Status Code Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491
Monitoring HRESULTs and HTTP Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
Monitoring Message Set Status Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
Monitoring Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
Using the Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
Software Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
Checking the QuickBooks Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
Dealing with Unsupported Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
Error Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
Synchronizing Data between Your Application and Quickbooks . . . . . . . . . . . . . . . . 499
Monitor Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
Example of Synchronizing Data with QuickBooks . . . . . . . . . . . . . . . . . . . . . . . 500
Three-Month Limit for ListDeletedQueryRq . . . . . . . . . . . . . . . . . . . . . . . . . . . 503
Modification Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503
Cases Needing Complete Re-Sync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503
Check with the User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503
Chapter 38: Redistributing SDK Components With Your Application
Using the Installers and Merge Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
Using the Stand-Alone Installers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506
Using the Merge Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506
Appendix A: Status Codes for qbXML Responses
HRESULTS from qbXML COM Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515
Appendix B: QuickBooks Data Accessible Via SDK Objects/Operations
Objects/Operations Supported by Desktop Editions . . . . . . . . . . . . . . . . . . . . . . . . 519
SDK Requests Supported in QuickBooks Simple Start Edition . . . . . . . . . . . . . . . . . 522
Additional Differences for SDK Support of QB Simple Start . . . . . . . . . . . . . . . . . . . 529
Contents
17
(c) 2013 Intuit Inc. All rights reserved.
Appendix C: qbXML Specification for the Canadian and UK Editions
Notes for QB CA/UK 2008 and Newer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .531
Canada . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .531
UK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .531
Notes for QB CA/UK 2007 and Older . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .532
Differences Between the Canadian and UK Specs . . . . . . . . . . . . . . . . . . . . . . .532
Differences Between the US and Canadian qbXML Spec . . . . . . . . . . . . . . . . . . .534
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .536
About Units of Measure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .536
About UI Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .537
Appendix D: qbXML RequestProcessor Method Reference
AuthPreferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .542
BeginSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .543
CloseConnection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .545
EndSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .546
GetCurrentCompanyFileName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .547
GetIsReadOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .548
GetPersonalDataPref . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .549
GetUnattendedModePref . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .550
WasAuthPreferencesObeyed. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .551
PutAuthFlags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .552
PutIsReadOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .553
PutPersonalDataPref . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .554
PutUnattendedModePref . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .555
MajorVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .556
MinorVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .557
OpenConnection2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .558
ProcessRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .559
ProcessSubscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .560
QBXMLVersionsForSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .561
QBXMLVersionsForSubscription. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .562
ReleaseLevel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .563
ReleaseNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .564
Appendix E: Enterprise Edition and Single/Multi-User Issues
Enterprise Features Requiring Single User Mode . . . . . . . . . . . . . . . . . . . . . . . . . . .565
Enterprise List Operations Requiring Single User Mode . . . . . . . . . . . . . . . . . . . . . .566
Enterprise Multi User Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .566
Appendix F: Overpayments and Refunds
Overpayments and Refunds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .569
The Manual Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .572
18
Contents
(c) 2013 Intuit Inc. All rights reserved.
Taking it to the SDK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
QuickBooks 2007 to the Rescue! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582
Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587
Who Should Read This Manual?
19
(c) 2013 Intuit Inc. All rights reserved.
A
BOUT
T
HIS
M
ANUAL
This manual provides general and detailed information on how to create an application that
effectively integrates with QuickBooks. A wide range of topics is covered, including how
to make the communication work, how to build request mesages, the structure and content
of specific request messages, how to use the QBFC convenience library, and so forth. It
assumes that you are familiar with and have read the Technical Overview, which introduces
many of the concepts used in this document.
A very useful video called QuickBooks SDK Essentials is also available online at the IPP
developer website to help you get started quickly and in the the right direction.
Who Should Read This Manual?
This manual is a reference resource for all developers who are creating applications that
integrate with QuickBooks. It provides practical information on how to create request
messages and interpret response messages using the QuickBooks SDK, regardless of which
API you choose (that is, qbXML or QBFC) or the QuickBooks product that is your target.
It describes the details of how to create queries and reports and guides you through dealing
with complex transactions such as receive payment and bill payment. Important new
features such as event notification and integrating with the QuickBooks user interface are
described in detail. This manual also focuses on general application concerns such as error
recovery, how to synchronize application data with QuickBooks, and how to anticipate
typical user problems in your application.
Before You Begin
Before you read the rest of this manual, be sure you’ve read the Technical Overview for the
QuickBooks Software Development Kit (SDK). This manual assumes you’re already
familiar with the introductory material and key concepts contained in the overview. Be sure
to check out the Onscreen Reference for QuickBooks, which contains the syntax for each
request and response message type for all of the SDK APIs.
This manual applies to integrating an application with any QuickBooks product. In many
cases, developers may be creating an application that integrates with several QuickBooks
products (for example, U.S. edition of QuickBooks, Canadian edition of QuickBooks, and
UK edition of QuickBooks).
I
MPORTANT
The Onscreen Reference is central to your programming
tasks. You need to refer to it when you are programming
because it contains the syntax and tag names required.
20
About This Manual
(c) 2013 Intuit Inc. All rights reserved.
What’s New in This Guide?
This version of the programmers guide has been restructured to highlight important topics
at the table of contents level. New chapters have been added to cover aspects of SDK
programming that were troublesome for many developers and existing chapters have been
revised for the same reason. Also new in this version is documentation on new features
available in the SDK, such as billing rates, vehicle mileage, and so forth.
What is the SDK?
21
(c) 2013 Intuit Inc. All rights reserved.
C
HAPTER
1 1
I
NTRODUCTION
TO
QBSDK P
ROGRAMMING
1
This chapter provides answers to questions many developers have when they start
investigating the QuickBooks SDK, which we’ll call “QBSDK” or simply “SDK” from this
point forward. What you should expect to find here are answers to many of the questions
you are likely to have when you first pick up the QBSDK and try to figure out what it does
and how you can use it:
What is the SDK and why should I use it?
What kinds of integrations are possible with the SDK? What kind of integrations with
the QuickBooks UI and event flow are possible? Which QuickBooks features and data
are accessible or not accessible?
If I develop an application, which versions and editions of QuickBooks will support it?
What is all this stuff included in the SDK package?
What is the Onscreen Reference, and why do I need to use it?
Do I have to use XML or are there convenience libraries to make life easier for me?
Which programming languages can I use?
What do I need to know in order to start programming?
What kind of technical support is available? Where can I go for information that is not
in the SDK documentation?
What impact does the QuickBooks Accountant version’s toggling feature have on
integrated applications?
What is the SDK?
The term “QuickBooks SDK” or simply “SDK” can refer either to the QBSDK package that
contains the tools, samples, and documentation or it can refer to the QBXML request
processor, which is a runtime component that is shipped with QuickBooks. In this guide,
we’ll use “SDK” to mean the runtime component and “SDK package” when we are referring
to the set of tools, samples, and so on.
It is the QBXML request processor that provides the actual functionality that integrated
applications use when these applications access QuickBooks. Your application uses the
request processor whenever it accesses a QuickBooks company: the request processor does
the qbXML validation, sends the requests to QuickBooks and returns the QuickBooks
responses (see Figure 1-1 on page 22).
As shown in Figure 1-1 on page 22, the request processor provides QuickBooks access to
your application for QuickBooks desktop edition. Notice that the input and the output is
XML, even if you use the QBFC convenience library, but QBFC does all the XML work for
you (more on the QBFC library later in this chapter).
22
Chapter 1: Introduction to QBSDK Programming
(c) 2013 Intuit Inc. All rights reserved.
Figure 1-1 Accessing QuickBooks through the request processor
Notice that the Request Processor is a DLL that is installed during a QuickBooks installation,
and runs in the same process as QuickBooks.
What Kinds of Integrations are Possible with the SDK?
If you are scoping out a potential application, you’ll want to know the kinds of integrations
that are possible with the SDK. The SDK originally provided only data access integration,
and data access is still the most prominent feature of the SDK. A list of the QuickBooks
data and objects that are made accessible via the SDK is provided in Appendix B,
“QuickBooks Data Accessible Via SDK Objects/Operations.”
However, more recent releases of the SDK also provide integration with QuickBooks
events, where your application can subscribe to various events and receive notification
when certain types of QuickBooks activity occur, for example, you can be notified when a
customer is added or modified, and so forth.
Another integration that is possible is to integrate with the QuickBooks UI in two specific
areas:
Menu, where your application can place a menu item within certain QuickBooks
pulldown menus.’
Displaying forms, where your application can cause certain QuickBooks forms to be
displayed, and even prefill some of these forms.
Which QuickBooks Editions/Versions Support My Application?
23
(c) 2013 Intuit Inc. All rights reserved.
The Programmers Guide describes all of the integrations, the data integrations are covered
throughout the guide. The UI and event integrations are covered in two chapters:
Chapter 15, “Integrating with the QuickBooks UI.
Chapter 14, “Event Notification,”
Which QuickBooks Editions/Versions Support My Application?
The release notes provided with the QB SDK package include the latest tables listing the
QuickBooks versions and editions and the corresponding level of the qbXML spec that they
support. Please refer to the release notes for those details.
The SDK provides methods for querying which version of the qbXML specification is
supported by the version of QuickBooks that is currently running on the users system. (The
QBXMLVersionsForSession) method can be called after the session begins.) If you write
“smart” code that checks the version and responds accordingly, your application can run
against multiple versions of QuickBooks.
What’s Included in the QuickBooks SDK Package?
Conceptually, the QuickBooks SDK includes the following software libraries, manuals,
utilities, and examples. Remember that the qbXML Request Processor is a runtime
components of QuickBooks itself and is shipped with QuickBooks.
Software libraries. APIs for creating, sending, and receiving QuickBooks messages.
These libraries, include
> qbXML Request Processor Interface
> QuickBooks Foundation Class (QBFC) Library
qbXML specification. The qbXML specification is described in qbXML schema files
that are distributed with QuickBooks. QuickBooks validates your application’s requests
against the qbXML specification.
QuickBooks Web Connector. The QB Web Connector is a component that makes it
easier for web services to access QuickBooks. Programming applications that work
with the QB Web Connector is documented in the QuickBooks Web Connector
Programmers Guide, which is included with the SDK.
qbmsXML specification. The qbmsXML specification details the QBMS transaction
requests and responses that are available for applications that integrate with the
QuickBooks Merchant Service.
Example qbXML file. This file (qbxmlops*.xml) includes examples of all qbXML
request and response messages.
Example qbmsXML file. This file (qbmsxmlops*.xml) includes examples of all
qbmsXML request and response messages.
• Documentation. In addition to this Programmers Guide, the following QuickBooks
SDK documentation is available:
> Onscreen Reference
24
Chapter 1: Introduction to QBSDK Programming
(c) 2013 Intuit Inc. All rights reserved.
>Developers Guide for QBMS (QuickBooks Merchant Service)
> QuickBooks Web Connector Programmers Guide
> Technical Overview
• Utilities. The SDK includes several utilities to aid in your development cycle. To verify
that a given qbXML or qbmsXML document conforms to the qbXML or qbmsXML
specification, use the qbXML Validator utility. To test the request/response cycle, use
the SDKTest+ utility, which accepts a qbXML request, sends it to QuickBooks, and
returns the response. Source code for SDKTest+ is available in multiple languages for
desktop versions of QuickBooks.
Sample applications. The SDK includes a large set of sample application programs,
including both source code and executable files in Visual Basic, C, C++, and Java.
What is the Onscreen Reference OSR? Why Must I Use It?
Once you’re ready to program, you’ll use the Onscreen Reference often to find out the exact
syntax of a given request or response. This online tool provides detailed reference
information for all developer libraries—qbXML and QBFC for QuickBooks (U.S),
QuickBooks (Canada), QuickBooks (UK), and qbmsXML (for QuickBooks Merchant
Service).
The OSR includes descriptions of each object, aggregate, and element in the SDK. For each
element, it includes the data type, maximum length (for strings) or range (for numerical
values), whether it is required or optional, and whether it is restricted to a particular release.
This online tool is also a handy place to look up the meaning of any SDK error code.
How Does QuickBooks Toggling Affect My Application?
QuickBooks 2006 and later Premier and Enterprise Accountant versions support the
toggling feature, in which the Accountant version can be toggled to become the other
editions and flavors. Some developers use the Accountant version for just that toggling
ability, to make sure their application works on targetted editions and flavors.
Notice that any SDK application with an open connection to the company file must close
that connection prior to the toggling. After the toggling, the application can re-open the
connection.
Do I Have to Use XML? Or are Convenience Libraries Available?
An important initial decision you’ll need to make is whether to use the qbXML Request
Processor API or the QBFC API. The main difference between the two approaches is that the
qbXML Request Processor API requires you to create and parse qbXML documents
explicitly. With the QBFC interface, you are relieved of the task of parsing the qbXML
content because you specify the data in terms of parameter/value pairs within COM methods.
There is little performance difference between the two approaches.
Which Programming Languages Can I Use?
25
(c) 2013 Intuit Inc. All rights reserved.
Which Programming Languages Can I Use?
The QuickBooks SDK is designed for use by a wide variety of developers in many different
development environments. Its application programming interfaces (APIs) can be used by any
programming language that is compatible with Microsoft’s Component Object Model
(COM).
What Do I Need to Know Before I Start Programming?
You need to know the functional area of QuickBooks that you intend to access in your
program. You need to know how the UI works in that area: what you can do in the UI and
what you cannot do. In general, the SDK simply mirrors the functionality provided in the
UI.
What Kind of Technical Support is Available?
The best source of additional information are the forums, knowledgebases, and FAQs that
are provided free of charge at https://developer.intuit.com. If further assistance is required,
use the technical support links provided at that site to contact technical support.
26
Chapter 1: Introduction to QBSDK Programming
(c) 2013 Intuit Inc. All rights reserved.
After the Tech Overview and the SDK Essentials Video...
27
(c) 2013 Intuit Inc. All rights reserved.
C
HAPTER
2 1
J
UMPSTART
1
If you are new to QB SDK programming, the fastest and surest way to get started in QB
SDK programming is use the following two resources:
The Technical Overview, which is supplied with the QB SDK installation.
The QuickBooks SDK Essentials Video available free at the IPP Website
The video, which can be downloaded or viewed on the web, runs about one hour. It will
save you many times over that amount of time in getting you on the right track. We highly
recommend this video to newcomers and to anyone not entirely comfortable in SDK
programming.
After the Tech Overview and the SDK Essentials Video...
Once you read the Technical Overview and take a look at the SDK Essentials video, and are
ready to investigate programming one of the SDK features, consider these resources in this
recommended order:
1. Consult the QB SDK Programmers Guide (this document) for the topic area you are
interested in. Doing this can save you lots of time later.
2. Check out the OSR for an understanding of the request features.
3. Check out the programming samples in the qbsdk\samples subdirectory, including the
xmlfiles subdirectory. You should be able to find much of what you need there.
4. Search the IPP Live Community forums.
28
Chapter 2: Jumpstart
(c) 2013 Intuit Inc. All rights reserved.
The Basic Communication Pattern
29
(c) 2013 Intuit Inc. All rights reserved.
C
HAPTER
3 1
T
HE
C
OMMUNICATION
M
ODEL
AND
W
AYS
OF
I
MPLEMENTING
I
T
1
This chapter describes the basic communication pattern used by all SDK applications,
authorizations of SDK applications, which is part of that pattern, and the different ways that
you can implement communication with QuickBooks.
The Basic Communication Pattern
All communication between QuickBooks and SDK applications follow the same basic
pattern. The application first establishes communication with QuickBooks (this involves
both connection-related method calls AND human interaction (getting the company
owners authorization). The application then sends a request set containing one or more
requests. QuickBooks processes the requests and sends back a response set containing one
or more responses (Figure 3-1).
Figure 3-1 The Basic Communication Model
This is a pretty high level view of things, but it is general enough to serve for the various
supported ways to access QuickBooks. Once you get down to particular types of access,
such as desktop applications accessing local QuickBooks, you’ll learn about request
processor DLL running in the QuickBooks process to handle incoming requests and send
out outgoing requests. We’ll cover those details a little further on in this chapter.
Authorizations You Need to Know About
There are two types of authorization that impact your application:
Company owner authorization, which applies to all SDK applications
Gateway authorization, which applies to applications using Intuit gateway such as QB
Merchant Services.
30
Chapter 3: The Communication Model and Ways of Implementing It
(c) 2013 Intuit Inc. All rights reserved.
Company Owner Authorization of SDK Applications
No SDK application can access a QuickBooks company unless the company owner (your
customer) authorizes that application. The first time your application accesses QuickBooks,
the company owner is prompted to grant or deny the access and also limit the access to
certain areas of QuickBooks data. The authorization grant can be a good-until-cancelled
authorization or a single session authorization. The authorization also can restrict access to
sensitive data, if desired by the company owner.
Once authorization is granted, the application can access the company, but you should be
aware that the owner can revoke that authorization at any time from within QuickBooks.
The way authorization is granted and how your application responds to the authorization
mechanism varies with the way you are communicating with QuickBooks. So we’ll discuss
authorization mainly from within each type of implementation.
Intuit Gateway Authorization of SDK Applications
If your application is using Intuit gateway QB Merchant Services, then it must be
authorized by those Intuit gateways or your connection attempt through them will fail.
Gateway authorization is entirely separate from company owner authorization: it is
controlled entirely from the side of Intuit. The gateway’s authorization for desktop
applications is acquired by registering the application with IPP. The gateway’s authorization
for hosted web applications is acquired by registering with IPP and in addition acquiring a
certificate from Intuit. Application registrations and certificates are described in the chapter
that covers accessing QBMS.
Authorization of your application, whether desktop or hosted, can be revoked by the Intuit
gateways at any time if your application is causing problems, which is why your
registration should have current contact information in it.
Messages: The Content of the Communication
Whatever the communication model, the “stuff” being communicated is qbXML message.
Messages are of two types:
requests that your application sends to QuickBooks
responses that QuickBooks returns to your application
One or more individual messages are grouped into a message set, which contains a
collection of either requests or responses.
Ways to Implement Communication With QuickBooks
31
(c) 2013 Intuit Inc. All rights reserved.
The name of a message indicates the QuickBooks object it deals with and the operation to
be performed on that object, as described in the following sections. Request messages have
the suffix Rq, and response messages have the suffix Rs. To get a feel for the messages
you’ll be working with, spend a few minutes exploring the Onscreen Reference for your
target QuickBooks product.
What’s in a Message?
The smallest component of a message is an element. The exact form of an element depends
on the API you’re using—whether you’re using the qbXML Request Processor API or the
QBFC (QuickBooks Foundation Class) Library to create requests and interpret responses.
Elements are name/value pairs and sometimes have associated attributes. Messages group
elements into containers called aggregates.
Regardless of the API you choose, the concepts are the same, which is why this manual
addresses the needs of multiple QuickBooks SDK audiences. For purposes of brevity, most
of the examples are in qbXML. If you’re using the QBFC COM API, the messages will be
constructed differently, but the elements, aggregates, and attributes will be used in exactly
the same manner.
For example, here is a request to add an account, AccountAddRq:
<AccountAddRq requestID=”2”>
<AccountAdd>
<Name>Checking Account</Name>
<AccountType>Bank</AccountType>
<BankNumber>0350039560</BankNumber>
</AccountAdd>
</AccountAddRq>
In this example, AccountAdd is an aggregate that contains the essential data of the
message. Name, AccountType, and BankNumber are all elements. AccountAddRq is also
an aggregate and is often referred to as the message aggregate since it contains the entire
message and its request ID (which, in qbXML, is an attribute).
In qbXML, an element or aggregate begins with its name in angled brackets:
<AccountAdd>
and ends with the name, preceded by a backslash, also in angled brackets:
</AccountAdd>
Ways to Implement Communication With QuickBooks
Your application can communicate with QuickBooks in any of the following ways:
A desktop application accessing a local QuickBooks
32
Chapter 3: The Communication Model and Ways of Implementing It
(c) 2013 Intuit Inc. All rights reserved.
A remote web application (web service) accessing a local QuickBooks via the local
QuickBooks Web Connector (QBWC)
I
MPORTANT
You can also access QuickBooks POS and/or QuickBooks
Merchant Service (QBMS) from any of the above
implementations. For details please refer to the QB POS SDK
Programmers Guide and the QBMS Programmers Guide.
Desktop Applications Accessing Local QuickBooks
The most typical communication is shown in Figure 3-2, where a desktop application
accesses a QuickBooks installation running on the same machine.
Figure 3-2 Desktop Application to Desktop QuickBooks Communication
In this implementation type, notice that the developer application drives the connection and
data exchange.
Where to Find More Details
This communication type has been around forever and so has the documentation for it. For
all the details related to communication, including sample code, see Chapter 5, “Accessing
Desktop QuickBooks Editions.”.
Web Services Accessing QuickBooks via QB Web Connector
One of the more recent access types is a remote web service accessing a local QuickBooks
(see Figure 3-3).
Ways to Implement Communication With QuickBooks
33
(c) 2013 Intuit Inc. All rights reserved.
Figure 3-3 Remote Web Service Accessing Local QuickBooks
As shown in the figure, the Web Connector functions as the SDK application. At user
specified intervals, the Web Connector asks the remote web service if it has any outstanding
work to do. (QBWC knows how to contact the web service from a QWC file obtained from
the web service provider.)
User name and password are supplied to the web service in this initial contact, so the web
service can do the lookups and see what needs to be done for that user. If the web service
has work for the user, it sends the proper qbXML requests to QBWC. QBWC passes them
on to QuickBooks and then returns the QuickBooks response to the remote service.
All the communication between web service and QBWC is done over HTTPS for security
purposes. This means a web service must obtain and use a standard industry certificate from
providers like Thawte, Verisign, and so forth.
Where to Find More Details
For complete details on implementing the required QBWC web service interfaces, see the
QBWC Programmers Guide, which is included in the QB SDK.
34
Chapter 3: The Communication Model and Ways of Implementing It
(c) 2013 Intuit Inc. All rights reserved.
How the QuickBooks UI Supports Authorization/Access
35
(c) 2013 Intuit Inc. All rights reserved.
C
HAPTER
4 1
S
PECIFYING
A
UTHORIZATION
P
REFERENCES
1
The QuickBooks administrative user is the one who authorizes your application for access
to the company, and can restrict that authorization in various ways, such as not allowing
access to sensitive financial data. This can adversely affect your application if it needs more
access permissions than the QuickBooks user grants it. How do you handle this situation?
For QB Simple Start edition, there is no built-in way using the SDK to solve this problem.
However, for desktop editions of QuickBooks other than Simple Start, there is a way for
your application to notify the user about required access permissions. You can use the
AuthPreferences object to tell the QuickBooks user what your application needs.
This chapter describes the overall authorization behavior built into the QuickBooks UI, and
how the AuthPreferences object works with it to prompt the user to grant needed access
rights.
How the QuickBooks UI Supports Authorization/Access
The first time your application logs in to QuickBooks, QuickBooks must already be
launched and running in the foreground with a company file open and the administrator
user logged in. These requirements prevent unauthorized applications from gaining access
to QuickBooks. The authorization process is triggered by the call to BeginSession.
When is the Authorization Dialog Displayed?
The authorization dialog appears when an application tries to access a QuickBooks
company file for the first time. The authorization dialog is also displayed when
A QuickBooks company file is opened for the first time by an application after it makes
an event subscription
An application previously authorized to access a particular QuickBooks company file
attempts to access that file in a way different than authorized or with different
preferences than the last time it accessed that file. This supports the AuthPreference
functionality that allows your application to prompt the user to provide the type of
authorization your application needs.
The Default Authorization Dialog
The default authorization dialog is the one that QuickBooks presents to the user if the
AuthPreferences property is not used. It is shown in Figure 4-1. In this authorization dialog,
the QuickBooks administrator can
36
Chapter 4: Specifying Authorization Preferences
(c) 2013 Intuit Inc. All rights reserved.
Refuse authorization by selecting “No”
Authorize for only the current session and force the application to be authorized again
the next time the application attempts to access a company file by selecting "Prompt
each time"
Authorize the application to access QuickBooks with no additional authorization
whenever that company file is open, regardless of which user is logged in by selecting
“Yes, whenever this company file is open.”.
Authorize the application to log on in unattended mode (auto login) by selecting “Yes,
allow access even if QuickBooks is not running.”
> If the user selects unattended mode authorization, and if there is more than one user
(not just the administrative user) then the “login as” dropdown is visible and
enabled, presenting the user with a list of login IDs currently able to log in to that
company file.
The checkbox at the bottom of the authorization dialog, if checked, authorizes your
application to access sensitive personal data. However. the currently logged in user is
still restricted by the permissions set up in QuickBooks, regardless of whether or not
the checkbox is checked.
How the AuthPreferences Object Works
37
(c) 2013 Intuit Inc. All rights reserved.
Figure 4-1 Default Authorization Form
How the AuthPreferences Object Works
Starting with QuickBooks 2005, you can use the AuthPreferences object to inform the user
via the QuickBooks authorization dialog itself, about the level of access that your
application requires.
AuthPreferences allows you to let the user know immediately what your application
requires, simplifies the users choices by displaying only those authorization selections in
the dialog that are relevant to your application, and eliminates unnecessary work by the
user, such as navigating through multiple QuickBooks menus and dialogs. Notice that the
user must be logged in as the QuickBooks administrative user in order to authorize these
preferences.
38
Chapter 4: Specifying Authorization Preferences
(c) 2013 Intuit Inc. All rights reserved.
How to Use the AuthPreferences Functionality
The AuthPreferences object is a property of the QB XML request processor. We’ll show
you how to instantiate this and set it in a code sample in just a moment. But first, let’s take
a look at what you can do with the object and its methods.
The AuthPreferences object has three write methods, which must be invoked BEFORE the
call to BeginSession:
PutIsReadOnly. This causes the QuickBooks authorization dialog to display text
informing the user that its access will be read-only.
PutUnattendedModePref. This has different effects depending on the parameter
specified:
> umpRequired, which causes the QuickBooks authorization dialog to display only
the selection choices of “No” (no authorization) or “Yes, allow access even if
QuickBooks is not running” (authorize unattended mode). In other words, you use
this value to tell the user you need to run in unattended mode if you’re going to run
at all.
> umpOptional, which causes the QuickBooks authorization dialog to display its
default selections and let the user pick. You would only use this setting if your
application didn’t need unattended mode.
PutPersonalDataPref which has different effects depending on the parameter specified:
> pdpRequired, which causes the QuickBooks authorization dialog to not display the
personal information checkbox for user selection, and instead display a warning
that the application needs to access personal data such as SSN or credit card
information.
> pdpOptional, which causes the QuickBooks authorization dialog to display a
checkbox for user selection asking whether the user wants to allow the application
to access personal data such as SSN or credit card information. That is, your
application doesn’t absolutely require the access, although it could use data from
such access if it were granted.
> pdpNotNeeded, which causes the QuickBooks authorization dialog to not display
the personal information checkbox for user selection, and instead display an
informational message that the application will NOT access personal data such as
SSN or credit card information. That is, if your application doesn’t use any of that
data, the nice thing to do is let the user know up front and not prompt the user for
access you don’t need.
There are three Get methods (GetIsReadOnly, GetUnattendedModePref, and
GetPersonalDataPref) that return the authorization preferences currently in effect, but these
methods can only be invoked AFTER the call to BeginSession.
How the AuthPreferences Object Works
39
(c) 2013 Intuit Inc. All rights reserved.
I
MPORTANT
Your code implementing the new authorization capabilities will
not set preferences on QB versions earlier than QuickBooks
2005. However, no errors will occur if you use
AuthPreferences and its related methods, so you can safely
write code and expect no failures. However, you may want to
do a check, using the AuthPreferences method
WasAuthPreferencesObeyed to determine whether the
QuickBooks version supports AuthPreferences or not.
Code Sample: AuthPreferences via the Request Processor
The following snippet shows the use of the AuthPreference object to set preferences in
AuthPreferences. This sample uses the request processor directly (QBXMLRP2Lib). We’ll
give a short QBFC snippet shortly.
Notice that this does not set QuickBooks authorization preferences (only the QuickBooks
administrator can do that) but it sets up AuthPreferences so that QuickBooks will display
the authorization dialogs that correspond to the preferences your applications has specified.
If (frmSDKTestPlus3.AuthPrefsDirty) Then
Dim prefs As QBXMLRP2Lib.AuthPreferences
Set prefs = qbXMLCOM.AuthPreferences
If (frmSDKTestPlus3.Unattended.Value) Then
prefs.PutUnattendedModePref umpRequired
Else
prefs.PutUnattendedModePref umpOptional
End If
prefs.PutIsReadOnly frmSDKTestPlus3.ReadOnly.Value
If (frmSDKTestPlus3.pdRequired.Value) Then
prefs.PutPersonalDataPref pdpRequired
ElseIf (frmSDKTestPlus3.pdNotNeeded.Value) Then
prefs.PutPersonalDataPref pdpNotNeeded
Else
prefs.PutPersonalDataPref pdpOptional
End If
End If
In this snippet, the parent form frmSDKTestPlus3 is checked to see whether any
preferences have been changed. If any changes were made, the various components in the
form are checked for new user selections and those choices are then set in the
AuthPreferences object.
N
OTE
This snippet is for a sandbox type application that allows for a
toggling of the AuthPreferences requirements for test
purposes. Your application probably would not do this, but
would instead simply set the preferences in the way your
application requires.
40
Chapter 4: Specifying Authorization Preferences
(c) 2013 Intuit Inc. All rights reserved.
Code Sample: AuthPreferences via QBFC
The following snippet shows the setting of the AuthPreferences object in QBFC.
Dim SessionManager As QBSessionManager
Set SessionManager = New QBSessionManager
Dim MyAuthPrefs As IAuthPreferences
Set MyAuthPrefs = SessionManager.QBAuthPreferences
MyAuthPrefs.PutIsReadOnly
SessionManager.OpenConnection2 appID, appleName, ctLocalQBD
SessionManager.BeginSession "", omDontCare
What Happens as a Result of the AuthPreference Settings?
The next time the application connects to QuickBooks after any change to AuthPreferences,
the proper authorization dialog is displayed to the user. For example, if you set the
AuthPreferences such that access to personal data was required, the ability to run in
unattended mode was required, and you specified read-only access, then the authorization
dialog shown in Figure 4-2 on page 41 would be displayed to the user.
How the AuthPreferences Object Works
41
(c) 2013 Intuit Inc. All rights reserved.
Figure 4-2 Authorization Dialog for Read-Only, Personal Data, and Unattended Mode
If the user chooses to authorize, QuickBooks pops up the confirmation message shown in
Figure 4-3 on page 42.
42
Chapter 4: Specifying Authorization Preferences
(c) 2013 Intuit Inc. All rights reserved.
Figure 4-3 Authorization Confirmation
Notice that the confirmation messages lists all of the authorized access preferences.
Setting Authorization Preferences Within QuickBooks
If your application does not use the AuthPreferences object and methods to help the
QuickBooks administrator set authorizations properly, the QuickBooks administrator may
need to set additional authorization preferences or change existing authorization
preferences for integrated applications within QuickBooks by clicking on the Integrated
Applications icon in the QuickBooks Preferences window, then selecting Company
Preferences. Preferences that can be set by the administrator include the following:
Disallowing or changing application access
Enabling certificate date checking
Listing authorized applications
Granting auto-login privileges and assigning the name of the auto-login user
Allowing application access to personal company data
Figure 4-4 on page 43 shows the window presented to the administrator for managing
integrated applications and their access to QuickBooks.
How the AuthPreferences Object Works
43
(c) 2013 Intuit Inc. All rights reserved.
Figure 4-4 Integrated Application Preferences
44
Chapter 4: Specifying Authorization Preferences
(c) 2013 Intuit Inc. All rights reserved.
Using Java with QB SDK
45
(c) 2013 Intuit Inc. All rights reserved.
C
HAPTER
5 1
A
CCESSING
D
ESKTOP
Q
UICK
B
OOKS
E
DITIONS
1
This chapter assumes that you have read about the basic communication model used for
accessing desktop QuickBooks editions, in Chapter 3, “The Communication Model and
Ways of Implementing It.”
Accessing desktop QuickBooks editions is pretty straightforward whether you use the
request processor or the QBFC convenience library. At bare minimum, there are only three
lines of code for the access: OpenConnection2, BeginSession, and ProcessRequest (or
DoRequests if you use QBFC). And two lines of housekeeping code when you’re finished:
EndSession and CloseConnection. We’ll cover that simple case in this chapter.
But there are a couple of other things you may want to know about as well. Such as
Single user mode vs multi-user mode.
Auto-login mode, which allows your application to run without an interactive user.
How to specify which QB editions your application supports and which ones it doesn’t.
How to tell your user which access rights your application needs in order to work. (This
isn’t covered here, but it is covered in Chapter 4, “Specifying Authorization
Preferences,”)
These topics are covered in this chapter.
Using Java with QB SDK
If you want to use Java with the QB SDK, you need to use a Java to COM bridge, for
example the Jacob bridge product. For more information, search the web, and take a look at
the blog Using the QuickBooks SDK via JACOB Java-Com Bridge.from Theoden’s Coding
Tips.
The programming samples included with the SDK also include a sample implementation
using a Java to COM bridge.
A Note About the Request Processor
The qbXML Request Processor is the gatekeeper between your application and
QuickBooks. The Request Processor implements the COM interface that allows your
application to establish a connection to QuickBooks and set up a working session for a
particular QuickBooks company file. Because it straddles the process boundary with
QuickBooks, the Request Processor is available even when QuickBooks is not running or a
working session for a specific company file has not yet been established.
46
Chapter 5: Accessing Desktop QuickBooks Editions
(c) 2013 Intuit Inc. All rights reserved.
N
OTE
The Request Processor supplies an API that allows event
subscriptions without requiring a QuickBooks session. The
subscriptions go into effect the next time the company file is
opened, or when QuickBooks is next started. (For more
information, Chapter 14, “Event Notification.”)
How to Access QuickBooks
To access QuickBooks, your application needs to do this:
1. Open a connection to QuickBooks.
2. Start a session for working on a specific QuickBooks company file.
3. Send whatever requests you want to do something in QuickBooks.
4. When you’re done or before your application exits, end the session.
5. Then close the connection.
VB Code Snippets for Access if You Use qbXML
If you use qbXML, you need to use QBXMLRP2Lib, however your language does this,
such as by an import statement, or by specifying it in your project reference, Then, here’s
what the above steps 1 through 5 look like in code:
Dim MyQbXMLRP2 As QBXMLRP2Lib.RequestProcessor2
Set MyQbXMLRP2 = New QBXMLRP2Lib.RequestProcessor2
MyQbXMLRP2.OpenConnection2 "", "My Sample App", localQBD
Dim ticket As String
ticket = MyQbXMLRP2.BeginSession("", QBXMLRP2Lib.qbFileOpenDoNotCare)
‘ The variable “xml” here is a fully formed message request set:
‘ we left out that part to keep this as simple as possible
Dim sendXMLtoQB As String
sendXMLtoQB = MyQbXMLRP2.ProcessRequest(ticket, xml)
MyQbXMLRP2.EndSession ticket
MyQbXMLRP2.CloseConnection
Some Commentary on the Code Snippet
The OpenConnection2 call is interesting partly because of the third parameter, which we’ve
shown as localQBD. Other possibilities could be to use localQBDLaunchUI, which would
start QuickBooks in interactive mode.
The first parameter to BeginSession is the full path to the QuickBooks company file you
want to use. We show an empty string here because we are using whatever file is currently
open in QuickBooks. The second parameter is the file mode. This is where you specify
How to Access QuickBooks
47
(c) 2013 Intuit Inc. All rights reserved.
whether you’re accessing the company file in single user mode or multi-user mode, which
we’ll describe shortly. We specified the file mode of “do not care” which allows for either
multi-user or single-user mode, depending on whether the file is currently opened or not.
If the BeginSession call succeeds, you get back a session ticket which you need to supply as
a parameter for the various calls into the request processor, such as ProcessRequest and
CloseConnection.
VB Code Snippets for Access if You Use QBFC
If you use QBFC, you need to use the QBFC DLL however your language does this, such
as by an import statement, or by specifying it in your project reference. Then, here’s how
you access QuickBooks:
Dim MySessionManager As QBSessionManager
Set MySessionManager = New QBSessionManager
MySessionManager.OpenConnection2 “ “, “My Sample App”, ctLocalQBD
MySessionManager.BeginSession "", omDontCare
‘ “MyMsgRequestSet” here is a fully formed message request set:
‘ we left out that part to keep this as simple as possible
Dim MyDataExt_resp As IMsgSetResponse
Set MyDataExt_resp = MySessionManager.DoRequests(MyMsgRequestSet)
MySessionManager.EndSession
MySessionManager.CloseConnection
Some Commentary on the QBFC Code Snippet
The same commentary provided for the qbXML snippet above applies here. One interesting
difference you’ll notice is the absence of the session ticket when you use QBFC. That is
managed automatically by QBFC.
What Happens in the Call to BeginSession?
When your application makes a BeginSession call to QuickBooks, the Request Processor
checks to ensure that the following are true:
The current QuickBooks supports the SDK (QuickBooks Version 10 or greater).
The version of QuickBooks and the version of the company data file, if one was
specified, match one another. (If NULL or an empty string was specified, this task is
skipped.)
The file access mode specified by your application and the mode in which the company
data file is currently open are compatible.
The Request Processor is able to successfully launch the located, required version of
QuickBooks. If it cannot start QuickBooks, any number of problems might exist; for
48
Chapter 5: Accessing Desktop QuickBooks Editions
(c) 2013 Intuit Inc. All rights reserved.
instance, QuickBooks might not have been correctly installed (perhaps only partially
installed) or there might be some other problem with QuickBooks.
If the application attempts auto login and if this permission has not been granted by the
QuickBooks administrative user, QuickBooks returns an error code to your application
in the BeginSession call.
If any of these tasks fail, your application will not be able to complete the login process or
connect to QuickBooks. However, in the event of failure, your application will have the
opportunity to present the user with direction on how to resolve the problem. For related
information, see Chapter 37, “Making Your Application Robust.”
Troubleshooting Errors in the BeginSession Call
For help with these and other errors, check out the IPP Developer website for more
information and a useful diagnostic tool called qbSDKDiag.
The qbSDKDiag tool turns on the maximum logging capability of QuickBooks and the
SDK, gathers important registry data about QuickBooks, starts QuickBooks, and attempts
to establish a connection with QuickBooks in interactive mode using QBXMLRP and
QBXMLRP2.
Having successfully connected in interactive mode, the user is then asked to enable
unattended access for the diagnostic tool and to close QuickBooks. The diagnostic tool then
attempts to connect with both QBXMLRP and QBXMLRP2 using unattended mode.
Finally, all the log files (qbsdklog.txt, qbinstancefinder.log, qbwin.log, and the diagnostic
log itself) are zipped up and e-mailed to the address supplied in the diagnostic application,
currently to IPP support.
Multiple Sessions versus a Single Session
A session gives your application access to QuickBooks data belonging to one company file.
Depending on whether your typical user deals with a single company file or multiple
company files in QuickBooks, you will have one or multiple sessions within a connection.
If your user typically deals with only one company’s data, you will probably open a
connection, begin a session, process multiple requests, and then end the session, as shown
in Figure 5-1 on page 49.
Using AuthFlags to Specify Support for QuickBooks Editions
49
(c) 2013 Intuit Inc. All rights reserved.
Figure 5-1 A single session within one connection.
If the user of your application often deals with multiple companies as, for example, a
professional accountant who manages finances for multiple organizations, your application
will probably open a connection and then begin and end several sessions on different
company files before finally closing the connection, as shown in Figure 5-2 on page 49.
Sessions do not overlap.
Figure 5-2 Multiple sessions within one connection.
In most cases, an application will send multiple requests to QuickBooks in a single session.
The processing is synchronous: your application must wait until one ProcessRequest call
completes execution and returns with the qbXML response data sent from QuickBooks
before issuing the next ProcessRequest call.
Using AuthFlags to Specify Support for QuickBooks Editions
Prior to QuickBooks 2006, the various editions of QuickBooks provided virtually the same
support for the various SDK requests. However, beginning with QuickBooks 2006, a new
edition called QuickBooks Simple Start provides support for a subset of SDK requests.
Consequently, to prevent applications from behaving unexpectedly while running on
QuickBooks Simple Start, the request processor now checks the AuthFlags property during
the call to BeginSession to determine whether your application supports QuickBooks
Simple Start.
50
Chapter 5: Accessing Desktop QuickBooks Editions
(c) 2013 Intuit Inc. All rights reserved.
For existing applications that aren’t designed for QuickBooks Simple Start, no code
changes are necessary, because by default, AuthFlags is set to support QuickBooks Pro,
Premier, and Enterprise.
However, if you are writing an application that does support QuickBooks Simple Start, you
need to explicitly set AuthFlags to indicate your applications support of that edition.
Otherwise, if your application attempts to begin a session with QuickBooks Simple Start,
you will get an error when you call BeginSession.
Setting AuthFlags to Specify Support for a QuickBooks Edition
To specify which editions your application supports, you invoke the PutAuthFlags method
of the AuthPreferences object before you call BeginSession. The basic call sequence is
straightforward:
1. Instantiate the request processor
2. Instantiate the AuthPreferences object.
3. Construct the desired AuthFlags value
4. Invoke the PutAuthFlags method on AuthPreferences using the AuthFlags value you
just constructed.
The tricky part in all this is the constructing of the AuthFlags value. You need to know a
few facts other than its data type, which by the way, is an integer value (a Long in VB).
Internally, the editions are represented by the following enumerated values:
The ForceAuthDialog value is included as a convenience: if you including it when you
construct your AuthFlags, you cause QuickBooks to display the authorization dialog again
for the user to change the permissions they may have already set for your application.
To specify support for each edition, you simply OR the values for each edition you are
supporting. In the following VB snippet, we specify support for all of the QuickBooks
editions and force the display of the auth dialog to boot.
Dim authFlags As Long
authFlags = 0
authFlags = authFlags Or &H8&
authFlags = authFlags Or &H4&
authFlags = authFlags Or &H2&
authFlags = authFlags Or &H1&
authFlags = authFlags Or &H80000000
When we finish constructing the AuthFlags, we set it as follows:
Behavior Needed Value
SupportQBSimpleStart 0x1
SupportQBPro 0x2
SupportQBPremier 0x4
SupportQBEnterprise 0x8
ForceAuthDialog 0x80000000
More Information about Login Modes
51
(c) 2013 Intuit Inc. All rights reserved.
Dim qbXMLCOM As QBXMLRP2Lib.RequestProcessor2
Dim prefs As QBXMLRP2Lib.AuthPreferences
Set prefs = qbXMLCOM.AuthPreferences
prefs.PutAuthFlags (authFlags)
The SDK sample program SDKTestPlus3 provides an example of constructing the
AuthFlags a bit more selectively, ORring only those editions you choose through UI
components.
I
MPORTANT
If you start your application by invoking BeginSession with
LocalQBLaunchUI AND you have SimpleStart, but do not set
the authFlags to specify Simple Start support, SimpleStart will
launch with the company file specified, and you’ll get an error
regarding the fact that your application doesn’t support
SimpleStart. Once Simple Start is launched in this scenario,
your application won’t have SDK access to Simple Start.
More Information about Login Modes
Integrated applications can log in to QuickBooks in one of two modes:
In interactive mode, QuickBooks runs in the foreground, and its user interface is
displayed. The user logs in to QuickBooks and opens a company file. Subsequently,
your application is launched and “attaches” to the company file that has already been
opened. The user can interact directly with your application and with QuickBooks.
In unattended mode (auto-login), QuickBooks runs in the background, and its user
interface may or may not be displayed, depending on the connection type you specify
in the call to OpenConnection2. The ctLocalQBD type either uses the local
QuickBooks currently running or, if not running, launches QB in unattended mode
(without UI, thus non interactively). If QuickBooks is not running, the
ctLocalQBDLaunchUI type launches it in interactive mode (the UI is displayed). If
your connection type doesn’t specify the launching of the QuickBooks UI, then
QuickBooks features are fully available to your application but not to the user. Notice
that whenever QuickBooks is started by the application rather than by the small-
business owner, it is in auto-login mode.
N
OTE
When an application accesses a company file that was opened
by a user from the QuickBooks user interface, the application
has the same privileges as that logged-in user. In some cases,
the user can impose further restrictions via the preferences
for the application. (In QuickBooks, bring up preferences by
selecting Edit->Preferences->Integrated Applications-
>Company Preferences->Properties.)
52
Chapter 5: Accessing Desktop QuickBooks Editions
(c) 2013 Intuit Inc. All rights reserved.
Setting Up Auto-Login
You use the AuthPreferences object to inform the user that auto-login (unattended) mode is
required (Chapter 4, “Specifying Authorization Preferences.”). The proper dialog with the
auto-login prompt will be presented to the user for confirmation. If the user chooses not to
authorize your applications requirements, then your application will not be allowed to
access the QuickBooks company. Notice that this is “all or nothing.” Either your
application gets all of its requirements or it is refused access to QuickBooks.
Alternatively, you can set up auto-login from within QuickBooks. Using this method, the
QuickBooks administrator sets the user name under which your application will run in
QuickBooks under Company Preferences, Properties, Access Rights, a window that is
accessible only to QuickBooks administrators (see Figure 5-3 on page 52).
Figure 5-3 QuickBooks window for allowing auto-login by an integrated application
If you don’t use AuthPreferences, be sure to tell your user that the QuickBooks
administrator must give your application the necessary authorizations.
What Happens if the Administrative User Deletes the Auto-Login User?
If an application is set up for auto-login, then a warning message is displayed to the
administrative user when that user attempts to delete. The message indicates that the user to
be deleted is used by an integrated application.
Limitations on Accessing Company Files
53
(c) 2013 Intuit Inc. All rights reserved.
I
MPORTANT
If an application starts QuickBooks in auto-login mode, any
subsequent applications authorized for auto-login will have
the privileges of the first application during that session. The
first auto-login application sets the user for any subsequent
applications during the session. This is the user that is the
“active” user for all applications until all of the applications
end their sessions and QuickBooks exits.
Only One Auto-Login User per Application
Regardless of whether single-user or multi-user mode is specified for a given session, there
can be only one auto-login active during that session. Figure 5-4 on page 53 illustrates a
multi-user session, with four different users accessing the same company file. Because Joe
is designated as an auto-login user on System 4, no other users can log in automatically
until “Joe” (the auto-user) logs out. When multiple instances of an integrated application
are running on different systems and accessing the same company file, as shown in Figure
5-4 on page 53, each user must have a different name.
Figure 5-4 Multiple users accessing the same company file
Limitations on Accessing Company Files
Only one company file at a time can be accessed by integrated applications on any given
machine running QuickBooks. The company file that must be used by integrated
applications is the one currently opened by the user from the QuickBooks user interface, or
the company file that is currently open by an application that started QuickBooks in auto-
login mode.
54
Chapter 5: Accessing Desktop QuickBooks Editions
(c) 2013 Intuit Inc. All rights reserved.
Allowing Application Access to Personal Data
The Access Rights window shown in Figure 5-3 on page 52 also includes a checkbox that
allows your application access to personal data in the company file. Personal data can
include:
Employee social security numbers
Any field directly related to an employee’s salary or wages
Anything related to credit card numbers or bank account numbers
Be sure to instruct the QuickBooks administrator to check this box if your application
requires access to personal employee or customer data. (Alternatively, your application can
require access to personal data using the AuthPreferences object, which is available for
QuickBooks 2005 and later.)
Single-User vs. Multi-User Mode
During a QuickBooks session, your application specifies whether to open the company data
file in single-user or multi-user mode. It is important to balance your needs with the overall
implications of selecting one mode over the other. Table 5-1 on page 55 summarizes the
different combinations. Another interesting case is that even when the integrated
application opens a company file in multi-user mode, other integrated applications can
access the company file, but no actual users can access that company file on the same
system.
I
MPORTANT
If QuickBooks 2007 and later is running non hosted, SDK
applications starting QuickBooks in DoNotCare mode will open
QuickBooks in single-user mode.
Microsoft Windows Vista & Windows 7 and UAC
55
(c) 2013 Intuit Inc. All rights reserved.
Table 5-1 QuickBooks company file login mode access conditions and rIghts
Trade-offs of Using Single-User Mode
Here are some of the advantages and disadvantages of using single-user mode.
Advantages:
Certain QuickBooks features require that a user operate in single-user mode. For
instance, a company file must be open in single-user mode for you to delete any of its
list items.
Locking and opening protection. If the company file is not already opened by another
QuickBooks-integrated application, your application will be able to open it with
exclusive access (locking out other applications), gaining improved performance.
Disadvantages:
Lockout. If your application attempts to open a company file in single-user mode and
that company file is already open in multi-user mode, your application will not be able
to access the company data file. Your application will be locked out. (If your
application specifies multi-user mode, it can share access to the company file.)
Microsoft Windows Vista & Windows 7 and UAC
On the released version of Windows Vista & Win 7, applications built with any version of
the QuickBooks SDK should work correctly with QuickBooks 2011 R7 and newer (and
QuickBooks Enterprise Solutions 11.0 R7 and newer), the latest available update release,
with the following additions:
Who started QuickBooks Mode Who may obtain access
Integrated Application Single-user All other integrated applications
= access
Integrated Application Multi-user QB users on same machine =
no access
All other integrated applications
= access
QB users on other machines =
access
QuickBooks User Single-user QB user already logged in
Only one integrated application
= access
QuickBooks User Multi-user QB users = access
Integrated applications = access
56
Chapter 5: Accessing Desktop QuickBooks Editions
(c) 2013 Intuit Inc. All rights reserved.
With User Access Control (UAC) ON - Both QuickBooks and the application accessing it
through the SDK can run with elevated user permissions (Run as Administrator) under
following setup for a successful SDK connection.
a. QuickBooks running as Administrator in AND Application accessing QuickBooks
through SDK running as Administrator.
b. QuickBooks in Unattended mode AND Application accessing QuickBooks through
SDK running as Administrator.
The following limitations are still in place
With UAC ON, either one of these – QuickBooks or SDK application cannot be run in
Elevated access.
a. Unsuccessful connection when QuickBooks in Standard user permission and SDK
Application running as Administrator.
b. Unsuccessful connection when QuickBooks running as Administrator and SDK
Application in Standard user permission.
Table 5-2 Use case for UAC
Cases UAC
Mode Of
Connection Client QuickBooks
SDK
Connection in
2011 R7
a. UAC ON Attended Elevated Elevated Successful
b. UAC On Unattended Eleveated Not Running Successful
Limitations:
a.
UAC ON Attended Standard Elevated Unsuccessful
b. UAC ON Attended Elevated Standard Unsuccessful
A Few Notes About Using QBFC
57
(c) 2013 Intuit Inc. All rights reserved.
C
HAPTER
6 1
B
UILDING
R
EQUESTS
I
N
QBFC
AND
IN
QB
XML 1
This chapter describes how to build requests using the QBFC library or the request
processor directly, via qbXML. Because the request processor API method requires you to
build valid qbXML request strings and parse the returned qbXML responses, this chapter
shows the use of Microsoft’s XML Services 4.0 DOM to build and parse the XML using
DOM documents.
A Few Notes About Using QBFC
The QBFC library provides a convenience layer that allows you to construct requests using
the familiar object and object property paradigm. You will notice that the convenience layer
is a thin layer, so consequently there are a lot of objects to contend with in QBFC. In fact,
each request is a separate object, and each request object has its own unique sub objects, for
example the line item add object for SalesOrders is different than the line item add object
for SalesReceipts.
Fortunately, the abundance of objects is not as daunting as it might seem. All of the
requests are built in the same way and in the same order, and the line items are appended to
their parent object in the same way as well.
N
OTE
If your development environment and language supports
Intellisense, a list of the message set’s Append methods are
available from within your environment. You could also use
the Visual Studio Object Browser to look up the Append
methods.
Alternatively, you can look up the request name in the OSR and prefix that
name with Append and suffix it with Rq. Also, the top level object Tag
name in the OSR for each request entry is the name of the object that is
returned by the message sets corresponding AppendRequest method.
Building a Request using QBFC
In QBFC, you build a message set object and fill it with the requests you want to send to
QuickBooks. You use the QBSessionManager object to do the building and the sending.
58
Chapter 6: Building Requests In QBFC and in qbXML
(c) 2013 Intuit Inc. All rights reserved.
I
MPORTANT
You’ll notice there is no built-in way to get/set RequestID in
QBFC. You don’t need to manage RequestID when you use
QBFC because QBFC automatically assigns requestIDs to
requests within the message request set, from 0 to N. QBFC
automatically returns the responses in the ResponseList in the
exactìthe order of the requests.
What You Need to Do in QBFC
The followng general process for building requests is illustrated in Listing 6-1.
1. Instantiate the QB SessionManager object.
2. Create the request message set object (SessionManager.CreateMsgSetRequest).
3. Set any desired message set-level attributes in that message set object.
4. Append the desired request objects to the message set object.
5. Set all required or desired field values (see OSR) in that request object.
6. If the request contains line items, append the appropriate line item add object to the
request and set its field values.
7. If you want to add more requests, append the desired request objects to the message set
and set its values as described above.
8. Open a connection to QuickBooks.
9. Begin the session with the specified QuickBooks Company.
10. Invoke DoRequests to send the requests to QuickBooks.
11. Process the response.
12. If you’re done, end the session and close the connection.
Notice that the open connection and begin session calls are shown after the request is
constructed. This is not required. You can perform the open connection and begin session
calls at any time before the call to DoRequests. We made these calls at the end mainly to
point out that you don’t need to be connected to QuickBooks in order to construct requests.
Sample: Building a SalesOrder Using QBFC
Listing 6-1 shows an example in VB that constructs a SalesOrder request with two line
items and sends it to QuickBooks.
______ Listing 6-1 Building a SalesOrderAdd Request
Dim SessionManager As QBSessionManager
Set SessionManager = New QBSessionManager
Building a Request using QBFC
59
(c) 2013 Intuit Inc. All rights reserved.
‘ We’re going to use US QuickBooks and the 6.0 spec
Dim SalesOrderSet As IMsgSetRequest
Set SalesOrderSet = SessionManager.CreateMsgSetRequest("US", 6, 0)
‘ Need a separate Append* for each request in the MsgSetRequest object
‘ First set properties in the main body of the sales order
Dim salesOrder As ISalesOrderAdd
Set salesOrder = SalesOrderSet.AppendSalesOrderAddRq
salesOrder.CustomerRef.FullName.setValue "John Hamilton"
salesOrder.RefNumber.setValue "121345"
‘ Now add the line items. Every transaction with line items will look very similar to this
Dim SOLineItemAdder As ISalesOrderLineAdd
Set SOLineItemAdder = salesOrder.ORSalesOrderLineAddList.Append.salesOrderLineAdd
SOLineItemAdder.ItemRef.FullName.setValue "fee"
SOLineItemAdder.Quantity.setValue 3
SOLineItemAdder.Other1.setValue "gold"
‘ Add another line item. Notice our re-use of the SOLineItemAdder variable
Set SOLineItemAdder = salesOrder.ORSalesOrderLineAddList.Append.salesOrderLineAdd
SOLineItemAdder.ItemRef.FullName.setValue "fee"
SOLineItemAdder.Quantity.setValue 5
SOLineItemAdder.Other1.setValue "silver"
‘ OK, we’re done, send this to QB; for grins show results in a message box
‘ We close everything down when done for illustration only: you would keep the session and
‘ connection open if you were going to send more requests
SessionManager.OpenConnection2 appID, appName, ctLocalQBD
‘ Let’s use whatever company file happens to be open now
SessionManager.BeginSession "", omDontCare
Dim SOAddResp As IMsgSetResponse
Set SOAddResp = SessionManager.DoRequests(SalesOrderSet)
MsgBox SOAddResp.ToXMLString
SessionManager.EndSession
SessionManager.CloseConnection
Set SessionManager = Nothing
The Importance of the CreateMsgSetRequest Call
When you create the message set object, you need to specify the qbXML spec version that
this message set supports. The sample above creates a message set that supports version 6.0
of the qbXML specification. The purpose of this is to make sure that the currently installed
QBFC library and request processor can support the type of requests your application is
going to make. (In our example, we could have used 2.1, since that was the spec version
that first supported SalesOrderAdd.)
60
Chapter 6: Building Requests In QBFC and in qbXML
(c) 2013 Intuit Inc. All rights reserved.
Background Details About the MsgSetRequest Object
For the visually inclined, Figure 6-1 represents the message set request object.
Figure 6-1 The Request Message Set Object
You need to be aware of the request message set methods and properties that are available
for your use. The various Append methods are used to add request objects of a specific type
to the message set. Each Append method call returns a corresponding request object that
must be filled with property values as desired.
The Attributes property is used to set message set-level attributes: currently continue
on error and stop on error are the supported attributes. We’ll describe this attribute later
in this chapter.
The ClearRequests method empties the message set once you’ve invoked DoRequests
and are otherwise finished with the original request. After you clear out the message set
object, you can fill it again with new requests that you want to send. It saves some
overhead.
The RequestList method returns the list (IRequestList) of request objects in the
message set. IRequestList has a count property and a GetAt (index) method to support
retrieval of requests from the list.
The ToXMLString method returns a complete and valid qbXML string that represents
the message set object and all its requests. This is useful for diagnostic purposes or if
you simply want to make sure you are building the objects as you expect.
The Verify method can be used before the call to DoRequests to make sure the
requests are fully formed (all required fields have been set) and valid. However, the
DoRequests method call also performs this checking automatically.
Building a Request using QBFC
61
(c) 2013 Intuit Inc. All rights reserved.
Another View of the Message Set Request Structure
Figure 6-2 on page 61 shows a more detailed view of the logical arrangement of the
individual requests in a request message set, along with some sample property values.
Figure 6-2 Request Message Set Structure
The figure shows a message set for a transaction containing two SalesOrderAdd requests.
Each SalesOrder usually has a separate line item for each item ordered. Notice that the line
item objects also have properties that need to be set in order to finish constructing the
request. There can be as many line item objects as you need.
62
Chapter 6: Building Requests In QBFC and in qbXML
(c) 2013 Intuit Inc. All rights reserved.
The basic message set structure shown in Figure 6-2 is the same for every request object
that has line items: these are usually transactions. If the object is a list object, which does
not contain line items, such as Customer, you don’t add any line item sub objects as shown
in the sample figure. Instead you simply set the object properties as shown in the top of the
figure.
Notice the OnError attribute setting of the message set. This specifies how errors in the
individual requests are handled. If you specify roeContinue, as the sample does, then the
failure of one request in the message set won’t prevent other requests from being processed.
If you specify roeStop, then an error in one request stops the processing of any succeeding
requests.
Building a qbXML Request
Building a qbXML request and sending it to QuickBooks is simply a matter of writing out a
valid qbXML string that contains the requests you want and then sending them to
QuickBooks. However, because building syntactically correct XML “by hand” is so tedious
and prone to error, we strongly recommend the use of technology that does all the tedious
stuff for you (angle brackets, start and end tags, and so on), so you can focus on including
those qbXML elements that you want.
What You Need to Do in qbXML using a DOM Document
Our samples show the use of Microsoft XML (MSXML) API DOMDocument, a
technology which is currently free from Microsoft. When you build the qbXML, you
should refer to the Onscreen Reference (OSR) for details on required request elements.
Figure 6-3 on page 62 shows the general steps in building a request using a DOM
document.
Figure 6-3 Building a qbXML Request
Building a qbXML Request
63
(c) 2013 Intuit Inc. All rights reserved.
The following VB code snippet shows the qbXML for adding a new customer, with just a
few of the available fields filled out, to keep things simple. Once the request is filled out,
our code snippet prepends the required header information and sends the completed XML
string to qbXML via the request processor.
' Build the request XML
Dim builder As New DOMDocument40
Dim QBXML As IXMLDOMNode
‘After the header tags, <QBXML> is always the first element tag,
‘followed by the message set <QBXMLMsgsRq>
Set QBXML = builder.createElement("QBXML")
builder.appendChild QBXML
Dim msgsRq As IXMLDOMElement
Set msgsRq = QBXML.appendChild(builder.createElement("QBXMLMsgsRq"))
‘Set attributes on the message set
msgsRq.setAttribute "onError", "continueOnError"
Dim CustomerAddRq As IXMLDOMElement
Dim CustomerAdd As IXMLDOMElement
Set CustomerAddRq =
msgsRq.appendChild(builder.createElement("CustomerAddRq"))
CustomerAddRq.setAttribute "requestID", "1"
Set CustomerAdd = CustomerAddRq.appendChild(builder.createElement
("CustomerAdd"))
Dim dataElement As IXMLDOMElement
If firstName <> "" Then
Set dataElement = CustomerAdd.appendChild(builder.createElement
("FirstName"))
dataElement.appendChild builder.createTextNode(firstName)
End If
If lastName <> "" Then
Set dataElement = CustomerAdd.appendChild(builder.createElement
("LastName"))
dataElement.appendChild builder.createTextNode(lastName)
End If
‘The request is built except for the headers: so build these and
‘append the request to them:
requestXML = "<?xml version=""" & "1.0" & """?>"
requestXML = requestXML + "<?qbxml version=""" & "6.0" & """?>" +
builder.xml
‘Start a QB session and send the request
Dim qbXMLRP As QBXMLRP2Lib.RequestProcessor2
Set qbXMLRP = New QBXMLRP2Lib.RequestProcessor2
Dim Ticket As String
qbXMLRP.OpenConnection2 cAppID, cAppName, localQBD
Ticket = qbXMLRP.BeginSession(qbfilename, qbFileOpenDoNotCare)
64
Chapter 6: Building Requests In QBFC and in qbXML
(c) 2013 Intuit Inc. All rights reserved.
responseXML = qbXMLRP.ProcessRequest(ticket, requestXML)
qbXMLRP.EndSession ticket
qbXMLRP.CloseConnection
Set qbXMLRP = Nothing
Processing a Response Using QBFC
65
(c) 2013 Intuit Inc. All rights reserved.
C
HAPTER
7 1
H
ANDLING
R
ESPONSES
U
SING
QBFC
OR
QB
XML 1
This chapter describes how to handle responses using the QBFC library or the request
processor API.
I
MPORTANT
You’ll notice there is no built-in way to get/set RequestID in
QBFC. You don’t need to manage RequestID when you use
QBFC because QBFC automatically assigns requestIDs to
requests within the message request set, from 0 to N. QBFC
automatically returns the responses in the ResponseList in the
exactìthe order of the requests.
Processing a Response Using QBFC
Processing responses using QBFC is somewhat like building requests, only in reverse.
When you invoke DoRequests to send the requests to QuickBooks, DoRequest returns an
IMsgSetResponse object. This object contains all of the response data, so you need to know
how to traverse this object and the other objects it contains.
I
MPORTANT
Not all invocations of DoRequest will result in a response with
StatusCode and StatusMessage. Certain failures will return
only an HRESULT indicating the nature of the failure.
Figure 7-1 shows the generalized method for getting response data.
66
Chapter 7: Handling Responses Using QBFC or qbXML
(c) 2013 Intuit Inc. All rights reserved.
Figure 7-1 Getting Response Data
Processing Responses: QBFC Sample Code
The following code snippet shows the response to an ItemInventoryAdd request. Because
this is not a query, the response will contain only the Ret object and not the Ret list, which
would have to be processed further.
N
OTE
In the sample, notice the response type. You can look up all
the response types in the Visual Studio object browser under
the ENResponseType or you can construct them from the
response name by prefixing the response name with rt, for
example, the type for an ItemInventoryAddRs response is
rtItemInventoryAddRs.
Also, the OSR is useful in looking up the Ret object and Ret list names for
each Response. The Ret or Ret list for the response is listed at the top of
the OSR entry for each response.
‘Send the request message and get the response message: then get the first
‘response message. This sample only expects one response
Dim responseMsgSet As IMsgSetResponse
Dim response As IResponse
Set responseMsgSet = sessionManager.DoRequests(requestMsgSet)
Set response = responseMsgSet.ResponseList.GetAt(0)
Processing a Response Using QBFC
67
(c) 2013 Intuit Inc. All rights reserved.
‘Make sure the response type is the expected ItemInventoryAddRs type
‘then get the expected IItemInventoryRet object data: we only want ListID
Dim itemInventoryListID As String
If (Not response. Is Nothing) Then
Dim responseType As Integer
responseType = response.Type.GetValue
Dim j As Integer
‘Notice that we make an implicit upcast here (supported in VB),
‘upcasting the detail to the itemInventoryRet type. In other languages,
‘you must do an explicit upcast, for example, in VB.Net:
‘itemInventoryRet = response.Detail as itemInventoryRet
If (responseType = rtItemInventoryAddRs) Then
Dim itemInventoryRet As IItemInventoryRet
Set itemInventoryRet = response.Detail
itemInventoryListID = itemInventoryRet.ListID.GetValue
End If
End If
The code snippet below shows how to get data from a query response, which does have a
Ret list of Ret objects.
‘Send the request message and get the response message: then get the first
‘response message. This sample only expects one response
Dim responseMsgSet As IMsgSetResponse
Dim response As IResponse
Set responseMsgSet = sessionManager.DoRequests(requestMsgSet)
Set response = responseMsgSet.ResponseList.GetAt(0)
'We’re expecting an ItemInventoryQuery response.
If (Not response.Detail Is Nothing) Then
Dim responseType As Integer
responseType = response.Type.GetValue
Dim j As Integer
‘Get the ret list
If (responseType = rtItemInventoryQueryRs) Then
Dim itemInventoryRetList As IItemInventoryRetList
Set itemInventoryRetList = response.Detail
Dim itemInventoryRet As IItemInventoryRet
ItemFlexGrid.Rows = (1 + itemInventoryRetList.Count)
68
Chapter 7: Handling Responses Using QBFC or qbXML
(c) 2013 Intuit Inc. All rights reserved.
‘load each ret object from the list into a separate row in the
‘grid control to display certain ret object fields
For j = 0 To itemInventoryRetList.Count - 1
Set itemInventoryRet = itemInventoryRetList.GetAt(j)
Set itemInventoryRet = itemInventoryRetList.GetAt(j)
If (Not itemInventoryRet.Desc1 Is Nothing) Then
ItemFlexGrid.Col = 0
ItemFlexGrid.Row = j + 1
ItemFlexGrid.Text = itemInventoryRet.ListID.GetValue
ItemFlexGrid.Col = 1
ItemFlexGrid.Text = itemInventoryRet.FullName.GetValue
ItemFlexGrid.Col = 2
ItemFlexGrid.Text = itemInventoryRet.SalesDesc.GetValue
ItemFlexGrid.Col = 3
ItemFlexGrid.Text = itemInventoryRet.QuantityOnHand.GetValue
End If
Next j
End If
End If
In the preceding code sample, an item inventory query is sent to get a list of inventory items
and display the list ID, fullname, description, and on hand quantity from each item in a VB
flex grid control. We just get the ret list, and in the same loop that we use to go through the
ret list, we also populate each row in the flex grid control.
Background Information: Understanding IMsgSetResponse
The IMsgSetResponse object is always returned unless DoRequest fails. IMsgSetResponse
contains a response list that has one or more response objects, as shown in Figure 7-2.
Processing a Response Using QBFC
69
(c) 2013 Intuit Inc. All rights reserved.
Figure 7-2 Response Message Set Structure
As shown in Figure 7-2, a response object that is a query response contains a Ret list object
that contains potentially multiple Ret objects. A response object that is not a query response
contains only one Ret object and no Ret list. This difference is crucial when it comes to
processing the response data. We’ll describe these in more detail shortly.
Also as shown in the figure, you’ll need to be aware of these response object methods:
The ResponseList method returns the IResponseList object containing the individual
response objects in the message set. IResponseList has a count property and a GetAt
(index) method to support retrieval of responses from the list.
The ToXMLString method returns a complete and valid qbXML string that represents
the response message set object and all its individual responses. This is useful if you
want to dump out the response message to see the contents either for diagnostic
purposes or if you want to make sure you are getting the data you expect.
Background Information II: IResponse
The data, that you are interested in is contained in the IResponse. How do you get the
IResponse from the response message set?
To get the individual responses contained in the response message set,
70
Chapter 7: Handling Responses Using QBFC or qbXML
(c) 2013 Intuit Inc. All rights reserved.
1. Invoke ResponseList on the response message object to get the IResponseList
2. Use the IResponseList Count and GetAt methods to get the individual IResponse
objects.
Ok, you have an IResponse, which is response data to one of the requests that was sent to
QuickBooks. How do you traverse IResponse to get the response data from it? This is a
little tricky, since the IResponse can be either an object or another list.
To show you what we mean, take a look at Figure 7-3:
Processing a Response Using QBFC
71
(c) 2013 Intuit Inc. All rights reserved.
Figure 7-3 The IResponse Object
As shown in the figure, an IResponse that is a query response has a Ret list object
containing one or more Ret objects. The retCount, iteratorID, and iteratorRemainingCount
properties are provided to support getting the individual Ret objects from the Ret list.
72
Chapter 7: Handling Responses Using QBFC or qbXML
(c) 2013 Intuit Inc. All rights reserved.
The IResponse that is not a query response has no ret list. It has only the single Ret object,
from which data can be extracted.
Useful IResponse Methods/Properties You’ll Need to Use
I
MPORTANT
Not all invocations of DoRequest will result in a response with
StatusCode and StatusMessage. Certain failures will return
only an HRESULT indicating the nature of the failure.
The IResponse object has these methods and properties:
The Detail method does different things depending on whether the response is a query
response or not. For a query response, the Detail method returns the Ret list, which can
be looped through to get the individual Ret objects. For non query responses, Detail
returns the Ret object itself.
Notice that each request has a corresponding Ret object, for example,
ItemInventoryAddRq has the response Ret object of IInventoryRet.
Notice also that CompanyQuery is a special request that is treated as a
non-query request and response
The iteratorID property returns the iterator ID, which is used only for query responses
whose originating request was set up to use iterators.
The iteratorRemainingCount property returns the number of objects remaining in the
iteration. This is used only for query responses whose originating request was set up to
use iterators..
The retCount property returns the number of Ret objects contained in the Ret list.It is
used only for query responses.
The StatusCode property returns the status code of the response. Every response has a
status code indicating success (the value zero) or a non zero code that indicating the
nature of the failure.
The StatusMessage property returns the a text description of the status code in the
response. Every response has a status message.
The StatusSeverity property returns the severity level of the error.
The Type property identifies the response type. This is useful if you want to make sure
the response you are processing is of the expected type. You can invoke GetValue to get
the type as an enumerated value, which is the easiest way to do a comparison with an
expected type. Alternatively, you can invoke GetAsString to get the string
representation of the type.
Processing a qbXML Response
The response XML string is returned from the ProcessRequests API call that sent the
original request set to QuickBooks. The suggested way to process that qbXML response
message set is to load it into a DOM document and walk its node list as shown in the
following pseudocode and Visual Basic code sample.
Processing a qbXML Response
73
(c) 2013 Intuit Inc. All rights reserved.
What You Need to Do to Process a Response in qbXML
Figure 7-4 on page 73 shows the general process of getting response data using DOM
documents.
Figure 7-4 Processing qbXML Responses
Processing a Response Message Set: Sample Code
The following code snippet shows how to load the response message set into the DOM
document and walk the node list for response data. Notice that there can be more than one
response in the message set to process.
Dim retStatusCode As String
Dim retStatusMessage As String
Dim retStatusSeverity As String
' Create xmlDoc Obj
Dim xmlDoc As New DOMDocument40
Dim objNodeList As IXMLDOMNodeList
' Node objects
Dim objChild As IXMLDOMNode
Dim custChildNode As IXMLDOMNode
Dim attrNamedNodeMap As IXMLDOMNamedNodeMap
Dim i As Integer
Dim ret As Boolean
Dim errorMsg As String
' Get CustomerAddRs nodes list
Set objNodeList = xmlDoc.getElementsByTagName("CustomerAddRs")
For i = 0 To (objNodeList.length - 1)
' Get the CustomerRetRs
Set attrNamedNodeMap = objNodeList.Item(i).Attributes
' Get the status Code, info and Severity
retStatusCode = attrNamedNodeMap.getNamedItem("statusCode").nodeValue
retStatusSeverity = attrNamedNodeMap.getNamedItem
("statusSeverity").nodeValue
retStatusMessage = attrNamedNodeMap.getNamedItem
("statusMessage").nodeValue
74
Chapter 7: Handling Responses Using QBFC or qbXML
(c) 2013 Intuit Inc. All rights reserved.
' Walk through the child nodes of CustomerAddRs node
For Each objChild In objNodeList.Item(i).childNodes
' Get the CustomerRet block
If objChild.nodeName = "CustomerRet" Then
' Get the elements in this block
For Each custChildNode In objChild.childNodes
If custChildNode.nodeName = "ListID" Then
resListID = custChildNode.Text
ElseIf custChildNode.nodeName = "Name" Then
resCustName = custChildNode.Text
ElseIf custChildNode.nodeName = "FullName" Then
resCustFullName = custChildNode.Text
End If
Next
End If ' End of customerRet
Next ' End of customerAddret
Next
75
(c) 2013 Intuit Inc. All rights reserved.
C
HAPTER
8 1
C
REATING
Q
UERIES
1
Query requests ask QuickBooks for data that meets specified criteria. Often, there are
multiple ways to obtain the same data from QuickBooks, but depending on the type of
query you send, the returned objects contain different elements and differing amounts of
related detail.
There are several basic types of query:
List query, which returns list objects.
Object-specific transaction query, which returns complete data from the specified
transactions.
Generic transaction query, which returns a common subset of data (common to all
transaction types) for the specified transactions.
Reports
This chapter describes list queries, object-specific queries, and the generic transaction
query. Reports are covered separately in due to their special characteristics.
When to Use a Query vs a Report
Although reports are covered in a separate chapter, it may be helpful to consider upfront
whether you need to use a simple query of the types described in this chapter or whether
you should really be using a report.
Whether you use a simple query request or a report request depends on exactly what data
you need and how you plan to use it. If you need a simple snapshot of one or more objects
then try a query request. If you need a more complete view, across multiple objects and
over a time period then use a report. Also, some collections of information are more simply
expressed in a report.
Different Ways of Using Queries to Get the Same Data
There are sometimes a number of ways to get at the same data. For example, suppose you
wanted to obtain customers with unpaid balances:
Suppose you want to write collection letters to the customers with unpaid balances.
This task requires that you have both the names and addresses of the customers. In this
case, you could use a CustomerQueryRq and specify a TotalBalance greater than zero.
The response would return a list of customer objects.
Suppose you want to create statements for the customers with unpaid balances. In this
case, you could use an InvoiceQueryRq and specify NotPaidOnly for PaidStatus.
76
Chapter 8: Creating Queries
(c) 2013 Intuit Inc. All rights reserved.
A third way to obtain this information is to issue a Collections Report, which is a type
of AgingReportQueryRq. This returns the data you’re seeking, but in report form rather
than in the form of a particular QuickBooks object.
Getting a Count of Query Objects
In some instances, you may want to get an approximate count of the objects that will be
returned in a particular query, for example if you want to allocate enough memory or break
down the returned data in manageable chunks. Queries have an attribute called metaData,
which can be set so that no objects are returned in the query, just an approximate count. The
reason the count is approximate is that other users can add or delete objects between the
time you query for the count and the time you query for the objects.
Filters
Filters enable you to specify selection criteria for the objects or categories of objects that
are returned by QuickBooks in response to a query. If multiple filters are specified, the
results are ANDed. In general, filters have two general purposes:
To obtain a set of objects that meet specified criteria
To limit the number of objects returned in a response to a manageable quantity
Filters can be grouped into two general categories: filters that operate on lists and filters
that operate on transactions.
N
OTE
This chapter presents filters conceptually and, therefore, not
always in the same order as they appear in the actual qbXML
request. Be sure to check out the exact order and syntax for
each request in the Onscreen Reference for your target
QuickBooks product and the API you are using.
Limiting the Number of Objects Returned
There are two ways to limit the data returned from a query. The best way is to use the
iterator feature, which is specific to queries. This feature is available only to desktop
editions QB 2006 and later using qbXML spec 5.0 and greater.
The second way is to use the IncludeRetElement feature, which is a feature common to
nearly all qbXML requests, not just queries.
Limiting the Number of Objects Returned
77
(c) 2013 Intuit Inc. All rights reserved.
Using Iterators to Walk Through Large Query Returns
The iterator attribute provided with most query types also allows you to break down query
results in smaller and more manageable chunks of data. An iterator results in responses that
contain only the specified number of objects. Iterators are only valid for the application that
starts them, and they are only valid for the current QuickBooks session. (Once the current
QuickBooks session ends, or QuickBooks is shut down, all the iterators go away.)
I
MPORTANT
Starting an iterator preloads the set of things that are going
to be returned to you and gives you the specified number
(MaxReturn) that you requested in each iteration. However,
the iterator DOES NOT remember all aspects of your query
(just the filters!). Accordingly, if you use other fields in the
query, such as IncludeRetElement, then you have to repeat
those in each continuation of the iterated query!
Starting an Iteration
How do iterators work? The iterator is created when a query contains the iterator attribute
set to Start, along with a MaxReturn value specifying how many records are to be returned
in each iteration. The response to that first query iteration contains, along with the response
data, an IteratorID value that uniquely identifies that iterator. This is important because you
can have many iterators active at the same time. The following example shows how to start
an iteration
<?xml version="1.0" ?>
<?qbxml version="5.0" ?>
<QBXML>
<QBXMLMsgsRq onError="stopOnError">
<CustomerQueryRq requestID="5001" iterator="Start">
<MaxReturned>10</MaxReturned>
<IncludeRetElement>ListID</IncludeRetElement>
</CustomerQueryRq>
</QBXMLMsgsRq>
</QBXML>
The response contains the returned objects, with the iteration-related information returned
in the response attributes, as shown in the following snippet:
<CustomerQueryRs requestID = "5001" statusCode = "0" statusSeverity =
"INFO" statusMessage = "..." iteratorRemainingCount = "50" iteratorID =
"{D7355385-A17B-4f5d-B34D-F34C79C3E6FC}">
In the query responses, notice the attribute called iteratorRemainingCount that contains the
number of objects left in the iteration. You must check for a value of 0 because that means
not only that there are no more objects, but more importantly, it means that the Iterator is
now removed from memory and therefore further attempts to access it will fail: its
78
Chapter 8: Creating Queries
(c) 2013 Intuit Inc. All rights reserved.
iteratorID is no longer valid. Other than checking for this remaining count value of 0, you
can use this iteratorRemainingCount value any way you want, for example, to change the
current MaxReturned settings.
I
MPORTANT
When the remainingCount value returned in the query
response contains a value of 0, this indicates that the
corresponding Iterator can no longer be used.
Continuing the Iteration
To continue a particular iteration, you simply issue the same query request again, but this
time with the iterator value now set to Continue, and the IteratorID field set to the
IteratorID value returned from the first query iteration. Remember that the iterator DOES
NOT remember all aspects of your query (just the filters!). Accordingly, if you use other
fields in the query, such as IncludeRetElement, then you have to repeat those in each
continuation of the iterated query.
A qbXML example is shown below:
<?xml version="1.0" ?>
<?qbxml version="5.0" ?>
<QBXML>
<QBXMLMsgsRq onError="stopOnError">
<CustomerQueryRq requestID="5001" iterator="Continue"
iteratorID="{D7355385-A17B-4f5d-B34D-F34C79C3E6FC}">
<MaxReturned>10</MaxReturned>
<IncludeRetElement>ListID</IncludeRetElement> </
CustomerQueryRq>
</QBXMLMsgsRq>
</QBXML>
Once a query has been issued with an iterator, subsequent iterations (i.e., queries using that
same iteratorID and the iterator attribute set to Continue) cannot change any filtering. The
only thing that can be changed during an iteration is the MaxReturned value.
Stopping the Iteration
At any point during an iteration, you can stop the iteration and destroy the iterator (freeing
up memory) by issuing the query request with the iterator attribute set to “Stop” and the
iteratorID set to the proper iterator ID. It is a good practice to do this if you want to stop an
iteration before it is complete, otherwise the iterator will continue to be held in memory
until the current QuickBook session ends, potentially occupying a large amount of memory.
(If your application crashes before cleaning up its iterators, the iterators it was using can be
removed from memory by stopping QuickBooks and starting it again.)
Limiting the Number of Objects Returned
79
(c) 2013 Intuit Inc. All rights reserved.
I
MPORTANT
If you exhaust the iteration, so that the last query shows an
iteratorRemainingCount value of 0, you need not and in fact
cannot issue the query with the iterator attribute set to
“Stop.” The iteratorID you would have to supply is no longer
valid.
Limiting Returned Data Using IncludeRetElement
I
MPORTANT
Although IncludeRetElement is mentioned here for queries, it
is designed for use with Add and Mod operations as well, to
limit response data to those data that you want.
You use the IncludeRetElement tag in the request to limit the data that will be returned in
the response. Inside this tag you specify the name of the top-level element or aggregate that
is to be returned in the response to the request. You cannot specify elements within an
aggregate, for example, you cannot specify a City within an Address: you must specify
Address and will get the entire address.
I
MPORTANT
You can specify multiple IncludeRetElement lines if you want
multiple aggregates or elements returned. Each aggregate or
element must be specified in a separate IncludeRetElement
line. The specified tag name is not parsed, so you must be
especially careful to supply a valid tag, properly cased,
because no error is returned in the status code if you specify
an invalid tag name.
The following sample customer query shows where you need to place the
IncludeRetElement tag:
<?xml version="1.0"?>
<?qbxml version="4.0"?>
<QBXML>
<QBXMLMsgsRq onError="continueOnError">
<CustomerQueryRq requestID="2">
<IncludeRetElement>FullName</IncludeRetElement>
</CustomerQueryRq>
</QBXMLMsgsRq>
</QBXML>
The following response shows what would be returned in the customer query listed above:
80
Chapter 8: Creating Queries
(c) 2013 Intuit Inc. All rights reserved.
<?xml version="1.0" ?>
<QBXML>
<QBXMLMsgsRs>
<CustomerQueryRs requestID="2" statusCode="0" statusSeverity="Info"
statusMessage="Status OK">
<CustomerRet>
<FullName>Abercrombie, Kristy</FullName>
</CustomerRet>
<CustomerRet>
<FullName>Abercrombie, Kristy:Family Room</FullName>
</CustomerRet>
......more customer names.......
</CustomerQueryRs>
</QBXMLMsgsRs>
</QBXML>
EmployeeQuery and IncludeRetElement
Notice that prior to QuickBooks 2005, an EmployeeQueryRq would return a permissions
error if the currently logged in QuickBooks user did not have “Payroll and Employees”
permission. This would occur even if you only needed data that was not restricted.
However, because of IncludeRetElement (new in SDK 4.0), the situation has changed
somewhat. You can use that new element to specify fields in the EmployeeRet object that
do not require “Payroll and Employees” permissions. Such a query would return the
unrestricted data (such as Name) from an EmployeeQueryRq even if the logged in user
lacks "Payroll and Employees” permissions.
Using MaxReturned
Most queries include the MaxReturned element, which is actually a delimiter that specifies
the maximum number of objects to return in each response. If your application deals with
large amounts of data, it is recommended that you use this delimiter to ensure acceptable
application performance.
If you’re using filters, the filters are applied first and then the MaxReturned value is applied
if needed. When you use MaxReturned, your application is responsible for keeping track of
the last object returned and specifying the start of the next search, as described in the
following paragraphs.
Basically, you’ll follow this technique:
1. 1. Issue a query (for example, a CustomerQueryRq request) with a MaxReturned
equal to a reasonable amount of data (for example, 100). This first query does not
include a From/To specification.
2. 2. For subsequent queries, issue the same type of query (here, a CustomerQueryRq
request) and specify the starting point for the next query. For example, if you are
dealing with an alphabetized list of names, you will use the
NameRangeFilter:FromName field and specify the last object that was returned in the
previous response. Do not specify the ToName field. (The value specified for
MaxReturned will determine the number of objects returned in the response.)
List Queries: Commonly Used Filters
81
(c) 2013 Intuit Inc. All rights reserved.
List Queries: Commonly Used Filters
List queries generally support the following types of filters:
ListID or FullName
Active status
Filtering by date and time modified
Matching criterion for names
Ranges for names
You can optionally ask that each returned object also contain the Data Extension values for
one or more Owner IDs.
ListID or FullName
List queries allow you to