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.
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.
|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
|Integration cost||Intuit takes a cut||Free|
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.
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.
Step 4 - Select application template
Select “database style”.
Step 5 - Name your application
After clicking OK the application dashboard will appear.
Step 6 - Customize application
Click Customize → Application
Click Advanced Settings
Step 7 - Create application token
Check “Require Application Tokens” check box.
Click “Manage Application Token” link.
Click “Assign Application Token” button.
Check “Create New Token”, enter app name, and click OK.
The app token should now be listed.
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.
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
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.
Once you have submitted the support request enter the gateway url into the “Application Destination URL” box and click the “Save Changes” button.
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).
Step 12 - Enter service provider id
Return to Customize → Application → Advanced Settings screen and update Federated Service Provider ID.
Click “Save Changes” button.
Step 13 - Deploy test app
Important: Substitute another app name for “ippsampleapp” in Heroku calls as that name will be taken.
$ git clone firstname.lastname@example.org: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.
$ 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.
Click “Use My QuickBooks Data” button.
Open company file in QuickBooks.
Click on Online Services → Set Up Intuit Sync Manager.
Login using your Workplace credentials.
Wait for sync to complete.
Go back to Workplace wizard and click “Start my Application” button.
If everything goes right you should see your customer list appear in the app!
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.
- IPP website
- IPP Federated Applications Guide
- Intuit Data Services Programming Guide
- IPP Blog post on generating x.509 certificates for federated applications
- Intuit Workplace
- Intuit Marketplace
- ipp_sample_app on Github
- IDN Forums
- QuickBooks Web Connector
- Ruby SAML Gateway project
- Ruby on Rails