QuickBooks Integration Plugin

October 16th, 2007 • Plugins • Quickbooks • Rails

I get a lot of requests for help with Rails and QuickBooks integration. So I decided to create a plugin that can help any developer jumpstart an integration project.

Introduction

This plugin provides a webservice controller as a starting point for learning and implementing Rails/QuickBooks integration via the QuickBooks Web Connector (QBWC).

If you are just learning about QuickBooks integration you need to read and understand the QBWC Programmers Guide.

What this plugin provides

On installation this plugin creates the following files:

  • app/controllers/qbwc_controller.rb
  • app/apis/qbwc_api.rb
  • app/helpers/qbwc_helper.rb
  • test/functional/qbwc_controller_test.rb
  • config/qbwc.qwc

The QbwcController includes a very simple example of querying QuickBooks and displaying a customer list.

To implement your own QuickBooks integration, implement the functions outlined in the QbwcController according to your integration needs.

Requirements

1) Install actionwebservice gem (if it's not already installed)

sudo gem install actionwebservice

2) Add a route for the qbwc controller to config/routes.rb

# example Quickbooks Web Connector api route
map.quickbooks_api 'apis/quickbooks/api', :controller => 'qbwc', :action => 'api'

3) The QBWC will only communicate over SSL so make sure your app has a valid and trusted SSL cert installed. For testing the QBWC will speak to localhost over http.

Installation

$ ./script/plugin install http://svn.depixelate.com/plugins/quickbooks_integration

Upon installation, the template files will be copied over to your app.

If you want to copy over the template files again, use the following rake task:

$ rake quickbooks_integration:setup

Note: The rake task will not overwrite any existing files.

Development Strategies

I develop on a Mac and run QuickBooks via Parallels Desktop for Mac. To setup an development environment using a Mac + Parallels do the following:

  1. Open Windows instance in Parallels
  2. Install QuickBooks
  3. Install the QBWC

  4. Modify hosts file (c:\WINDOWS\system32\drivers\etc\hosts) to point localhost1 to Mac's IP:

    # replace IP address below with your Mac's IP address
192.168.0.3 localhost1

  5. Open a QuickBooks company file (you can use one of the QuickBooks example company files)

  6. Copy qbwc.qwc file to Windows instance and double-click to install apps configuration in the QBWC
  7. Start up Rails app with ./script/server
  8. Tail your log/development.log file to see communication cycle
  9. Check box on QBWC next to app's listing and click 'Update selected' button
  10. Watch qbxml messages sent back and forth...

Help

Getting up to speed on QuickBooks can be challenging. I would highly recommend posting questions to the excellent IDN forums if you get stuck.

References

QBWC Programmers Guide
QBXML Messages
QuickBooks SDK Manuals
IDN Forums
QuickBooks Web Connector

--- --- ---

4 Comments

  1. Comment by BJacaruso on 10/16/07
    The QuickBooks(r) Web Connector is one way to integrate with QuickBooks. It does have its drawbacks. It is not an on-demand service, in other words you have to wait for its cycle which is configured in a config file. Since it has no concept of what’s going on in the business logic of your integration, you may have some challenges creating work flow; IE: if you insert a SalesOrder and you find out the Item is out of stock on the insert, and you would like to make an additional change in QuickBooks(r) you will have to wait until the cycle comes around again. For simple inserts the Web Connector is an easy way to get to QuickBooks. And the advantage is the Web Connector is the service that initiates the call, making it easy for administrators to like. We found it was not enough for integrations that implemented full order management work flow. In our Pervasive DataSynch product we ended up building a service of our own that leverages the qbXML interface. Our service is based on a queue so we get guaranteed delivery as well as a collision free interface. We used an Apache stack to implement it so it is painless to distribute. But the best part is we can call it from our business logic that is not only located in the integration code, but from other applications, even hosted ones like Salesforce.com. We build integrations every day. What we have learned is there is always several ways to implement them. As long as it meets your needs the Web Connector is not a bad way to go. Great job on the plugin!
  2. Comment by Zack on 10/16/07
    BJacaruso: The QuickBooks Integration plugin and your product have different uses. My understanding of the DataSynch product you mention is that it only works as an integration liaison between QuickBooks and Salesforce. My plugin provides a framework for integration with any Rails-based web app. Also, you misunderstand the QBWC workflow in describing having to wait in some cases "for the next cycle" in handling a complex workflow. It is actually very easy to implement complex workflow actions in the QBWC. If the return value of the receiveResponseXML method is less than 100, the QBWC will know that there is more to process and call the sendRequestXML method for the next request. In this way it is very easy to respond to exceptions like an item being out-of-stock.
  3. Comment by Dylan Markow on 10/26/07
    I just finished a project involving the QBWC, but I would up using soap4r to generate the code off of the wsdl file. Wish this had been around when I started, awesome work! Quick heads-up: I'm sure you know, but Intuit just released v7 of the SDK. Along with it comes QBWC V2.0, which has a couple new callbacks/methods that need to be implemented (including getServerVersion, getInteractiveURL, interactiveDone, and interactiveRejected -- and it seems that even though the docs call it "getServerVersion" it's really implemented as "serverVersion"). The newest QBWC that you download from Intuit's site tries to use the serverVersion callback on every update, and I know my rails app was throwing errors because I didn't have that method implemented.
  4. Comment by Zack on 10/26/07
    Dylan: Yes... I've been playing with the new features of the QBWC 2.0 and will update the plugin at some point in the near future.

Commenting is closed for this article.