Lesson 4: QuickBooks Desktop Integration - High Level SOAP Service Actions

You Have To Build A SOAP Server

Let's jump right into this SOAP server you are going to be constructing and discuss it at a high level. Moreover, let's start to look at some code too. The code I'll be going to be going over for the rest of the lessons is based on my private gem called QBSDK. However, when I personally do an integration I do not use the gem directly but instead put the core gem code directly into the Rails app as a first-class citizen. The reason is that I want to be as "close to the metal" as possible on an integration project because flexibility is key for a successful integration. In my projects I only use a generic SOAP server library called wash_out. You also, depending on your tech stack, should pick out a mature SOAP server library. What you need to avoid is a "full stack" QBD integration library such as the QBWC gem (in the Ruby ecosystem) because again, I feel it is vital to the success of your integration project if you (and the rest of the team) understand at a "low level" what is going on.

The QBSDK Gem

Your First SOAP Action

Let's take a look at the WSDL, which the washout gem automatically generates. Note: you also are going to need to generate all of these WSDL actions exactly I'll be specifying them. Remember that the QuickBooks Web Connector (QBWC) will ping your SOAP server (we'll refer to this as a "session") and the first thing it's going to ask for is a "serverVersion" (see Fig. 1). A QBWC session has a life cycle of SOAP Server actions, which will be discussed in this article.

You then need to send back a response for the serverVersion request. I just send back a "blank" response. Same with the "clientVersion" action, which is the next request/response step in the QBWC session. You then send back a client version response, which again, I just send back a blank response. I have all these responses in the code which are partial displayed in Figure 1. I'll be going into these actions in detail later, but let's continue on at a high level.

The Core Actions

The first two actions are benign so let's move on to the core actions. With these actions we now have to do something meaningful. First, is the "authenticate" action. I'm not going to show you what to do exactly for authentication in this lesson so let's keep moving. Next, we have the "sendRequestXML" action. This can be a query, an add, or a modify request. There will be many more details on this action in later lessons.

The Receive Response

The receiveResponseXML action and its response get a little interesting in that when you provide the receive response you must return a progress indicator that is an integer, 1 through 100. If your progress is anything less than 100 the QBWC session is sent back to the sendRequestXML action, creating a loop. If you send back 100 that means there is no more work to do and the QBWC session will close by being sent to the closeConnection action.

So with a progress of less than 100 you just keep on looping until you give a progress of "100" or a "-1" is returned. Negative one means an error, which will send the QBWC session to the getLastError action. This looping effect means that you're going to be creating a queue and constructing that queue properly is vital and will be discussed in detail later.

Conclusion

That gives you a high level of what's going on in these SOAP actions during a QBWC's session life-cycle. In the next lessons, we'll be diving into the details of each core action.