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.
- 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.
- 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.
- 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.
- 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.
- 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
- 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.
- 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.
- 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.
- 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.
- 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
- 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:
Good luck and happy coding,
- 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.
- 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.