Dev Guide Quick Books

QuickBooks SDK ®

Developer’s Guide

for QuickBooks

Version 4.0

SDK version 4.0, released November 2004. (c) 2004 Intuit Inc. All rights reserved. QuickBooks and Intuit are registered trademarks of Intuit Inc. All other trademarks are the property of their respective owners and should be treated as such. Acknowledgement: This product includes software developed by the Apache Software Foundation () (c) 1999-2004 The Apache Software Foundation. All rights reserved. Intuit Inc. P.O. Box 7850 Mountain View, CA 94039-7850 For more information about the QuickBooks SDK and the SDK documentation, visit http://developer.intuit.com/QuickBooksSDK/.

CONTENTS About This Guide Who Should Read This Guide? . . . . . Before You Begin . . . . . . . . . . . . . . What If I Don’t Want to Use qbXML? . What’s in This Guide? . . . . . . . . . . . What’s New in This Manual?. . . . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

.vii .vii viii . ix . ix

Request Processor . . . . . . . . . . . . . . . . . . . . . . Typical Connection Sequence . . . . . . . . . . . . . . . Session Ticket . . . . . . . . . . . . . . . . . . . . . . . . . Multiple Sessions versus a Single Session. . . . What’s inside a Message? . . . . . . . . . . . . . . . . . Obtaining a Digital Certificate for Your Application

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

Enabling Users to Authorize Your Application . . . . . . . . . . . . . . . . . . When is the Authorization Dialog Displayed?. . . . . . . . . . . . . . . . The Default Authorization Dialog . . . . . . . . . . . . . . . . . . . . . . . . Using AuthPreferences to Obtain Proper Application Authorization . Setting Authorization Preferences Within QuickBooks. . . . . . . . . . More Information about Login Modes . . . . . . . . . . . . . . . . . . . . . Only One Auto-Login User per Application . . . . . . . . . . . . . . . . . Limitations on Accessing Company Files . . . . . . . . . . . . . . . . . . . Allowing Application Access to Personal Data . . . . . . . . . . . . . . . Single-User vs. Multi-User Mode . . . . . . . . . . . . . . . . . . . . . . . . Trade-offs of Using Single-User Mode. . . . . . . . . . . . . . . . . . . . . Hello, QuickBooks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C++ Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Visual Basic Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BeginSession Checks and Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . Subscribing Your Application to QuickBooks Events. . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. 8 . 8 . 8 . 9 13 14 16 16 17 17 18 19 19 22 22 23

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

25 25 26 26

Chapter 1: Introduction 1 1 2 2 3 3

Chapter 2: Communicating with QuickBooks

Chapter 3: Supporting Your User Helping Users Troubleshoot and Resolve Problems . . . . . . Multiple Installed Versions of QuickBooks . . . . . . . . . . Incompatible Versions: QuickBooks and Company File . Different Company File Is Already Open . . . . . . . . . . . Warn Your Users to Complete Error Recovery before Upgrading. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . . . . . . . . . . . . . . . . . 26

Contents iii (c) 2004 Intuit Inc. All rights reserved.

Versions of Integrated Applications . . . . . . . . . . . . . Provide a Means for Breaking Out of Error Recovery . Topics to Include in Your Documentation . . . . . . . . . . . Permissions Required for Auto-Login. . . . . . . . . . . . QuickBooks User Permissions. . . . . . . . . . . . . . . . . Application Access to Personal Data . . . . . . . . . . . . Complete Error Recovery before Upgrading . . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. 27 . 27 . 27 . 28 . 28 . 28 . 29

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. 34 . 35 . 37 . 38 . 39 . 40 . 41 . 42 . 43 . 44 . 45 . 46 . 47 . 48 . 49 . 51 . 52 . 53 . 54 . 55 . 56

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. 61 . 63 . 63 . 64

Chapter 4: Method Reference AuthPreferences . . . . . . . . . . BeginSession . . . . . . . . . . . . CloseConnection . . . . . . . . . . EndSession . . . . . . . . . . . . . . GetCurrentCompanyFileName . GetIsReadOnly . . . . . . . . . . . GetPersonalDataPref . . . . . . . GetUnattendedModePref. . . . . WasAuthPreferencesObeyed . . PutIsReadOnly . . . . . . . . . . . PutPersonalDataPref . . . . . . . PutUnattendedModePref . . . . . MajorVersion. . . . . . . . . . . . . MinorVersion. . . . . . . . . . . . . OpenConnection2 . . . . . . . . . ProcessRequest . . . . . . . . . . . ProcessSubscription . . . . . . . . QBXMLVersionsForSession . . . QBXMLVersionsForSubscription ReleaseLevel . . . . . . . . . . . . . ReleaseNumber . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

Appendix A: Result Codes Appendix B: qbXML Specification for the Canadian Editions Differences Between the qbXML Specifications Installation . . . . . . . . . . . . . . . . . . . . . . . . . About Units of Measure . . . . . . . . . . . . . . . . About UI Integration . . . . . . . . . . . . . . . . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

Appendix C: The QuickBooks SDK and Digital Code Signing Code Signing Technology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 About Microsoft Authenticode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 What is a Digital Certificate? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

iv

Contents (c) 2004 Intuit Inc. All rights reserved.

The Certificate Authority . . . . . . . . . . . . . . . . . . . . . . . . . . . Code Signing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Obtaining a Digital Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . Commercial CA Entities You Can Use . . . . . . . . . . . . . . . . . . . Obtaining the Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . Signing Your Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Do You Have Everything You Need? . . . . . . . . . . . . . . . . . . . . An Example Using a Test Application . . . . . . . . . . . . . . . . . . . Signing Code With the Internet Client Software Developer’s Kit Useful web site links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

66 66 67 67 67 67 68 68 70 74

Contents (c) 2004 Intuit Inc. All rights reserved.

v

vi

Contents (c) 2004 Intuit Inc. All rights reserved.

ABOUT THIS GUIDE

This Developer’s Guide describes the qbXML Request Processor API, which is used to send requests to and receive responses from QuickBooks. The guide focuses on the communication between your application and QuickBooks, not on the content of the messages themselves. For information on the structure and content of the messages, which are sent as qbXML documents, see the Concepts Manual and the Onscreen Reference. The qbXML Request Processor API described in this manual is implemented using Microsoft’s Component Object Model (COM). This API is small (consisting of just a few methods) and easy to use.

Who Should Read This Guide? This guide is for developers who are creating applications that integrate with U.S. and Canadian editions of QuickBooks.1 This API requires that you construct the qbXML messages separately, using a method of your choice, and then supply the messages as a text stream to the COM method (ProcessRequest) contained in this library. You need some familiarity, but need not be an expert, with the following: •

XML, because the messages use qbXML, an XML (eXtensible Markup Language) specification designed for QuickBooks

•

COM, because the API used to send messages is a COM library

Before You Begin Before you read the rest of this guide, be sure you’ve read the Technical Overview for the QuickBooks Software Development Kit (SDK). This guide assumes you’re already familiar with the introductory material and key concepts contained in the overview as well as the first three chapters of the Concepts Manual. Figure 1 on page viii shows the complete SDK documentation set and the other documents you’ll consult as you develop your integrated application. You’ll also want to check out the Onscreen Reference for QuickBooks, which contains the qbXML syntax for each request and response message type. The Onscreen Reference has separate sections for the U.S. and Canadian editions of QuickBooks. 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 QuickBooks Online Edition). If you are developing for multiple QuickBooks products, be sure to read the Developer’s Guide for each target QuickBooks product, as shown in Figure 1 on page viii. (Note too that the Concepts Manual applies to integrating with any QuickBooks product.) 1 In

this guide, the term QuickBooks refers to QuickBooks Pro; QuickBooks Premier; QuickBooks Enterprise Edition; and the industry-specific editions of QuickBooks.When the distinction is important, the guide refers to the U.S. and Canadian editions of QuickBooks (see Appendix B, which compares the two specifications). Who Should Read This Guide? vii (c) 2004 Intuit Inc. All rights reserved.

You are here

Developer’s Guide for QuickBooks (U.S. and Canadian Editions)

Technical Overview

Concepts Manual

Developer’s Guide for QBFC

Developer’s Guide for QuickBooks Online Edition

2

1

• What is the QuickBooks SDK?

• What is in a QuickBooks message? • How do I use the information contained in the messages?

Figure 1

3

• How does my application communicate with QuickBooks?

Onscreen Reference for • QuickBooks (U.S.) • QuickBooks (Canadian) • QuickBooks Online Edition, • QBFC (U.S.) • QBFC (Canadian)

(Strongly Recommended for Any Programming in the SDK)

4

• What is the exact syntax for a given message?

Documentation Roadmap

What If I Don’t Want to Use qbXML? An alternative to using the qbXML Request Processor API is to use the QuickBooks Foundation Class (QBFC) Library, a COM library that implements the requests and responses as COM methods and parameters instead of qbXML documents. For more information about QBFC, see the Technical Overview and the Developer’s Guide for QBFC. The QBFC Library includes support for QuickBooks Online Edition as well as QuickBooks.

viii About This Guide (c) 2004 Intuit Inc. All rights reserved.

What’s in This Guide? This Developer’s Guide contains the following chapters: Chapter 1, “Introduction,” describes important concepts about communicating with QuickBooks, including what the Request Processor does, the typical sequence for connecting with QuickBooks, the session ticket, and registering and certifying your application. Chapter 2, “Communicating with QuickBooks,” describes how to use the AuthPreferences property (new in SDK 4.0) and related methods to prompt the administrator to supply the proper authorizations required by your application. It also describes the OpenConnection2 method (new in SDK 4.0) that provides for varying types of QuickBooks connection. It explains the difference between interactive and automatic login modes, and between singleuser and multi-user modes. A sample “Hello, QuickBooks” program illustrates the calling sequence for connecting and sending messages to QuickBooks. Chapter 3, “Supporting Your User,” presents ways your application can help the user troubleshoot typical problems that arise when an application attempts to connect to QuickBooks and open a company file. It also suggests topics you may want to include in your documentation to help the user avoid common pitfalls when setting up users and permissions within QuickBooks. Chapter 4, “Method Reference,” is an alphabetical reference to the COM methods that make up the qbXML Request Processor API. Appendix A, “Result Codes,” describes the result codes returned by the ProcessRequest method. A nonzero result code indicates an error condition. Appendix B, “qbXML Specification for the Canadian Editions,” highlights the differences between the U.S. and Canadian editions of QuickBooks. Also see the Onscreen Reference for QuickBooks (Canadian Editions), which presents the complete syntax and descriptions for all qbXML elements, aggregates, and attributes for the Canadian editions of QuickBooks. The Onscreen Reference is installed with the SDK and is also located online at http://developer.intuit.com/QuickBooksSDK/chart.asp?id=94. Appendix C, “QuickBooks SDK and Digital Code Signing,” describes the basics of digital code signing as it affects QuickBooks.

What’s New in This Manual? This manual includes details on the AuthPreferences object and related methods that you should consider using, as they significantly simplify the user’s task of authorizing your application and also enable you application to specify what kind of authorizations it needs. The manual also includes details on OpenConnection2, which can be used to connect to desktop QuickBooks editions, QuickBooks via RDS, or even QuickBooks Online Edition.

What’s in This Guide? (c) 2004 Intuit Inc. All rights reserved.

ix

x

About This Guide (c) 2004 Intuit Inc. All rights reserved.

CHAPTER 1 INTRODUCTION

1 1

The interactions between your application and QuickBooks follow the client-server model. Your application (the client) sends a request to QuickBooks (the server). QuickBooks services the request and sends back a response containing data and status codes. Request (Object + Operation)

Developer Application

QuickBooks Response (Data + Status Code)

Client Figure 1-1

Server Client/server model of communication with QuickBooks

Request Processor The qbXML Request Processor is the gatekeeper between your application and QuickBooks. The Request Processor implements the COM interface described in this guide. This interface 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. NOTE 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. (See the chapter on Event Notification in the Concepts guide.)

Typical Connection Sequence In the current model, QuickBooks and your application run on the same desktop system: 1. A connection is opened. 2. A session is established for working on a specific QuickBooks company file. 3. A conversation is held between the application and QuickBooks. 4. The session is ended. 5. The connection is closed. Request Processor (c) 2004 Intuit Inc. All rights reserved.

1

Session Ticket When a working session for a particular company file is established, the Request Processor provides your application with a session handle, called a ticket, that identifies this session. Your application stores the ticket for the duration of the session and passes it to the Request Processor each time your application sends a request message to QuickBooks. NOTE The session ticket is not needed or used in the Request Processor event subscription API.

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 1-2 on page 2. Connection

Session

Request Message Set 1/ Response

Request Message Set 2/ Response

Start time

Figure 1-2

Request Message Set 3/ Response End time

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 1-3 on page 3. Sessions do not overlap.

2

Chapter 1: Introduction (c) 2004 Intuit Inc. All rights reserved.

Connection to QuickBooks

Session 1 Request Message Set / Response

Session 2 Request Message Set / Response

Session 3 Request Message Set / Response

Start time

End time

Figure 1-3

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.

What’s inside a Message? This guide takes a “black-box” approach to the request and response messages themselves. Each message is actually a document that contains qbXML, a form of eXtensible Markup Language (XML) designed to deal with QuickBooks data. Many developers use an XML parser such as Microsoft’s XML Core Services 4.0 (MSXML) because it makes parsing and assembling messages easier, but this is not a requirement. Messages are supplied as text strings when they are sent to the Request Processor. For more information on message content and format, see the Concepts Manual and the Onscreen Reference for your target QuickBooks products.

Obtaining a Digital Certificate for Your Application You can apply for and obtain a digitally signed certificate for your application. This certificate assures the user that your application code is authentic and has not been tampered with. For information on digitally signed certificates, what they are, how support for them is implemented in QuickBooks, and how to obtain and use them in your application, please see Appendix C, “The QuickBooks SDK and Digital Code Signing.” At login, QuickBooks presents one of two user interfaces depending on whether an integrated application has a digital certificate. Figure 1-4 on page 4 shows the user interface for authorizing login by signed applications. Figure 1-5 on page 5 shows the user interface for authorizing login by applications that are not signed. NOTE The authorization dialogs shown are those for the current QuickBooks release. If you have an older version of QuickBooks, your dialogs may vary slightly.

What’s inside a Message? (c) 2004 Intuit Inc. All rights reserved.

3

Figure 1-4

4

Chapter 1: Introduction (c) 2004 Intuit Inc. All rights reserved.

User interface authorizing an application with certificate information

Figure 1-5

User interface authorizing an application without a certificate

Obtaining a Digital Certificate for Your Application (c) 2004 Intuit Inc. All rights reserved.

5

6

Chapter 1: Introduction (c) 2004 Intuit Inc. All rights reserved.

CHAPTER 2 COMMUNICATING WITH QUICKBOOKS

1 1

This chapter describes important concepts relating to how your application communicates with QuickBooks. It also presents a simple code example illustrating the basic sequence of calls to the qbXML Request Processor during a QuickBooks session. The following topics are covered: •

Authorizing your application, which describes >

The default authorization page

>

Using the AuthPreferences property (new in SDK 4.0) of the request processor, along with its methods to inform the QuickBooks administrative user about your application’s authorization requirements and simplify the user’s selection choices (new functionality in SDK 4.0).

>

Background information on how the QuickBooks administrative user sets authorization preferences for your integrated application within QuickBooks if you don’t use the AuthPreferences object.

>

More information on login modes (auto-login versus interactive login)

>

More information on accessing personal company data

>

More information on single-user versus multi-user mode for accessing a QuickBooks company file

•

“Hello, QuickBooks,” a code excerpt that illustrates the sequence of calls to the qbXML Request Processor for communicating with QuickBooks (see Chapter 4, “Method Reference,” for a complete description of the highlighted methods and parameters).

•

Subscribing to events is briefly covered.

IMPORTANT Starting with SDK 4.0, a new connection method is supported, called OpenConnection2. It provides a connection type parameter that allows your application to connect to QuickBooks in various useful ways, such as connecting to QuickBooks Online Edition or forcing an RDS connection even if QuickBooks is installed locally.

7 (c) 2004 Intuit Inc. All rights reserved.

Enabling Users to Authorize Your Application NOTE This section on authorization does not apply to QuickBooks Online Edition. QBOE does not support the AuthPreferences property and uses different authorization processes.

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? As previously noted, 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 2-1 on page 9. In this authorization dialog, the QuickBooks administrator can •

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

8

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.

Chapter 2: Communicating with QuickBooks (c) 2004 Intuit Inc. All rights reserved.

•

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.

Figure 2-1

Default Authorization Form

Using AuthPreferences to Obtain Proper Application Authorization Starting with SDK 4.0, 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. Using AuthPreferences is recommended because it lets 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, and eliminates the need to navigate 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.

Enabling Users to Authorize Your Application (c) 2004 Intuit Inc. All rights reserved.

9

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

>

umpOptional, which causes the QuickBooks authorization dialog to display its default selections.

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

>

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.

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. IMPORTANT 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: Using AuthPreferences The following snippet is taken from the SDK sample SDKTestPlus3, which is located at samples\qbdt\vb\qbxml\SDKTestPlus3. This snippet shows the use of the AuthPreference object to set preferences in AuthPreferences. 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. 10 Chapter 2: Communicating with QuickBooks (c) 2004 Intuit Inc. All rights reserved.

If (frmSDKTestPlus3.AuthPrefsDirty) Then Dim prefs As QBXMLRP2Lib.AuthPreferences Set prefs = qbXMLCOM.AuthPreferences If (frmSDKTestPlus3.Unattended.Value) Then prefs.PutUnattendedModePref umpRequired Else prefs.PutUnattendedModePref umpOptional End If prefs.PutIsReadOnly frmSDKTestPlus3.ReadOnly.Value If (frmSDKTestPlus3.pdRequired.Value) Then prefs.PutPersonalDataPref pdpRequired ElseIf (frmSDKTestPlus3.pdNotNeeded.Value) Then prefs.PutPersonalDataPref pdpNotNeeded Else prefs.PutPersonalDataPref pdpOptional End If End If

In this snippet, the parent form frmSDKTestPlus3 is checked to see whether any preferences have been changed. If any changes were made, the various components in the form are checked for new user selections and those choices are then set in the AuthPreferences object. NOTE This snippet is for a sandbox type application that allows for a runtime changing of the AuthPreferences requirements. Your application probably would not do this, but would instead simply set the preferences in the way your application requires.

The next time the application connects to QuickBooks after any change, the proper authorization dialog is shown. 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 2-2 on page 12 would be shown to the user.

Enabling Users to Authorize Your Application (c) 2004 Intuit Inc. All rights reserved.

11

Figure 2-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 2-3 on page 13.

12 Chapter 2: Communicating with QuickBooks (c) 2004 Intuit Inc. All rights reserved.

Figure 2-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 2-4 on page 14 shows the window presented to the administrator for managing integrated applications and their access to QuickBooks.

Enabling Users to Authorize Your Application (c) 2004 Intuit Inc. All rights reserved.

13

Figure 2-4

Integrated Application Preferences

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 smallbusiness owner, it is in auto-login mode.

14 Chapter 2: Communicating with QuickBooks (c) 2004 Intuit Inc. All rights reserved.

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

Setting Up Auto-Login As described in the preceding section, you use the AuthPreferences object to inform the user that auto-login (unattended) mode is required. 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 2-5 on page 15).

Figure 2-5

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. Enabling Users to Authorize Your Application (c) 2004 Intuit Inc. All rights reserved.

15

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. IMPORTANT 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 2-6 on page 16 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 2-6 on page 16, each user must have a different name. QuickBooks System 1

User: Sam (interactive login) Company File: QuickBooks System 2

Joe’s Bakery (shared drive)

User: Jane (interactive login) QuickBooks System 3

User: Everett (interactive login) QuickBooks System 4

User: Joe (auto-login) Figure 2-6

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 autologin mode. 16 Chapter 2: Communicating with QuickBooks (c) 2004 Intuit Inc. All rights reserved.

Allowing Application Access to Personal Data The Access Rights window shown in Figure 2-5 on page 15 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 2-1 on page 18 summarizes the different combinations. Note that if an integrated application opens a company file in single-user mode, no other applications or users can work on that company file during that session. In some cases, this mode may be necessary, but in others it may be bad citizenship. 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.

Enabling Users to Authorize Your Application (c) 2004 Intuit Inc. All rights reserved.

17

Table 2-1

QuickBooks company file login mode access conditions and rIghts

Who started QuickBooks

Mode

Who may obtain access

Integrated Application

Single-user

No one else

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

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

•

Exclusion of other applications. Your application locks out other applications, denying them access to the company file. This behavior is considered impolite. In environments that are known to need multi-user access, this might be of some concern.

18 Chapter 2: Communicating with QuickBooks (c) 2004 Intuit Inc. All rights reserved.

Hello, QuickBooks The following code samples illustrate the typical sequence for communicating with QuickBooks. The first example is written in C++, the second in Visual Basic. Highlights of this sample test code are as follows (see boldface calls in sample code): 1. Read the qbXML request from a file. 2. Instantiate the Request Processor. 3. Open the connection to QuickBooks (OpenConnection method; the application name and ID are parameters to this method, or default values can be used here). 4. Begin the session for working on a specific company (BeginSession method; the QuickBooks company data file is provided here as a parameter. The mode can also be specified here. Your application needs to save the ticket.). 5. Show the name of the currently open data file. 6. Process the request (ProcessRequest method; uses the ticket and reads data from the provided qbXML file). This step can be repeated multiple times within a session. 7. Dump the response to a file. 8. End the session (EndSession method). 9. Close the connection (CloseConnection method).

C++ Example The complete sample code for this example is included in the SDK; see SDKTest.cpp. Also see the Visual Basic sample code in the following section and in Appendix A of the Technical Overview. . . . #import "QBXMLRP2.dll" void process_XMLDataCOM (CComBSTR CComBSTR TCHAR TCHAR TCHAR { CComBSTR qbFile (fileName); BSTR xmlInput = NULL; BSTR xmlOutput = NULL; BSTR companyName = NULL;

appName, appID, *fileName, *inputXMLFileName, *outputXMLFileName)

clock_t startTime; clock_t finishTime; double duration; TCHAR durationStr [100]; HRESULT hr = S_OK; BSTR ticket = NULL; QBXMLRP2Lib::IRequestProcessor3Ptr

pReqProc;

Hello, QuickBooks 19 (c) 2004 Intuit Inc. All rights reserved.

if (!readXMLinputFile (inputXMLFileName, &xmlInput)) { std::cout BeginSession (qbFile.m_str, qbMode, &ticket); if (SUCCEEDED (hr)) { hr = pReqProc->GetCurrentCompanyFileName (ticket, &companyName); if (SUCCEEDED (hr)) { std::cout