QWC Starter Kit For ColdFusion

The QWC Starter Kit For ColdFusion is a free MX 7 compatible program consisting of a simple web service which will allow you to communicate with the free QuickBooks® Web Connector from Intuit. The Starter Kit is being released to help other ColdFusion developers bypass the countless hours of head-scratching, hair-pulling and teeth-gnashing that I went through trying to get my cf_ezcart Accounting Assistant off the ground. To look at it now, it's like, why was THAT so hard? The answer to that is that the documentation is written for .NET geeks and the like.

Each call from the Web Connector contains a SOAP request. You must reply with a SOAP response. These responses contain the unique token you will create for the session, and may contain anything else from a simple string to the qbXml that will be used to actually transfer data to and from QuickBooks. What I have done is completely "Washed your hands of the SOAP". How was that for a pun? :) I give you every variable that is sent from the Web Connector and I return the variables you set. The only XML you should have to deal with is the actual qbXml that manipulates and/or queries QuickBooks data. Simply set the outgoing qbXml as a variable and we include it in the SOAP response.

Following is my "personal" overview, more or less in layman's terms, of how the QuickBooks Web Connector works. Read this, then download the application and follow the steps within the ReadMe file and you should be well on your way to building your first QuickBooks compatible application. Feel free to refer back to this page, but of course nothing replaces the documentation from the QuickBooks SDK.

1. The Web Connector can hold 1 or more services. It resides on the QuickBooks user's computer. It may be launched by itself while QuickBooks is opened or closed, or from within QuickBooks. Click to view a screenshot.
2. Every service you register with QuickBooks will be registered as a separate application. A service is registered by creating the APPNAME.QWC file, which is simply a little XML file with a qwc extension, then double clicking it while the QuickBooks Company File that you want to register it with is open. The XML within the file contains the URL to your web service and it's support page, a username, your application name, etc. So 3 web services = 3 QWC files.
3. When a service within the Web Connector window is initiated, it sends the username and password to the authenticate service, the first of 6 services you will deal with. How you use the username and password is up to you. For my cf_ezcart Accounting Assistant I use the username to specify which of the 4 services they are connecting to, and I use the password to validate the user.
4. You will respond with an XML request containing 2 strings. A unique token for the session and a string indicating to the Web Connector what to do next. If the username/password is not recognized the 2nd string will be "nvu" indicating non valid user.
5. Assuming the user was recognized, now is where you must begin your logic. You must decide if you have any new data to send to QuickBooks or if you need to check QuickBooks for new data. If so, you will reply with an empty string (or the path to the company file you wish to use if working with a closed company file). If there is no data to transfer you will respond with the string "none".
6. If you reply "nvu" or "none" in the steps above, indicating the session should end, the web connector responds by calling the closeConnection service. To this call you will respond with an appropriate string. This could be Thank You, Goodbye, whatever. I like to say something useful like 27 requests were processed in 3 minutes. This message will show up when the QuickBooks user clicks the "click for more information" link in the Status section of the Web Connector.
7. If you DO have data to transfer, the Web Connector will call the sendRequestXML service. This is where the fun begins. The qbXml you build to send to QuickBooks at this point can be anything. It can be several CustomerAdd requests to add new customers. It can be a Query request to get information on Inventory updated since the last update. Any valid qbXml is eligible.
8. Any time you send a qbXml request, the Web Connector will respond to the receiveResponseXML service with the qbXml result. Here you will perform your actions based on the result. Mark the customer as Added by adding the ListID and EditSequence returned from QuickBooks for a CustomerAdd request. Or update the prices of all Inventory items returned from the ItemInventoryQuery request.
9. If you send invalid qbXml to the Web Connector, it will reply with a message to connectionError, which you may log and review. The procedure I use is that I always log the last request. When this happens, I save just the qbXml portion of the last request to a text file and run it with the qbXml validator. This should tell you where you went wrong. The Web Connector basically gives you no feedback on why the request failed.
10. After performing any necessary actions at receiveResponseXML, you must respond with a number indicating the percentage of requests that are complete. This is likely going to be the same logic you used during authentication, except this time we are indicating our progress. If you have 50 Customers to add and you added 10 on the first request, you would enter 20 here indicating you are 20% complete. The Application Progress bar in the Web Connector will be updated to reflect this value. "100" tells the Web Connector the session is complete. It will respond with a call to the closeConnection service.
11. If you encounter an error at receiveResponseXML, a CF error, unexpected data returned from QuickBooks, any reason that you cannot continue, you must respond with a negative value. At the same time you should log the error condition. The Web Connector will respond with a call to the "getLastError" service where the error will be presented to the user. I use cfcatch to capture and write ColdFusion errors to a database where I can see it. Any other error you simply write what the problem is. This is one of the things that should be added to the Support Page. Last Error Logged. The hardest part about this development is seeing what the heck is actually going on. It's not like a typical CF site where you get feedback on errors right in your browser.

The QWC Starter Kit For ColdFusion is egoware. If it helps you, you must email us and tell us how really cool we are for building this nifty little program for you. The only 2 things you cannot do with it are:

1. You cannot build a commercial application similar to this one. In other words, you can't expand on this program and sell it. You are free to use it to build and distribute any program, either commercial or for a single client, that actually exchanges data with QuickBooks.
2. You cannot use it to build any tools that interact with cf_ezcart Shopping Cart to distribute commercially. If by chance you have a cf_ezcart customer as a client, you are free to build a single-use only program for that client.

Download QWC Starter Kit For ColdFusion

Download QuickBooks Web Connector

QuickBooks® is a registered trademark and service mark of Intuit Inc. in the United States.

Tropical Web Creations, Inc. is a member of the Intuit Developer's Network.