1

Developer Network

QuickBooks SDK Essentials

Peter A. VogelDeveloper Support

SupervisorIntuit Developer Network

2

Developer Network

Agenda

o Overview of the SDK

o Communicating with QuickBooks

o Rubber to the Road – Demo

o The Gory Details

o A Whirlwind Tour: SDK \ *.*

o FAQ and Resources

3

Developer Network

Overview of the SDK

4

Developer Network

SDK Design Principles

o Small business user in control

o Standards: XML, COM, HTTPS, SOAP

o One accounting spec: qbXML

o Extensible

o Robust (logging, error handling/recovery)

5

Developer Network

SDK: What Versions of QuickBooks?

o QuickBooks Desktop US (2002-2004…)

» Enterprise Solutions All flavors

» Premier All flavors

» Pro

Canada (2003-2004…)

o Online Edition Since Nov. 2002

6

Developer Network

What is it?

o qbXML is the “native language” of the SDK Request/Response model

Simple COM API to establish communication and exchange data

Basic functionality is part of QuickBooks

IntegratedApp

qbXML Request

qbXML ResponseQuickBooks

QB

XM

LR

P

7

Developer Network

So What’s in the SDK?

o Documentation

o Onscreen Reference

o Sample Programs and XML Requests

o Tools Object-based COM API to “wrap” qbXML

Validate XML

Basic Send/Receive Tool

More that we can talk about later

8

Developer Network

Choose Your Methodology

o qbXML The “assembly language” of QuickBooks

» Construct the XML requests/Parse the responses Ideal if your environment “speaks” XML natively

o QBFC The “C++” of QuickBooks

» COM object-oriented approach. Excellent for languages that “speak” COM naturally, like

VB.

o 3rd Party Developer Tools Environment-specific high-level abstractions

» Focus on your application logic, not QuickBooks ODBC, high-level objects

9

Developer Network

SDK: What’s Supported?

o Most Data Lists and Transactions

» Query, Add, Modify, Delete Depth of support varies with QB Version

» Version determines qbXML version supported

o Data Events Notification of changes to Lists and Txns

o UI Events Add menu items Notification of Company file open/close

10

Developer Network

Communicating with QuickBooks

11

Developer Network

Framework for Data Communication

o Open Connection to QuickBooks

o Begin session with a company file

o Construct set of request messages

o Send request to QuickBooks

o Receive response messages

o End session

o Close connection

12

Developer Network

Open Connection to QuickBooks

o OpenConnection(appID, appName) appID: empty string for now

» Intended to eventually allow QuickBooks to link to a listing on Solutions Marketplace

appName: name to appear in QuickBooks

o Starts QuickBooks if necessary

o Checks if the executable attaching is digitally signed.

13

Developer Network

Begin Session with a Company File

o BeginSession(companyFile,openMode) companyFile: path to the company to open openMode: an enum of desired file mode

» qbFileOpenSingleUser / omSingleUser» qbFileOpenMultiUser / omMultiUser» qbFileOpenDoNotCare / omDontCare

o Ensures correct company file is open in correct mode

o Displays application authorization if necessary

14

Developer Network

Construct set of request messages

o qbXML – just a string Most reliable method is to use a DOM API

» MSXML is freely available, convenient

o QBFC – Class hierarchy Almost a qbXML-specific DOM API No direct composition of qbXML Frequently less code Rocks when IntelliSense is available

o But *what* is a request? An XML string – you’ll see several examples in our

session today

15

Developer Network

Send Requests to QuickBooks (qbXMLRP2)

o response = ProcessRequest(ticket, requestXML) ticket: Session ticket from BeginSession

requestXML: string of XML containing request

Response: string of XML containing response

o Sends request HRESULT/exception if QB cannot parse the request

XML if request successful or QB encounters a business logic error

16

Developer Network

Send Requests to QuickBooks (QBFC)

o respMsgSet = DoRequests(requestMsgSet) requestMsgSet: QBFC object containing full content of a

request. respMsgSet: QBFC object containing content of response

o QBFC performs logical verification first HRESULT if detectable error

o Sends Request to QuickBooks HRESULT in rare cases Response status for success or QuickBooks logical error

17

Developer Network

End Session

o qbXMLRP: EndSession(ticket) ticket: the session ticket returned by beginSession

o QBFC: EndSession No ticket, QBFC manages internally

o Closes the company file for your app If QuickBooks UI is live company file will not close

Frees resources, etc.

18

Developer Network

Close Connection to QuickBooks

o CloseConnection Indicates intent to drop COM connection

o Be SURE to clear your COM pointer As long as you have a COM pointer, QB cannot close

19

Developer Network

The Framework with qbXMLRP

On Error GoTo HandleError

DIM qbXMLRP as RequestProcessor

Set qbXMLRP = new RequestProcessor

qbXMLRP.OpenConnection(“”, “Sample App”)

DIM ticket as String

ticket = _qbXMLRP.BeginSession(“”,qbFileOpenDoNotCare)

…

qbXMLRP.EndSession(ticket)

qbXMLRP.CloseConnection

Set qbXMLRP = nothing

…

HandleError:

MsgBox(…)

20

Developer Network

The Framework with QBFC

On Error Goto HandleError

DIM SessionMgr as QBSessionManager

Set SessionMgr = new QBSessionManager

SessionMgr.OpenConnection(“”,”Sample QBFC”)

SessionMgr.BeginSession(“”,omDontCare)

…

SessionMgr.EndSession

SessionMgr.CloseConnection

Set SessionMgr = nothing

…

HandleError:

msgBox(…)

21

Developer Network

Rubber to the Road - Demo

22

Developer Network

Simple! ~ What does the XML look like?

o strXML = Query.ToXMLString<?xml version="1.0"?><?qbxml version="3.0"?><QBXML> <QBXMLMsgsRq onError="continueOnError"> <CustomerQueryRq requestID=“1" /> </QBXMLMsgsRq></QBXML>

o QBFC took care of a lot of details XML prolog qbXML version <QBXML> and <QBXMLMsgsRq> envelopes Request ID

o The Response XML would be too long to show!

23

Developer Network

The Gory Details

qbXML Concepts

24

Developer Network

qbXML Vocabulary – qbXML Element

o Data that is bounded by a leading start tag and a trailing end tag. Tags are case sensitive.

<Name>Robin Q. Public</Name>

Note: Tags with no value may be used to clear a field in a modify request

<Addr4></Addr4> -or- <Addr4/>

25

Developer Network

qbXML Vocabulary – qbXML Aggregate

o A collection of elements or other aggregates. Cannot contain any data itself Can contain elements that contain data Can contain aggregates recursively.

<BillAddress>

<Addr1>123 Easy Street</Addr1>

<Addr2>Suite 12</Addr2>

<City>Mountain View</City>

<State>CA</State>

<PostalCode>94039</PostalCode>

<Country>USA</Country>

</BillAddress>

26

Developer Network

qbXML Vocabulary – Ref Aggregate

o An aggregate used to reference one type of QuickBooks record within a record which needs that information

<CustomerRef>

<FullName>Robin Q. Public</FullName>

</CustomerRef>

-OR-<CustomerRef>

<ListID>A40000-1071505981</ListID>

</CustomerRef>

27

Developer Network

Use of Ref Aggregates

28

Developer Network

qbXML Basics

o QB processes well-formed requests

ORDER of elements is IMPORTANT!

One response document for whole message set

Separate response status for each request in a set and for overall message set

o Request Types Query (filtered & unfiltered)

Add

Modify

Delete

Void

o Object Types List

» Items, Customers, …

Transaction» Invoice, Bill, Check, …

29

Developer Network

Objects: Coming and Going

o Distinguish between data you can send and data you receive. Add and Modify requests = Add + Modify objects

<CustomerModRq requestID=“1”>

<CustomerMod>

…

</CustomerMod>

</CustomerModRq>

Query, Add, Modify responses = Return Objects

<CustomerModRs requestID=“1” statusCode … >

<CustomerRet>

…

30

Developer Network

qbXML Request Message Structure

o Message Prolog XML processing instruction qbXML version

» DOCTYPE (1.0, 1.1) –or– » Processing Instruction (2.0 and later)

o Message Body<QBXML>

<QBXMLMsgsRq onError=“stopOnError”>

Requests (all top aggregates end with “Rq”)

CustomerQueryRq, CustomerAddRq, etc.

</QBXMLMsgsRq>

</QBXML>

31

Developer Network

qbXML Response Message Structure

o Message Prolog XML processing instruction

o Message Body<QBXML>

<QBXMLMsgsRs onError=“stopOnError”>Responses (all top aggregates end with “Rs”)

Each returned object aggregate ends with “Ret”CustomerRet, InvoiceRet, etc.

</QBXMLMsgsRs>

</QBXML>

32

Developer NetworkAdd Request

<?xml version="1.0" ?><?qbxml version="2.0" ?> <QBXML> <QBXMLMsgsRq onError = "stopOnError"> <CustomerAddRq requestID = "2"> <CustomerAdd> <Name>Joe B. Customer</Name> <FirstName>Joe</FirstName> <LastName>Customer</LastName> <BillAddress> <Addr1>123 Main St.</Addr1> <City>Mountain View</City> <State>CA</State> <PostalCode>94566</PostalCode> </BillAddress> </CustomerAdd> </CustomerAddRq> </QBXMLMsgsRq></QBXML>

33

Developer Network

<?xml version="1.0" ?><QBXML> <QBXMLMsgsRs> <CustomerAddRs requestID="2" statusCode="0" statusSeverity="Info"

statusMessage="OK"> <CustomerRet>

<ListID>A40000-1071505981</ListID><TimeCreated>2003-12-15T11:33:01-05:00</TimeCreated><TimeModified>2003-12-15T11:33:01-05:00</TimeModified>

` <EditSequence>1071505981</EditSequence><Name>Joe B. Customer</Name><FullName>Joe B. Customer</FullName><FirstName>Joe</FirstName><LastName>Customer</LastName><BillAddress> <Addr1>123 Main St.</Addr1> <City>Mountain View</City> <State>CA</State> <PostalCode>94566</PostalCode></BillAddress>

</CustomerRet> </CustomerAddRs> </QBXMLMsgsRs></QBXML>

Add Response

34

Developer Network

Key Concepts in that Response

o EditSequence Required to modify QuickBooks Data

Prevents Inadvertent Overwrite with Stale Data

If your EditSequence is out of date, you must refresh from QuickBooks

o Name vs. Fullname Name – the actual name of a list item

» <Name>Family room</Name>

Fullname – Includes parent names (like a path)

» <Fullname>Abercrombie, Kristy:Family room</Fullname>

35

Developer Network

The Gory Details

o QBFC & qbXML

36

Developer Network

qbXML Component Mapping

o Elements, Aggregates, Attributes -> Objects

o COM Object RequestProcessor -> QBSessionManager

o Unique to QBFC List and ORList Objects

37

Developer Network

o Declare, instantiate session manager

o Declare request message set

o Create request message set object

o Set request message set attributes

o Repeat Append request object

» Set values of request elements and attributes

Building Messages

38

Developer Network

Set Request Message Set Attributes

o Attributes property of the request message set An object itself, with properties for each attr

o Example: Set OnError, NewMessageSetID and OldMessageSetID

values

With requestMsgSet.Attributes .OnError = roeStop .NewMessageSetID = strNewMsgSetID .OldMessageSetID = “0”End With

39

Developer Network

Building Messages

o Declare, instantiate session manager

o Declare request message set

o Create request message set object

o Set request message set attributes

o Repeat Append request object

» Set values of request elements and attributes

40

Developer Network

Append a Request to the Message Set

o Separate object types for requests

o Append* methods for requests

Dim invoiceAdd As QBFC3Lib.IInvoiceAdd

Set invoiceAdd = requestMsgSet.AppendInvoiceAddRq

41

Developer Network

Element Objects

o Associated with values

o Standard types

o Methods SetValue, SetValueAsString, SetEmpty, Unset

GetValue, GetValueAsString

IsEmpty, IsSet

GetMaxLength

invoiceAdd.RefNumber.SetValue “0013672”

42

Developer Network

Aggregate Objects

o May Contain Aggregate objects

Attribute objects

Element objects

List objects

ORList objects

43

Developer Network

Set Values Within Aggregates

With invoiceAdd.ShipAddress

.Addr1.SetValue “Brian Cook"

.Addr2.SetValue "c/o Enviromental Designs"

.Addr3.SetValue "1521 Main Street"

.Addr4.SetValue "Suite 204"

.City.SetValue "Culver City"

.State.SetValue "CA"

.PostalCode.SetValue "90139"

End With

44

Developer Network

List and ORList Objects

o List - Multiple aggregates or elements of same type

o ORList – Multiple aggregates or elements of different types

o Methods Add or Append, Count, GetAt

45

Developer Network

List and ORList Object Examples

o List ListID, TxnID or FullName filters

Expense lines

o ORList Invoice line list (Item or ItemGroup Lines)

Some Query response lists

» Item query response, entity query response

46

Developer Network

Add ORList Object And Set Object Values

Dim invoiceLineAdd As QBFC3Lib.IInvoiceLineAdd

Set invoiceLineAdd = invoiceAdd.ORInvoiceLineAddList.Append.InvoiceLineAdd

invoiceLineAdd.ItemRef.FullName.SetValue "Installation"

invoiceLineAdd.Quantity.SetValue 2

47

Developer Network

QBFC Response Handling Steps

o Get count of responses

o Step through responses getting status Step through response return lists if any

» Check for object existence Retrieve data for your application

48

Developer Network

Get Response Information

Dim response As IResponse

For i = 0 to responseMsgSet.ResponseList.Count - 1

Set response = responseMsgSet.ResponseList.GetAt(i)

…

Next i

49

Developer Network

Access Response Attributes

If response.StatusCode <> 0 Then

msg = "Status: Code = " &

CStr(response.StatusCode) & _

", Message = " & response.StatusMessage & _

", Severity = " & response.StatusSeverity & vbCrLf

MsgBox msg

End If

50

Developer Network

Getting Response Details

If (Not response.Detail Is Nothing) Then    

Dim responseType As Integer

responseType = response.Type.GetValue    

Dim j As Integer

If (responseType = rtInvoiceAddRs) Then     

Dim invoiceRet As IInvoiceRet

Set invoiceRet = response.Detail     

    End If   

End If  

51

Developer Network

Retrieve Response Elements

txnID = invoiceRet.TxnID.GetValue

If Not (invoiceRet.RefNumber Is Nothing) Then

frmInvoiceDisplay.txtInvoiceNumber =

invoiceRet.RefNumber.GetValue

End If

52

Developer Network

Retrieve and Step Through ORList

Dim orInvoiceLineRetList As QBFC2Lib.IORInvoiceLineRetList

Set orInvoiceLineRetList = invoiceRet.ORInvoiceLineRetList

If Not (orInvoiceLineRetList Is Nothing) Then

Dim i As Integer

For i = 0 To ORInvoiceLineRetList.Count – 1

‘Code to handle each possible type in the ORList

Next

End If

53

Developer Network

ORList Handling

If invoiceRet.ORInvoiceLineRetList.GetAt(i).ortype = _

orilrInvoiceLineRet Then

‘Code to handle InvoiceLineReturn

Else

‘Code to handle InvoiceGroupLineReturn

End If

o Lists require no type checking in your application

54

Developer Network

o Most frequent QBFC support request

invoiceAdd.ORInvoiceLineAddList.Append.invoiceLineAdd.ItemRef.FullName.SetValue “Installation”

invoiceAdd.ORInvoiceLineAddList.Append.invoiceLineAdd.Quantity.SetValue 3

o Append creates a new object! Code above creates two invoice lines

» First has an item, but no quantity

» Second has a quantity, but no item

o Immediately obvious with ToXMLString output!

Append Misuse

55

Developer Network

Proper Append Use

Dim invoiceLineAdd As QBFC2Lib.IInvoiceLineAdd

Set invoiceLineAdd = invoiceAdd.ORInvoiceLineAddList.Append.invoiceLineAdd

invoiceLineAdd.ItemRef.FullName.setValue "Installation"

invoiceLineAdd.Quantity.setValue 3

56

Developer Network

A Whirlwind Tour: SDK \ *.*

57

Developer Network

Several Developer Tools Available

o Different approaches for different environments For traditional programming environments

» AcctSync, CoreObjX – higher level object view

For specific application environments

» Alpha 5/QLinker for Alpha 5 database

» Data Flow Manager for Access/VB environments

» …

For ODBC environments

» qODBC

o http://developer.intuit.com/QuickBooksSDK/Resources/?id=97

58

Developer Network

All about Data so Far

o Request/Response model is great! But what if I need to know what the user just did in

QuickBooks?» Keeping track of additional customer data?

Picture scanning? » Sending Estimates to people in the field?» …

o QuickBooks 2004 introduces Events Data Events (Add/Modify/Merge/Delete) UI Events (Company Open/Close) UI Extension Events

» (Add a menu item or submenu to hit your app)

59

Developer Network

Event model

o App subscribes to events it wants Build subscription request message set

» AppName» COM ProgID or CLSID for notification

Send subscription request to QuickBooks» No session needed, just connection

o QuickBooks admin approves subscriptiono QuickBooks sends event XML via COM callback

60

Developer Network

Other SDK Items for Consideration

o Error recovery

o Macros to reduce parsing effort

o Data Extensions and Custom Fields

o Reports – Getting the data or telling QB to display

o Tools Subscription viewer Out of process COM wrappers to support ASP

o Remote Data Sharing Allow your App to access QB over the net

o QuickBooks Online Edition

o Troubleshooting tips

61

Developer Network

FAQ and Resources

62

Developer Network

Why not IIF?

o IIF import bypasses QuickBooks business logic Can corrupt company files

» Can cause incorrect/invalid accounting data

» Break referential integrity of database

Drives call volume at Intuit Technical Support

o Significant % of customers uncomfortable with navigating file system Export/Import confusing, difficult to find the file

Double imports especially troublesome

SDK: Robust, real-time, two-way communication

63

Developer Network

A Roadmap to Complete Understanding

64

Developer Network

IDN Resources

o Our main web site: http://developer.intuit.com

o Developer forums: http://idnforums.intuit.com

o Developer Support idn_dev_support@intuit.com

o 3rd Party Tools http://developer.intuit.com/QuickBooksSDK/Resources/?

id=97

o Solutions Marketplace http://marketplace.intuit.com