Developing requests and processing responses with the QBFC library

This page introduces the objects in the QBFC library, focusing on the objects and methods you will most often use when building request messages and processing response messages. It also shows you how to use the API reference pages to obtain the details you need to work with QBFC objects. Functionally speaking, there are two groups of objects in the library:

• Objects that your application uses to communicate with the QuickBooks request processor,
• Objects that basically model QuickBooks objects, which your applications use to send data to and receive data from QuickBooks

If you are comfortable using XML simply writing out qbXML requests may be the way for you to implement your application. However, for many programmers, QBFC provides a faster and easier way to write an application.

If you try to understand the QBFC object model by studying the individual objects, you’re in for a long day’s work. The QBFC library is a thin wrapper, which means there are a great many objects in the library, most of which model QuickBooks objects. The best way to understand the QBFC objects is to consider the way in which they are used, beginning with the central QBFC object: QBSessionManager. Applications use the session manager to

• Make the initial QuickBooks connection to the request processor
• Begin the QuickBooks session with the request processor
• Create request objects
• Send the request objects to the request processor
• Receive response messages from the request processor

This page concentrates on QBSessionManager’s role in creating and sending requests and receiving responses, because these are the operations in which your applications will be working with the large number QBFC objects that model QuickBooks objects and use them to retrieve or operate on QuickBooks data. Despite the large number of these data-modeling objects, they are similar in nature, and the procedures described here apply to all of them.

For information about the session manager’s role in opening connections and beginning sessions, see Connections, sessions and authorizations.

The following figure outlines the steps for creating and building a request message. They begin with the session manager.

1. Call the QBSessionManager’s CreateMsgSetRequest method to create an IMsgSetRequest object. This object will contain one or more request messages.

2. Call one of the IMsgSetRequest’s append methods to create an empty request object. The important point here for understanding the QBFC library is that IMsgSetRequest has a large number of append methods, one for each of the SDK’s request objects. And each of the request objects corresponds to a combination of a QuickBooks object and an operation, so there are request objects for AccountAdd, AccountModify, AccountQuery, and so on. The figure represents this by showing append methods for company query, customer add, and vendortype query. Each request object has it’s own data fields, depending on the QuickBooks object it models, but your application handles every request object in the same way.

   

3. The append methods return an empty request object. The application needs to finish building the object before sending the message set to the request processor. If, for example, the application is adding a new customer to QuickBooks, it calls AppendCustomerAddRq, which returns an empty ICustomerAdd object. The application can define the new customer by calling the ICustomerAdd’s SetValue methods to set its properties to values that describe the new customer.

Notice that the various append methods are not listed in the reference pages. If your programming environment supports Intellisense, you can see all of the Append methods in your code editor when you instantiate an IMsgSetRequest object. If you don’t have this, and don’t have an object browser that can look into the QBFC library, you can easily construct the append method name simply by applying the naming convention–at the request names listed in the reference pages: just put “Append” in front of each request name and “Rq” at the end of the request name.

Only invoke an Append method once for each desired request! Each time you invoke an Append method, you are adding a new and separate request object to the request set.

For each request in the API Reference pages, the reference provides code samples that show the construction in VB or VB.Net code.

The reference pages have the information you need to build out an empty request object. The page for an object will show the data properties that are available for the object, which of them are required, and what are the details for each property (data type, max length, and enumerated values). The figure below shows the reference page for the ICustomerAdd object.

Notice the following about information on the page:

• The object’s name is the root of the display, and appears directly under the Tag heading (ICustomerAdd, circled in this figure)
• The Tag heading refers to the fact that when the request is sent to the request processor, these properties are represented as QBXML tags.
• The properties are listed in a tree structure, indicating which are aggregates and which are leaf nodes.
• To see a definition of the property, click the property name.
• To see the property’s data structure, including enumerated values and methods for working with the property, click the data type name.

Each leaf node has a SetValue method, which the application uses to set the value of the property, subject to the datatype, max length, and list of enumerated values displayed on the reference page. The following snippet shows how this is done for a customer add object’s FirstName property:

Dim MyICustomerAdd as ICustomerAdd
Set MyICustomerAdd = MyRequestMsgSet.AppendCustomerAddRq
MyICustomerAdd.FirstName.SetValue("Fred")

The next illustration shows the enumerated values for the DeliveryMethod property, which appear when the data type name, IQBENDeliveryMethodType, is clicked. Note that the appearance of “EN” in the data type name indicates that it has enumerated values.

The IMsgSetRequest Append methods are already covered in this document and in the API Reference pages. However, the request message set object has other methods you need to know about.

The following figure outlines the steps for processing a response message. They begin with the session manager.

1. Create IMsgSetResponse object.

2. Populate the IMsgSetResponse by calling the QBSessionManager’s DoRequests method, and capturing the return in the IMsgSetResponse.

3. The important point here for understanding how to work with the QBFC library is that the actual data objects in the responses are nested within the structure of the IMsgSetResponse object. Remember that the IMsgSetRequest could have contained multiple requests, and that, therefore, the IMsgSetResponse will often contain multiple responses. Your application will want to process each response separately. The response or responses are contained in the IMsgSetResponse’s ResponseList property.

   

4. To access the data in the response, you need to work your way through the layers of nesting. First, get a handle on the response list:

1
2

Dim responseList as IResponseList
responseList = responseMsgSet.ResponseList

1. The individual responses are nested in the response list as IResponse objects. To access the individual responses in the response list, call the response list’s GetAt() method. If you are certain that the IMsgSetRequest contained only a single request message you can get the single response in a single call, like this:

1
2
3

Dim response as IResponse
response = responseList.GetAt(0)
'    ... process response

1
2
3
4
5

for i=0 to responseList.Count-1
   Dim response as IResponse
   response = responseList.GetAt(i)
' ... process response
Next i

1. A look at IResponse objects, as shown in the figure, reveals the following significant characteristics:
   • An IResponse object has some properties that report on its status–StatusCode, StatusSeverity, and StatusMessage
   • If the source request was valid, the IResponse object will have a non-empty Detail attribute, which contains the actual QuickBooks data.
   • The Detail attribute will have a data type that is appropriate for the data it holds and corresponds to the source request type. The response to an IAccountAddRq, for example, will be an IAccountRet object for example, and the response to an IAccountQueryRq will be IAccountRetList, indicating a list of Account objects.
   • Note the naming convention for the detail objects: IOBjectTypeRet or, in the case of multiple objects, IObjectTypeListRet, which is simply a list of IOBjectTypeRet.
   • As with the request objects, there are many *Ret objects, one for each QuickBooks object that can be accessed via the SDK.
2. To access the QuickBooks data in the *Ret objects, call the GetValue methods for each property of the object, according to the following pattern: data = IOBjectTypeRet.PropertyName.GetValue(). For query responses, the application will need to loop through the objects in tje *RetList and process them in sequence.
3. For code examples of processing responses see Receiving and processing responses.

The reference pages have the information you need to process a response object. For each QuickBooks object, the reference page shows both the request and response message used to work with that object via the SDK. For the response side, the *Ret object, the page will show the data properties that are returned with the object and what are the details for each property (its data type, max length, and enumerated values). The figure below shows the reference page for the IResponse object of type ICustomerRet.

Notice the following about information on the page:

• The *Ret object is the root of the display, and appears directly under the Tag heading (in this example it’s an IResponse of type ICustomerRet).
• The Tag heading refers to the fact that when the request is sent to the request processor, these properties are represented as QBXML tags.
• The properties are listed in a tree structure, indicating which are aggregates and which are leaf nodes.
• To see a definition of the property, click the property name.
• To see the property’s data structure, including enumerated values and methods for working with the property, click the data type name.

Each leaf node has a GetValue() method, which the application uses to get the value returned for the property. It should conform to the datatype, max length, and list of enumerated values displayed on the reference page. The following snippet shows how this is done for an ICustomerRet customer response object’s FirstName property:

Dim ReturnedFirstName As String
ReturnedFirstName = MyICustomerAdd.FirstName.getValue()

The following tables list the objects described in the previous paragraphs, along with the their methods and properties.

The following table shows the properties and methods for the message set response object:

The following table shows the properties and methods for the IResponseList object.

The following table shows the properties and methods for the IResponse object.