1. QuickBooks SDK Essentials
Peter A. Vogel Developer Support Supervisor Intuit Developer Network

2. Agenda Overview of the SDK Communicating with QuickBooks
Rubber to the Road – Demo
The Gory Details
A Whirlwind Tour: SDK \ *.*
FAQ and Resources

3. Overview of the SDK

4. SDK Design Principles Small business user in control
Standards: XML, COM, HTTPS, SOAP
One accounting spec: qbXML
Extensible
Robust (logging, error handling/recovery)

5. SDK: What Versions of QuickBooks?
QuickBooks Desktop
US ( …)
Enterprise Solutions
All flavors
Premier
Pro
Canada ( …)
Online Edition
Since Nov. 2002

6. What is it? 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
Integrated
App
qbXML Request
qbXML Response
QuickBooks
QBXMLRP

7. So What’s in the SDK? Documentation Onscreen Reference
Sample Programs and XML Requests
Tools
Object-based COM API to “wrap” qbXML
Validate XML
Basic Send/Receive Tool
More that we can talk about later

8. Choose Your Methodology
qbXML
The “assembly language” of QuickBooks
Construct the XML requests/Parse the responses
Ideal if your environment “speaks” XML natively
QBFC
The “C++” of QuickBooks
COM object-oriented approach.
Excellent for languages that “speak” COM naturally, like VB.
3rd Party Developer Tools
Environment-specific high-level abstractions
Focus on your application logic, not QuickBooks
ODBC, high-level objects

9. SDK: What’s Supported? Most Data Data Events UI Events
Lists and Transactions
Query, Add, Modify, Delete
Depth of support varies with QB Version
Version determines qbXML version supported
Data Events
Notification of changes to Lists and Txns
UI Events
Add menu items
Notification of Company file open/close

10. Communicating with QuickBooks

11. Framework for Data Communication
Open Connection to QuickBooks
Begin session with a company file
Construct set of request messages
Send request to QuickBooks
Receive response messages
End session
Close connection

12. Open Connection to QuickBooks
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
Starts QuickBooks if necessary
Checks if the executable attaching is digitally signed.

13. Begin Session with a Company File
BeginSession(companyFile,openMode)
companyFile: path to the company to open
openMode: an enum of desired file mode
qbFileOpenSingleUser / omSingleUser
qbFileOpenMultiUser / omMultiUser
qbFileOpenDoNotCare / omDontCare
Ensures correct company file is open in correct mode
Displays application authorization if necessary

14. Construct set of request messages
qbXML – just a string
Most reliable method is to use a DOM API
MSXML is freely available, convenient
QBFC – Class hierarchy
Almost a qbXML-specific DOM API
No direct composition of qbXML
Frequently less code
Rocks when IntelliSense is available
But *what* is a request?
An XML string – you’ll see several examples in our session today

15. Send Requests to QuickBooks (qbXMLRP2)
response = ProcessRequest(ticket, requestXML)
ticket: Session ticket from BeginSession
requestXML: string of XML containing request
Response: string of XML containing response
Sends request
HRESULT/exception if QB cannot parse the request
XML if request successful or QB encounters a business logic error

16. Send Requests to QuickBooks (QBFC)
respMsgSet = DoRequests(requestMsgSet)
requestMsgSet: QBFC object containing full content of a request.
respMsgSet: QBFC object containing content of response
QBFC performs logical verification first
HRESULT if detectable error
Sends Request to QuickBooks
HRESULT in rare cases
Response status for success or QuickBooks logical error

17. End Session qbXMLRP: EndSession(ticket) QBFC: EndSession
ticket: the session ticket returned by beginSession
QBFC: EndSession
No ticket, QBFC manages internally
Closes the company file for your app
If QuickBooks UI is live company file will not close
Frees resources, etc.

18. Close Connection to QuickBooks
Indicates intent to drop COM connection
Be SURE to clear your COM pointer
As long as you have a COM pointer, QB cannot close

19. 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. 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. Rubber to the Road - Demo

22. Simple! ~ What does the XML look like?
strXML = Query.ToXMLString
<?xml version="1.0"?> <?qbxml version="3.0"?> <QBXML> <QBXMLMsgsRq onError="continueOnError"> <CustomerQueryRq requestID=“1" /> </QBXMLMsgsRq> </QBXML>
QBFC took care of a lot of details
XML prolog
qbXML version
<QBXML> and <QBXMLMsgsRq> envelopes
Request ID
The Response XML would be too long to show!

23. The Gory Details
qbXML Concepts

24. qbXML Vocabulary – qbXML Element
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. qbXML Vocabulary – qbXML Aggregate
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. qbXML Vocabulary – Ref Aggregate
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-
<ListID>A </ListID>

27. Use of Ref Aggregates

28. qbXML Basics 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
Request Types
Query (filtered & unfiltered)
Add
Modify
Delete
Void
Object Types
List
Items, Customers, …
Transaction
Invoice, Bill, Check, …

29. Objects: Coming and Going
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. qbXML Request Message Structure
Message Prolog
XML processing instruction
qbXML version
DOCTYPE (1.0, 1.1) –or–
Processing Instruction (2.0 and later)
Message Body
<QBXML>
<QBXMLMsgsRq onError=“stopOnError”>
Requests (all top aggregates end with “Rq”)
CustomerQueryRq, CustomerAddRq, etc.
</QBXMLMsgsRq>
</QBXML>

31. qbXML Response Message Structure
Message Prolog
XML processing instruction
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. Add 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. Add Response <?xml version="1.0" ?> <QBXML>
<QBXMLMsgsRs>
<CustomerAddRs requestID="2" statusCode="0" statusSeverity="Info" statusMessage="OK">
<CustomerRet>
<ListID>A </ListID>
<TimeCreated> T11:33:01-05:00</TimeCreated>
<TimeModified> T11:33:01-05:00</TimeModified>
` <EditSequence> </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>

34. Key Concepts in that Response
EditSequence
Required to modify QuickBooks Data
Prevents Inadvertent Overwrite with Stale Data
If your EditSequence is out of date, you must refresh from QuickBooks
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. The Gory Details
QBFC & qbXML

36. qbXML Component Mapping
Elements, Aggregates, Attributes -> Objects
COM Object
RequestProcessor -> QBSessionManager
Unique to QBFC
List and ORList Objects

37. Building Messages Declare, instantiate session manager
Declare request message set
Create request message set object
Set request message set attributes
Repeat
Append request object
Set values of request elements and attributes

38. Set Request Message Set Attributes
Attributes property of the request message set
An object itself, with properties for each attr
Example:
Set OnError, NewMessageSetID and OldMessageSetID values
With requestMsgSet.Attributes
.OnError = roeStop
.NewMessageSetID = strNewMsgSetID
.OldMessageSetID = “0”
End With

39. Building Messages Declare, instantiate session manager
Declare request message set
Create request message set object
Set request message set attributes
Repeat
Append request object
Set values of request elements and attributes

40. Append a Request to the Message Set
Separate object types for requests
Append* methods for requests
Dim invoiceAdd As QBFC3Lib.IInvoiceAdd
Set invoiceAdd = requestMsgSet.AppendInvoiceAddRq

41. Element Objects Associated with values Standard types Methods
SetValue, SetValueAsString, SetEmpty, Unset
GetValue, GetValueAsString
IsEmpty, IsSet
GetMaxLength
invoiceAdd.RefNumber.SetValue “ ”

42. Aggregate Objects May Contain Aggregate objects Attribute objects
Element objects
List objects
ORList objects

43. 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. List and ORList Objects
List - Multiple aggregates or elements of same type
ORList – Multiple aggregates or elements of different types
Methods
Add or Append, Count, GetAt

45. List and ORList Object Examples
ListID, TxnID or FullName filters
Expense lines
ORList
Invoice line list (Item or ItemGroup Lines)
Some Query response lists
Item query response, entity query response

46. 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. QBFC Response Handling Steps
Get count of responses
Step through responses getting status
Step through response return lists if any
Check for object existence
Retrieve data for your application

48. Get Response Information
Dim response As IResponse
For i = 0 to responseMsgSet.ResponseList.Count - 1
Set response = responseMsgSet.ResponseList.GetAt(i) …
Next i

49. 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. 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. Retrieve Response Elements
txnID = invoiceRet.TxnID.GetValue
If Not (invoiceRet.RefNumber Is Nothing) Then
frmInvoiceDisplay.txtInvoiceNumber =
invoiceRet.RefNumber.GetValue
End If

52. 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. ORList Handling Lists require no type checking in your application
If invoiceRet.ORInvoiceLineRetList.GetAt(i).ortype = _
orilrInvoiceLineRet Then
‘Code to handle InvoiceLineReturn
Else
‘Code to handle InvoiceGroupLineReturn
End If
Lists require no type checking in your application

54. Append Misuse Most frequent QBFC support request
invoiceAdd.ORInvoiceLineAddList.Append.invoiceLineAdd.ItemRef.FullName.SetValue “Installation”
invoiceAdd.ORInvoiceLineAddList.Append.invoiceLineAdd.Quantity.SetValue 3
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
Immediately obvious with ToXMLString output!

55. Proper Append Use Dim invoiceLineAdd As QBFC2Lib.IInvoiceLineAdd
Set invoiceLineAdd = invoiceAdd.ORInvoiceLineAddList.Append.invoiceLineAdd
invoiceLineAdd.ItemRef.FullName.setValue "Installation"
invoiceLineAdd.Quantity.setValue 3

56. A Whirlwind Tour: SDK \ *.*

57. Several Developer Tools Available
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

58. All about Data so Far 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? …
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. Event model 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
QuickBooks admin approves subscription
QuickBooks sends event XML via COM callback

60. Other SDK Items for Consideration
Error recovery
Macros to reduce parsing effort
Data Extensions and Custom Fields
Reports – Getting the data or telling QB to display
Tools
Subscription viewer
Out of process COM wrappers to support ASP
Remote Data Sharing
Allow your App to access QB over the net
QuickBooks Online Edition
Troubleshooting tips

61. FAQ and Resources

62. SDK: Robust, real-time, two-way communication
Why not IIF?
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
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. A Roadmap to Complete Understanding

64. IDN Resources Our main web site: Developer forums: Developer Support
Developer forums:
Developer Support
3rd Party Tools
Solutions Marketplace