Upload
kristina-bridges
View
237
Download
10
Embed Size (px)
Citation preview
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 [email protected]
o 3rd Party Tools http://developer.intuit.com/QuickBooksSDK/Resources/?
id=97
o Solutions Marketplace http://marketplace.intuit.com