Preparing and sending requests

As described in Communicating with QuickBooks, applications communicate with QuickBooks by means of request and response messages. The steps for building and submitting request messages are outlined below:

Create a QBSessionManager object.

Call QBSessionManager to create an object of type IMsgSetReq – this is your request message set.

      Dim myMsgSetRequest As IMsgSetRequest
      Set myMsgSetRequest = SessionManager.CreateMsgSetRequest("US", 6, 0)

Call your IMsgSetReq object to create a request object of the type appropriate for the work to be done. The SDK provides many types of request objects; each one is specific to one QuickBooks object type (invoice, customer, etc.) and one SDK operation type (add, modify, delete, etc.).

      Dim myRequestObject As ISomeQBObjectTypeSomeOperationType
      Set myRequestObject = myMsgSetRequest.AppendSomeQBObjectTypeSomeOperationTypeRq

 #. The request objects are named according to the convention, I\ *QBObjectTypeQBOperationType*, where *QBObjectType* is the name of the QuickBooks object type, such as customer, invoice, or vendor, that the request will operate on, and *QBOperationType* is the type of operation the request object
      performs, such as add, query, etc.
 #. The methods called to create request objects are named according to the convention Append\ *ObjectTypeOperationType*\ Rq.

 The SDK provides a large number of request objects that correspond to the QuickBooks object types and operations. For a summary of the SDK's object set, see `QuickBooks objects and operations accessible with the
 SDK </app/developer/qbdesktop/docs/additional-reference/quickbooks-objects-and-operations-accessible-with-the-sdk>`__.

As needed, call setValue methods of the request object to set its fields to the values to be added, modified, deleted, etc.
1
myRequestObject.propertyName.setValue "value"
As needed, create nested “subobjects” of the main request object by calling append methods of the main request object (the names for these append methods follow the naming convention for append methods described above). The first of the examples that follow shows appending a sales order add request and then calling append methods of the sales order add request to create nested line items.
As needed, continue adding request objects and subobjects to the IMsgSetRequest object.
When all requests have been added, submit the request set to the QuickBooks request processor by calling the connection manager’s DoRequest method, in this format:
1
set ResponseMsgSet = ConnectionManager.DoRequest (myMsgSetRequest)

The examples that follow cover these steps in more detail.

For a list of QuickBooks objects and operations accessible thorough the SDK, see QuickBooks objects and operations accessible with the SDK.

Request code examples

Two examples of building a request follow, one using the QBFC classes, and the other using Microsoft’s XML (MSXML) API DOMDocument technology to build the request in QBXML.

Building a sales order add request with QBFC

The following example, in VisualBasic, follows the steps outlined above to build a request message set with a single request message. The request is to add a sales order containing two line items. The request objects used, following the naming convention described above, are ISalesOrderAdd and ISalesOrderLineAdd.

 ' Create a QBSessionManager object:
 Dim SessionManager As QBSessionManager
 Set SessionManager = New QBSessionManager

 ' Create an IMsgSetRequest object (the parameters specify US QuickBooks and the 6.0 spec):
 Dim SalesOrderSet As IMsgSetRequest
 Set SalesOrderSet = SessionManager.CreateMsgSetRequest("US", 6, 0)

 ' Create an ISalesOrderAdd object:
 Dim salesOrder As ISalesOrderAdd
 Set salesOrder = SalesOrderSet.AppendSalesOrderAddRq

 ' Set the ISalesOrderAdd object's field values:
 salesOrder.CustomerRef.FullName.setValue "John Hamilton"
 salesOrder.RefNumber.setValue "121345"

 ' Create an ISalesOrderLineAdd object as a nested subobject of ISalesOrderAdd
 Dim SOLineItemAdder As ISalesOrderLineAdd
 Set SOLineItemAdder = salesOrder.ORSalesOrderLineAddList.Append.salesOrderLineAdd

 ' Set the ISalesOrderLineAdd object's field values:
 SOLineItemAdder.ItemRef.FullName.setValue "fee"
 SOLineItemAdder.Quantity.setValue 3
 SOLineItemAdder.Other1.setValue "gold"

 ' Create another ISalesOrderLineAdd object:
 Set SOLineItemAdder = salesOrder.ORSalesOrderLineAddList.Append.salesOrderLineAdd

 ' Set the second ISalesOrderLineAdd object's field values:
 SOLineItemAdder.ItemRef.FullName.setValue "fee"
 SOLineItemAdder.Quantity.setValue 5
 SOLineItemAdder.Other1.setValue "silver"

 ' The request message set for this example is complete
 ' Open a connection:
 SessionManager.OpenConnection2 appID, appName, ctLocalQBD
 ' Begin a session:
 SessionManager.BeginSession "", omDontCare

 ' Create a IMsgSetResponse object:
 Dim SOAddResp As IMsgSetResponse

 ' Call DoRequests, passing the IMsgSetRequest object that was populated with a
 Set SOAddResp = SessionManager.DoRequests(SalesOrderSet)

 ' Display the unprocessed QBXML in the response in a message box:
 MsgBox SOAddResp.ToXMLString

 ' End the session:
 SessionManager.EndSession
 ' Close the connection:
 SessionManager.CloseConnection
 ' Clear the QBSessionManager
 Set SessionManager = Nothing

Some points to notice about this example:

The application could have created additional request objects (which could have been more ISalesOrderAdd objects, or request objects of other types, or both), fully populated them, appended them to the MessageSetRequest, and passed a MessageSetRequestcontaining multiple requests with a single call to DoRequests.
The application could have called OpenConnection and BeginSession before creating and populating the request message set; the key point is that it had to successfully make those calls before calling DoRequests.
The application could have left the session manager, connection, and session alive and made additional requests; if could also have closed the session, started another session and made additional requests. In this case, it would most likely be specifying a different company file for each session.

Building a customer add request with QBXML

Building a qbXML request and sending it to QuickBooks is simply a matter of writing out a valid qbXML string that contains the requests you want and then sending them to QuickBooks. However, because building syntactically correct XML “by hand” is so tedious and prone to error, we strongly recommend the use of a technology that does all the tedious stuff for you (angle brackets, start and end tags, and so on), so you can focus on including those qbXML elements that you want.

Our samples show the use of Microsoft XML (MSXML) API DOMDocument, a technology which is currently free from Microsoft. When you build the qbXML, you should refer to the qbXML messages reference for etails on the elements required in the request.

The following VB code example shows the qbXML for adding a new customer. To keep things simple, only a few of the available customer data fields are filled out. After building the request, the example prepends the required header information and sends the completed XML string to the request processor.

 ' Build the request XML document:
 Dim builder As New DOMDocument40
 Dim QBXML As IXMLDOMNode

 ' After the header tags write the QBXML element tag:
 Set QBXML = builder.createElement("QBXML")
 builder.appendChild QBXML

 ' Write the message set tag:
 Dim msgsRq As IXMLDOMElement
 Set msgsRq = QBXML.appendChild(builder.createElement("QBXMLMsgsRq"))

 ' Set attributes of the message set:
 msgsRq.setAttribute "onError", "continueOnError"

 ' Add the CustomerAddRq element tag:
 Dim CustomerAddRq As IXMLDOMElement
 Set CustomerAddRq = msgsRq.appendChild(builder.createElement("CustomerAddRq"))
 CustomerAddRq.setAttribute "requestID", "1"

 ' Add the CustomerAdd element tag:
 Dim CustomerAdd As IXMLDOMElement
 Set CustomerAdd = CustomerAddRq.appendChild(builder.createElement ("CustomerAdd"))

 ' Add the data element tags for first name and last name:
 Dim dataElement As IXMLDOMElement
 If firstName <> ""
    Then Set dataElement = CustomerAdd.appendChild(builder.createElement ("FirstName"))
       dataElement.appendChild builder.createTextNode(firstName)
 End If

 If lastName <> ""
    Then Set dataElement = CustomerAdd.appendChild(builder.createElement ("LastName"))
    dataElement.appendChild builder.createTextNode(lastName)
 End If

 ' The request is built except for the headers: so build these and
 ' append the request to them:
 requestXML = "" requestXML = requestXML + "" + builder.xml

 ' Create a request processor:
 Dim qbXMLRP As QBXMLRP2Lib.RequestProcessor2
 Set qbXMLRP = New QBXMLRP2Lib.RequestProcessor2

 ' Open a QuickBooks connection:
 Dim Ticket As String
 qbXMLRP.OpenConnection2 cAppID, cAppName, localQBD

 ' Begin a QuickBooks session:
 Ticket = qbXMLRP.BeginSession(qbfilename, qbFileOpenDoNotCare)

 ' Send the request, passing the requestXML built above:
 responseXML = qbXMLRP.ProcessRequest(ticket, requestXML)

 ' End the session:
 qbXMLRP.EndSession ticket

 ' Close the connection:
 qbXMLRP.CloseConnection

 ' Remove the request processor:
 Set qbXMLRP = Nothing

Some points to notice about this example:

The application could have created additional request objects (which could have been more CustomerAddRq elements, or request elements of other types, or both), fully populated them, appended them as children of the msgsRq, element and passed a msgsRq containing multiple requests with one call to ProcessRequest.
The application could have called OpenConnection and BeginSession before creating and populating the request message set; the key point is that it had to successfully make those calls before it called ProcessRequest.
The application could have left the session manager, connection, and session alive and made additional requests; if could also have closed the session, started another session and made additional requests. In this case, it would most likely be specifying a different company file for each session.