Intuit Partner Platform for Ruby Web Applications

The Intuit Partner Platform (IPP) is now the preferred way for third-party SaaS applications to integrate with QuickBooks and QuickBooks Online. In this post we’ll cover how to get started integrating a Ruby web app using IPP. We’ll use Sinatra for the example app but the concept and code apply identically to a Ruby on Rails app.

A Look Back

Historically the best way for a Ruby web app to integrate with QuickBooks was through the QuickBooks Web Connector (QBWC). In 2006 I wrote a blog series (part 1, part 2, part 3, and part 4) on the Web Connector method of synchronization and even 3+ years later these posts receive a lot of traffic. One of the reasons is that this method of synchronization is still a valid and supported method. In addition, the QBWC method currently has certain advantages over IPP at the moment. However there are major advantages with using the IPP platform as well.

Comparison

This post will focus on the technical side of IPP integration. And while a full explanation of all the differences between the IPP and QBWC integration methods would take a separate detailed post, it is useful to understand some of the major differences before going further.

Important Note: This section will likely become out-of-date in regard to IPP. Intuit updates the platform frequently and it is highly recommended that this chart be verified against the current offering on their main site.

IPP Web Connector
Supported entities to sync Many (new entities being added with each release) The most
QuickBooks Online support Built-in (currently in beta-mode) Separate integration required
Authentication SAML + OAuth (open source SDKs available) Username and password
QuickBooks supported versions 2009+ 2006+ (even earlier is possible)
API programming model Always connected. Disconnected. Web app must wait for Connector to make requests.
Ability to market through Intuit Marketplace Yes Yes
Ability to market through Intuit Workplace Yes No
Billing support for integration Yes (Intuit handles billing) No
Responsibility for end-user integration support Mixed (Intuit and developers split) Developer
Approval process for integration Federated QA Checklist
Federated Security Guidelines
Partner Assessment Guidance
None
Integration cost Intuit takes a cut Free
Private applications No Yes

Getting Started

Step 0 - Review the IPP Developer Center for Federated Applications website

The IPP Developer Center for Federated Applications website provides detailed information on how to get started with an IPP integration.

Step 1 - Register as an Intuit Developer Network (IDN) developer

Complete the relatively short IDN application

Check your email for the temporary password and login.

Step 2 - Register with Workplace

Intuit Workplace is the customer-facing portal where IPP applications are marketed and sold to customers. It is a successor to the Intuit Marketplace and only developer apps that integrate with IPP can be marketed through the portal.

This registration step can be confusing because the IPP Workplace Developer Account is different from an IDN account.

Before proceeding turn-off your Flash blocker browser extension as Workplace uses Flash extensively :(

Register as an IPP Workplace developer account to start the process.

At the end of the registration cycle the browser will redirect to a developer version of workplace.intuit.com where new apps can be created.

My apps

Step 3 - Create an application

Click the “Create New” button in the top right of the page. If you don’t see this button make sure you are on the My applications page of Workplace.

New app button

Step 4 - Select application template

Select “database style”.

App style

Step 5 - Name your application

App name

After clicking OK the application dashboard will appear.

App dashboard

Step 6 - Customize application

Click Customize → Application

Customized app click

Click Advanced Settings

Advanced settings

Step 7 - Create application token

Check “Require Application Tokens” check box.

Click “Manage Application Token” link.

App token click

Click “Assign Application Token” button.

Assign token button

Check “Create New Token”, enter app name, and click OK.

Create app token

The app token should now be listed.

List app token

Return to Customize → Application → Advanced Settings screen

Step 8 - IDS Settings

Intuit Data Services provides the HTTP API for accessing QuickBooks data in the cloud. Enable access and click the “Save changes” button.

Use IDS flag

Return to Customize → Application → Advanced Settings screen

Step 9 - Generating a x.509 certificate

Follow the OpenSSL instructions in the IPP blog post titled Federated Applications: Generating your x.509 certificate in Java, OpenSSL or .Net

The following command should work fine (substitute your domain as appropriate):

$ openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout ipp_sample_app.depixelate.com.key -out ipp_sample_app.depixelate.com.crt

Generate x.509 cert

Step 10 - Request Service Provider ID for Federation

Check the “Application is Hosted Externally” checkbox and click “Get Federated Service Provider ID” link.

In the support request form:

  • Note this issue is a “Request for Federated Service Provider ID”
  • Paste your .crt file into the form
  • Include your inbound gateway url (callback url on your app)

The inbound gateway url is where your app will receive the SAML message from IPP when the app is loaded in Workplace. For this sample app we are using Heroku and we’ll choose a simple domain like https://ippsampleapp.heroku.com.

Request service provider id

Once you have submitted the support request enter the gateway url into the “Application Destination URL” box and click the “Save Changes” button.

Request service provider id

Step 11 - Wait for service provider id to be issued

Intuit will send a service provider provisioning email once the request is processed (mine was issued in 16 hours).

service provider id issued

Step 12 - Enter service provider id

Return to Customize → Application → Advanced Settings screen and update Federated Service Provider ID.

enter service provider id

Click “Save Changes” button.

Step 13 - Deploy test app

The example application is a Sinatra app and we’ll use the excellent Heroku for easy deployment. The app uses code from the Ruby SAML Gateway project to handle the SAML authentication.

Important: Substitute another app name for “ippsampleapp” in Heroku calls as that name will be taken.

$ git clone git@github.com:zackchandler/ipp_sample_app.git
$ cd ipp_sample_app
$ gem install heroku
$ heroku create ippsampleapp
$ git push heroku master
$ heroku addons:add piggyback_ssl

Now we need to setup some environment variables on Heroku that the sample app requires.

The first variable is the app db id which can be found from the Workplace admin dashboard in the url bar.

app id

$ heroku config:add APP_DBID="YOUR APP DB ID"

The application token can be found via Customize → Application → Advanced Settings → Manage Application Token link.

$ heroku config:add APP_TOKEN="YOUR APP TOKEN ID"

Pass in private key so SAML library can decrypt SAML message from IPP.

$ heroku config:add PRIVATE_KEY="YOUR PRIVATE KEY"

Step 14 - Setup QuickBooks Sync Manager and run app

Login to workplace.intuit.com on same computer as QuickBooks.

Click on app icon.

Enter the QuickBooks company name you want to sync. QuickBooks ships with two sample QuickBooks data files for a service-based business and a product-based business. They are called Larry’s Landscaping and Rock Castle Construction respectively. Use either one or your own company data.

setup company name

Click “Use My QuickBooks Data” button.

use qb data

Open company file in QuickBooks.

Click on Online Services → Set Up Intuit Sync Manager.

use qb data

Login using your Workplace credentials.

choose qb company to sync

Wait for sync to complete.

sync progress

Go back to Workplace wizard and click “Start my Application” button.

start app

If everything goes right you should see your customer list appear in the app!

customer listing

Conclusion

The Intuit Partner Platform is still young but already shows huge promise for allowing SaaS apps to quickly and securely integrate with QuickBooks data.

I hope this post is helpful to Rubyists working towards such an integration.

References

blog comments powered by Disqus