1 / 64

QuickBooks SDK Essentials

QuickBooks SDK Essentials. Peter A. Vogel Developer Support Supervisor Intuit Developer Network. Agenda. Overview of the SDK Communicating with QuickBooks Rubber to the Road – Demo The Gory Details A Whirlwind Tour: SDK *.* FAQ and Resources. Overview of the SDK. SDK Design Principles.

renate
Download Presentation

QuickBooks SDK Essentials

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  1. QuickBooks SDK Essentials Peter A. VogelDeveloper Support SupervisorIntuit 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 (2002-2004…) • Enterprise Solutions • All flavors • Premier • All flavors • Pro • Canada (2003-2004…) • Online Edition • Since Nov. 2002

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

  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 • 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) • 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 • CloseConnection • 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- <CustomerRef> <ListID>A40000-1071505981</ListID> </CustomerRef>

  27. Use of Ref Aggregates

  28. 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, … qbXML Basics

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

  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 “0013672”

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

More Related