QBSDK_ProGuide Pro Guide

sdk-guide

User Manual:

Open the PDF directly: View 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

Intuit QuickBooks

SDK

Programmer’s Guide

Version 13.0

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

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

ONTENTS

About This Manual

Who Should Read This Manual? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

What’s 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

What’s 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

What’s 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

Contents

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

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

Contents

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

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

Contents

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

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

Contents

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

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

Contents

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? Why’s 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

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

Contents

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

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 Developer’s 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

Contents

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

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

Contents

Taking it to the SDK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577

QuickBooks 2007 to the Rescue! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582

Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587

Who Should Read This Manual?

BOUT

HIS

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

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.

About This Manual

What’s New in This Guide?

This version of the programmer’s 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?

HAPTER

1 1

NTRODUCTION

QBSDK P

ROGRAMMING

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

Chapter 1: Introduction to QBSDK Programming

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?

The Programmer’s 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 user’s 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

Programmer’s 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 Programmer’s Guide, the following QuickBooks

SDK documentation is available:

> Onscreen Reference

Chapter 1: Introduction to QBSDK Programming

>Developer’s Guide for QBMS (QuickBooks Merchant Service)

> QuickBooks Web Connector Programmer’s 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?

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.

Chapter 1: Introduction to QBSDK Programming

After the Tech Overview and the SDK Essentials Video...

HAPTER

2 1

UMPSTART

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 Programmer’s 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.

Chapter 2: Jumpstart

The Basic Communication Pattern

HAPTER

3 1

OMMUNICATION

ODEL

AND

AYS

MPLEMENTING

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

owner’s 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.

Chapter 3: The Communication Model and Ways of Implementing It

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

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:

<Name>Checking Account</Name>

</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:

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

Chapter 3: The Communication Model and Ways of Implementing It

•A remote web application (web service) accessing a local QuickBooks via the local

QuickBooks Web Connector (QBWC)

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

Programmer’s Guide and the QBMS Programmer’s 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

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 Programmer’s Guide, which is included in the QB SDK.

Chapter 3: The Communication Model and Ways of Implementing It

How the QuickBooks UI Supports Authorization/Access

HAPTER

4 1

PECIFYING

UTHORIZATION

REFERENCES

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

Chapter 4: Specifying Authorization Preferences

•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

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 user’s 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.

Chapter 4: Specifying Authorization Preferences

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

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

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.

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.

Chapter 4: Specifying Authorization Preferences

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

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.

Chapter 4: Specifying Authorization Preferences

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

Figure 4-4 Integrated Application Preferences

Chapter 4: Specifying Authorization Preferences

Using Java with QB SDK

HAPTER

5 1

CCESSING

ESKTOP

UICK

OOKS

DITIONS

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.

Chapter 5: Accessing Desktop QuickBooks Editions

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

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

Chapter 5: Accessing Desktop QuickBooks Editions

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

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.

Chapter 5: Accessing Desktop QuickBooks Editions

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 application’s 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

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.

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.

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

Chapter 5: Accessing Desktop QuickBooks Editions

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 application’s 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

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-

Chapter 5: Accessing Desktop QuickBooks Editions

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.

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

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

Chapter 5: Accessing Desktop QuickBooks Editions

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:

UAC ON Attended Standard Elevated Unsuccessful

b. UAC ON Attended Elevated Standard Unsuccessful

A Few Notes About Using QBFC

HAPTER

6 1

UILDING

EQUESTS

QBFC

AND

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.

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 set’s 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.

Chapter 6: Building Requests In QBFC and in qbXML

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

‘ 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.)

Chapter 6: Building Requests In QBFC and in qbXML

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

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.

Chapter 6: Building Requests In QBFC and in qbXML

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

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)

Chapter 6: Building Requests In QBFC and in qbXML

responseXML = qbXMLRP.ProcessRequest(ticket, requestXML)

qbXMLRP.EndSession ticket

qbXMLRP.CloseConnection

Set qbXMLRP = Nothing

Processing a Response Using QBFC

HAPTER

7 1

ANDLING

ESPONSES

SING

QBFC

XML 1

This chapter describes how to handle responses using the QBFC library or the request

processor API.

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.

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.

Chapter 7: Handling Responses Using QBFC or qbXML

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.

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

‘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

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)

Chapter 7: Handling Responses Using QBFC or qbXML

‘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)

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

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

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,

Chapter 7: Handling Responses Using QBFC or qbXML

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

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.

Chapter 7: Handling Responses Using QBFC or qbXML

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

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

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

Chapter 7: Handling Responses Using QBFC or qbXML

' 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

End If ' End of customerRet

Next ' End of customerAddret

HAPTER

8 1

REATING

UERIES

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.

Chapter 8: Creating Queries

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

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

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

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>

<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

Chapter 8: Creating Queries

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.

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>

<CustomerQueryRq requestID="5001" iterator="Continue"

iteratorID="{D7355385-A17B-4f5d-B34D-F34C79C3E6FC}">

<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

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

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.

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>

<IncludeRetElement>FullName</IncludeRetElement>

</CustomerQueryRq>

</QBXMLMsgsRq>

</QBXML>

The following response shows what would be returned in the customer query listed above:

Chapter 8: Creating Queries

<?xml version="1.0" ?>

<QBXML>

<CustomerQueryRs requestID="2" statusCode="0" statusSeverity="Info"

statusMessage="Status OK">

<FullName>Abercrombie, Kristy</FullName>

</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

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