Minimul: a QuickBooks integration expert

Migrating a QuickBooks Online App from OAuth1 to OAuth2 using the qbo_api gem - Step 3

2019-11-08T00:00:00Z

Show notes:

In short this tutorial is about creating OAuth2 access tokens given that you have valid OAuth1 tokens using the Migration API.
To see the Qbo::OAuth2.migrate! code see the Step 2 article.

lib/tasks/quickbooks.rake


namespace :quickbooks do

    task :oauth2_migrate => :environment do
        qbo_accounts = QboAccount.all
        qbo_accounts.each do |qbo_account|
            next unless qbo_account.id == 3 # Remove this line later of course
            begin
                Qbo::OAuth2.migrate!(qbo_account)
                puts "SUCCESS_OAUTH2_MIGRATION_FLAG: qbo_account_id: #{qbo_account.id}"
            rescue => e
                puts "FAILED_OAUTH2_MIGRATION_FLAG: qbo_account_id: #{qbo_account.id} error_message: #{e.message}"
            end
        end
    end
end

Migrating a QuickBooks Online App from OAuth1 to OAuth2 using the qbo_api gem - Step 2

2019-11-06T00:00:00Z

Show notes:

Add gem 'rack-oauth2' to Gemfile
Enable OAuth2 on your app at https://developer.intuit.com and set the redirect URI and grab the client_id and client_secret.

Initial OAuth2 Setup

config/routes.rb

  get '/oauth2-redirect', to: 'visitors#oauth2_redirect'

app/models/qbo/oauth2.rb

app/controllers/visitors_controller.rb


class VisitorsController < ApplicationController  skip_before_action :authenticate_user!, :except => [:oauth2_redirect]

    def oauth2_redirect
        qbo_account = current_account.qbo_account
        if params[:state] == session[:oauth2_state] && qbo_account
            client = Qbo::OAuth2.client
            client.authorization_code = params[:code]
            if resp = client.access_token!
                attrs = {
                    access_token: resp.access_token,
                    refresh_token: resp.refresh_token,
                    companyid: params[:realmId]
                }.merge(Qbo::OAuth2.expires_in)
                qbo_account.update!(attrs)
                msg = "Your QuickBooks account has been successfully linked."
                flash[:inner_notice] = msg
                render 'shared/close_and_redirect', layout: 'basic'
            end
        end
    rescue => e
        @url = account_url(current_account)
        msg = "There was a problem linking Your QuickBooks account - given an error: #{e.message}"
        logger.warn msg
        flash[:alert] = msg
        render 'shared/close_and_redirect', layout: 'basic'
    end
end

app/controllers/application_controller.rb

  
def set_oauth2_state
    session[:oauth2_state] = Rails.env.test? ? '3242adf32423kjo' : SecureRandom.uuid
end
helper_method :set_oauth2_state

config/initializers/inflectors.rb

ActiveSupport::Inflector.inflections(:en) do |inflect|  
  inflect.acronym 'OAuth2'
end

view code


<% content_for :script do %>
  intuit.ipp.anywhere.setup({ grantUrl: '<%= Qbo::OAuth2.authorize_url(state: set_oauth2_state).html_safe %>',
                              datasources: { quickbooks : true, payments : false }
                            });
<% end %>

Migrating a QuickBooks Online App from OAuth1 to OAuth2 using the qbo_api gem - Step 1

2019-10-24T00:00:00Z

OAuth2 Renewal Strategy

The QuickBooks Online API OAuth2 access token's are only good for 1 hour. This is a radical departure from OAuth1's 6 month expiry duration. With that short a window probably the best way to ensure uninterrupted usage is to utilize a code pattern for all QBO request that does the following:

Catches "Unauthorized" errors (status code 401 — i.e. an invalid access token).
Next, automatically renews and persists the access token.
Lastly, replays the failed 401 request.

In the screencast, I'll be focusing on this approach. See the show notes below for an example code pattern that will make OAuth2 renewal and persistence automatic. Note: The code pattern below requires customization for your particular situation.

Scheduled Renewal Job?

With OAuth1's one month renewal window you could rely on a background scheduler like Cron but with the OAuth2's super short renewal duration, relying solely on Cron may not be best because in the case that your app or the QBO API has an outage when either service returns it may take considerably longer to get QBO requests flowing again. I talk more about going with a background scheduler strategy here.

Show Notes:

Update the qbo_api gem to the latest.
Refactor your QuickBooks Online API requests in to the "request_handler" pattern as seen below. The qbo_account, record, and payload ideas are specific to my app that I'm switching over to OAuth2. Please watch the screencast to get the proper context.


module Qbo
    class Base

        def self.request_handler(qbo_account_id:, payload: false, record: false)
            retries ||= 0
            qbo_account = QboAccount.find(qbo_account_id)
            api = Qbo.init(qbo_account)
            yield(api)
        rescue QboApi::Unauthorized
            if qbo_account.access_token.present?
                Qbo::OAuth2.renew(qbo_account)
                retry if (retries += 1) < 3
            else
                register_error(qbo_account: qbo_account, error: '401 Authentication Error', payload: payload)
            end
        rescue QboApi::Error => e
            if err = e.fault
                if record
                    fix_duplicate_customer(qbo_account: qbo_account, record: record, error: err, payload: payload, qbo_api: api)
                else
                    final_err = error_body(err)
                    register_error(qbo_account: qbo_account, error: final_err, payload: payload)
                end
            end
        rescue => e
            final_err = e.to_s[0..255]
            qbo_account.account.qbo_errors.create(body: final_err, request_json: payload.to_json, account: qbo_account.account)
            raise e
        end

        def self.entity_handler(qbo_account_id:, entity:, record:, payload:)
            request_handler(qbo_account_id: qbo_account_id, record: record, payload: payload) do |api|
                if id = record.qbo_id
                    res = api.update(entity, id: id, payload: payload)
                else
                    res = api.create(entity, payload: payload)
                    record.update(qbo_id: res['Id'])
                end
                res
            end
        end

        def self.fix_duplicate_customer(qbo_account:, record:, error:, payload:, qbo_api: api)
            if record.class.name == "Customer" && error[:error_body][0][:error_message] == 'Duplicate Name Exists Error'
                if res = qbo_api.get(:customer, ["DisplayName", record.display_name])
                    record.update(qbo_id: res['Id'])
                else
                    register_error(qbo_account: qbo_account, error: error, payload: payload, resource: record)
                end
            else
                register_error(qbo_account: qbo_account, error: error, payload: payload, resource: record)
            end
        end

        def self.register_error(qbo_account:, error:, payload:, resource: false)
            qbo_account.account.qbo_errors.create(body: error[:error_body], method: error[:method], resource: resource,
                                                                                        url: error[:url], status: error[:status], request_json: payload.to_json) 
        end

        def self.error_body(err)
            if body = err.try(:[], :error_body)
                result = body.map{ |b| b.try(:[], :error_detail) || b.try(:[], :error_message) }.join(" -- ")
            else
                ""
            end
        end
    end
end

  
module Qbo

  def self.init(qbo_account)
    if qbo_account.access_token.present?
      attrs = {
        access_token: qbo_account.access_token,
        realm_id: qbo_account.companyid
      }
    else
      attrs = { 
        token: qbo_account.token,
        token_secret: qbo_account.secret,
        realm_id: qbo_account.companyid,
        consumer_key: Rails.application.secrets.qbo_app_consumer_key,
        consumer_secret: Rails.application.secrets.qbo_app_consumer_secret
      }
    end
    QboApi.new(attrs)
  end

end

Lesson 9 - QuickBooks Desktop Integration Setup - QBWC Verbose Logging

2019-10-02T00:00:00Z

Lesson Notes:

Protip: If you're dev environment is MacOS or Linux OS and you miss your command line tools when hacking around in Windows 10 you can install the Ubuntu subsystem.
Here is how to turn on verbose logging.
Understanding QBXML Verbose Logs.

Lesson 8 - QuickBooks Desktop Integration: Using the SDKTestPlus3 Tool

2019-09-28T00:00:00Z

Lesson Notes:

Here is the link for the SDKTestPlus3 Tool.

It is great tool for quickly troubleshooting QBXML requests and responses as it gives a "close to metal" experience.
I also use the tool from time to time for creating test fixtures.

The tool is automatically installed during QBSDK installation.
To find it easily type "sdk" in the Window search bar. The name of the SDK tool is "qbXML Test+".
Quickly find the SDKTestPlus3 Tool.
To get started, load in a sample QBXML query that was provided when the QBSDK was installed.
Sample QBXML files can be found in C:\Program Files (x86)\Intuit\IDN\QBSDK13.0\samples\xmlfiles directory.
I'm going to use QBXML that adds an Invoice to QBD.
If the QBXML request was successful it will say so in the "Status" box.
Here is what QBXML Response looks like:
When seleting the 'View Output' button ou get the QBXML response (when the request was successful).
Make sure that when submitting transaction requests, like an add invoice request that you have "real" required references, like the CustomerRef in the request below (meaning the the customer being referenced is a real QBD customer).
You're going to be doing a lot of QBXML hacking so have a good editor — like Vim :)
Using the SDKTestPlus3 Tool I made a real QBD invoice.
Here is a look at the QBD Invoice I made from the above QBXML.

Lesson 7 - Install The QuickBooks Desktop SDK

2019-09-16T00:00:00Z

Lesson Notes:

Additional Software you'll need to install on the Windows guest VM for QuickBooks Desktop.

Alternate browser like Firefox or Chrome if you don't dig Edge or IE.
A good text editor for hacking XML.

You may want to use Intuit's sample company files instead of creating your own because they come populated with name list (customers, vendors, items, etc) and transaction (invoices, sales receipts, etc) entities.
QBD comes with sample company files preloaded with data.
Download and install the QBSDK.
If your dev environment is OSX or Linux you are going to need to do some host file hacking.
This topic is explained starting around the 2:01 mark.

Search for the Windows console (cmd.exe) app.
Right-click the cmd.exe and select "Run as Adminstrator".
Paste in this command: notepad.exe C:\Windows\System32\drivers\etc\hosts
Using ifconfig to get your OSX or Linux IP Address.
Create an entry in the Windows host file like so: 192.168.1.45 localhost.test

My local address is 192.168.1.45 and I use a static DHCP address so it doesn't change.

Save and exit the host file — these local DNS changes will take place immediately on Windows.

Minimul says —

The QuickBooks Web Connector can only establish a SOAP server connection to an "https" enabled SOAP server or if there is "localhost" somewhere in the hostname than it can just be a plain "http" connection so that is why I use localhost.test.
This topic is explained starting around the 4:01 mark.
Lastly, make sure you bind your local (on OSX/Linux) SOAP web application server to 0.0.0.0. For example, for Rails I run this command bundle exec rail s -b 0.0.0.0 or you will not be able to communicate from the Windows VM to your local SOAP dev environment.

Lesson 6 - Install QuickBooks Desktop via VirtualBox

2019-09-14T00:00:00Z

Run QuickBooks Desktop No Matter Your OS

In the last lesson, I discussed obtaining a copy of the QuickBooks Desktop Not For Resale (NFR) version. In this lesson, I'll teach you how to install QuickBooks Desktop even if you don't use Windows for development. To demonstrate, I'll be use the free and excellent VirtualBox so I can run Windows and therefore QuickBooks within MacOS. In my particular case, I have two Windows OS VirtualBox instances but you'll only need one.

My VirtualBox Windows Instances

This section is at the 0:28 mark.

I have a Windows 7 instance (with IE 10 and QuickBooks Desktop Pro) and I have a Windows 10 instance (with IE 11 and QBD 2018). For both of these instances I purchased real Windows CD keys.

Getting Affordable Windows CD Keys

There are legitimate sites that sell CD keys for OEM versions of Windows. I believe I got that latest key for like $12 and I did check around to see if the site was legit and it was. Sadly, I forgot which site is was and I couldn't find the email receipt. These sites buy OEM keys in volume so the prices are low. The catch with an OEM is that you can only install them one time, which is not a drawback in this scenario where you're only using Windows for testing within a virtual machine.

Conclusion

After getting the Windows OEM key, use one of the many online tutorials for installing Windows on VirtualBox. After installing Windows within VirtualBox you'll download and install QuickBooks Desktop via the NFR link(s) that Intuit provided for you. That's all for this lesson. In the next lesson we'll install the QuickBooks SDK.

Lesson 5 - Install QuickBooks Desktop Not For Resale (NFR) Copy

2019-09-11T00:00:00Z

But I Don't Have QuickBooks Desktop?

Let's talk about actually getting a copy of QuickBooks Desktop (QBD) up and running. If you're on Windows, this is going to be a lot easier. I'm on a Mac so these upcoming lessons should work fine on Linux as well. If you're on Windows, skip ahead to the lessons that are going to be relevant for you. But stay here right now, because what I'm going to talk about is this NFR stuff in a general way.

What is the Not For Resale Version?

Because you're watching this you are now an official QuickBooks developer and you can get a NFR (Not For Resale) copy of QuickBooks Desktop (not that I remember having to provide a reason for requesting the QBD NFR but you might have to). A QBD NFR copy is simply a version that is intended for testing and trial purposes only.

Obtaining The NFR

First, you got to get an Intuit developer account if you don't have one. Then go to the NFR page and call them up. Back in 2013, I paid like $300 to get a NFR subscription but I'm pretty sure that it is free nowadays. QuickBase, the Intuit subsidiary, is the company that you'll actually be talking to.

What version?

When requesting a NRF they're going to ask you what version you want. There are many versions of QBD, such as of Point of Sale, UK/Canadian versions, Premiere, Enterprise, Pro, Manufacturing, etc. Moreover, each version has a "year'd version" such as QuickBooks 2016 Pro. So of the older year'd versions may be in use by your customers. But don't fret too much, The QuickBooks Web Connector (QBWC) is mature technology and will work seamlessly across them. Truth is that QuickBooks Desktop has not changed much recently and you don't have to run and test each year'd version. Of course, if your user base is primarily in the manufacturing sector then grab a copy of 2019 QBD Manufacturer. There'll probably be a couple of GUI differences here and there but GUI differences shouldn't effect your integration aims, which most likely will revolve around basic syncing activities of name lists and transactions. These standard requests and responses you'll be performing are going to work fine across all QBD versions and year'd versions. QBD Pro, Premiere, or Enterprise, generally speaking, is what most of your customers will be running but don't complicate things right now and just pick one of them for the year 2019.

This section is at the 0:50 mark.

Conclusion

This lesson explains how you can get a NFR copy if you don't already have a copy of QBD. If you do have one, great, then you don't need to go through this step. The next lesson is going to involve installing the QBD NFR with VirtualBox so if you're a Windows user you can skip that lesson.

Lesson 4: QuickBooks Desktop Integration - High Level SOAP Service Actions

2019-09-07T00:00:00Z

You Have To Build A SOAP Server

Let's jump right into this SOAP server you are going to be constructing and discuss it at a high level. Moreover, let's start to look at some code too. The code I'll be going to be going over for the rest of the lessons is based on my private gem called QBSDK. However, when I personally do an integration I do not use the gem directly but instead put the core gem code directly into the Rails app as a first-class citizen. The reason is that I want to be as "close to the metal" as possible on an integration project because flexibility is key for a successful integration. In my projects I only use a generic SOAP server library called wash_out. You also, depending on your tech stack, should pick out a mature SOAP server library. What you need to avoid is a "full stack" QBD integration library such as the QBWC gem (in the Ruby ecosystem) because again, I feel it is vital to the success of your integration project if you (and the rest of the team) understand at a "low level" what is going on.

This section is at the 0:10 mark.

The QBSDK Gem

Service Action Code from the QBSDK Gem.

Your First SOAP Action

Let's take a look at the WSDL, which the washout gem automatically generates. Note: you also are going to need to generate all of these WSDL actions exactly I'll be specifying them. Remember that the QuickBooks Web Connector (QBWC) will ping your SOAP server (we'll refer to this as a "session") and the first thing it's going to ask for is a "serverVersion" (see Fig. 1). A QBWC session has a life cycle of SOAP Server actions, which will be discussed in this article.

The First SOAP Server Action - The Server Version.

You then need to send back a response for the serverVersion request. I just send back a "blank" response. Same with the "clientVersion" action, which is the next request/response step in the QBWC session. You then send back a client version response, which again, I just send back a blank response. I have all these responses in the code which are partial displayed in Figure 1. I'll be going into these actions in detail later, but let's continue on at a high level.

This section is at the 2:00 mark.

The Core Actions

The first two actions are benign so let's move on to the core actions. With these actions we now have to do something meaningful. First, is the "authenticate" action. I'm not going to show you what to do exactly for authentication in this lesson so let's keep moving. Next, we have the "sendRequestXML" action. This can be a query, an add, or a modify request. There will be many more details on this action in later lessons.

The Core Actions

This section is at the 3:05 mark.

The Receive Response

The receiveResponseXML action and its response get a little interesting in that when you provide the receive response you must return a progress indicator that is an integer, 1 through 100. If your progress is anything less than 100 the QBWC session is sent back to the sendRequestXML action, creating a loop. If you send back 100 that means there is no more work to do and the QBWC session will close by being sent to the closeConnection action.

So with a progress of less than 100 you just keep on looping until you give a progress of "100" or a "-1" is returned. Negative one means an error, which will send the QBWC session to the getLastError action. This looping effect means that you're going to be creating a queue and constructing that queue properly is vital and will be discussed in detail later.

How A "Loop" Is Created.

This section is at the 4:15 mark.

Actions for Closing A QBWC Session

Conclusion

That gives you a high level of what's going on in these SOAP actions during a QBWC's session life-cycle. In the next lessons, we'll be diving into the details of each core action.

Lesson 3: QuickBooks Desktop Integration - High-level overview of QBXML

2019-09-05T00:00:00Z

QBXML and Its Bible

In the last two lessons I talked about creating a SOAP server that talks to the QBWC, which is a SOAP client. Next, we'll discuss by which means or protocol does this client and server speak to each other. This means is a simple text protocol called QBXML. The best way to learn about QXML is through its bible, the QBSDK On-Screen Reference or OCR. You're always going having this reference open so go ahead and open it up now and start clicking around. As of this writing, the latest QBSDK version is 13.

This section is at the 0:10 mark.

Using the QBSDK OCR

Diagram demonstrating using the QBSDK OCR.

Minimul says —

You'll notice the "QBFC" option on the OCR but that is beyond the scope of this class, I'll just be focusing the QuickBooks Web Connector which uses QBXML.

QBSDK is an umbrella term that is exclusive to QuickBooks Desktop integration and is not related to integrating with QuickBooks Online. I say umbrella term, because it is really a group of technologies you're going to have implement and QBXML is one of those pieces. As you can see from browsing around the OCR that support is mature and you're most likely going to be able to achieve your integration goals.

I believe version 13 of the QBSDK came out in around 2013 so it's unlikely that any of your customers are not going to qualify for version 13, meaning they're definitely going to be using a QuickBooks Desktop version beyond 2013.

Use the XMLOps tab to see the raw QBXML.

This section is at the 2:23 mark.

Conclusion

QBXML is at the heart of QBD integration and it is the means of communicating with the QuickBooks Web Connector. In the next lessons I'll be diving more in-depth around create and serving up QBXML via the SOAP server you're going to be building.

Lesson 2: QuickBooks Desktop Integration - SOAP Server Strategy

2019-08-23T00:00:00Z

SOAP Server - Don't Use An Existing Library

Now that you know that you need to make a SOAP server on your end to talk to the QBWC, what kind of strategy should you go about making and constructing this SOAP server? I am going to go against conventional wisdom and recommend throughout the entire training series that you do not use an "off the shelf" QuickBooks desktop integration framework or library from your particular tech stack. I'm going to advocate that you bake this integration right in to your web application code. You're gonna want to talk to the database at a very intimate level. Moreover, you're going to have a lot of edge cases, error reporting and other things that make it very difficult for a generic library to handle. In fact, I have not even released this "library" that you're going to see through out this series and when I do an integration I pull it right into the application itself. So I practice what I preach.

This section is at the 0:22 mark.

Minimul says —

Really, Don't Use an Existing Library?

You're not going to be doing a QuickBooks desktop integration many times — you're going to do this one time and you're gonna need to do it right too. You want this to actually work and your customers to be happy. To do a solid QuickBooks desktop integration you are going need to be close to the metal. In short, you need to know what's technically going on. You are not going to be able to outsource that to a generic library. Chances are if you use an off-the-shelf library you'll end up re-writing most of the thing anyway.

This section is at the 1:14 mark.

Conclusion

The only library you going to want to start with is a generic SOAP server library. From there you are going to build each of the SOAP actions directly into your app. In the upcoming lessons you'll see how to do just that.

Lesson 1: High Level Overview Of The QuickBooks Web Connector (QBWC)

2019-08-22T00:00:00Z

What is the QuickBooks Web Connector?

Let's talk at a high level about what the QuickBooks Web Connector (or QBWC) is and how it provides integration to QuickBooks Desktop (QBD). Take a look at Figure 1 as well. First, know that QuickBooks Desktop only runs on Windows and it is sort of like a program in and of itself. It acts like a middleware agent that will talk to your web app server, which you must configure as a SOAP server. You can create an integration between your app and QB Desktop using COM objects as well but that is beyond the scope of these lessons.

This section is at the 0:22 mark.

Diagram demonstrating how the QBWC works.

QBWC is a SOAP Client

On your end you have to create a SOAP sever because the QBWC is SOAP client. SOAP is an acronym for Simple Object Access Protocol, which is a protocol that sends text back and forth so you can integrate two systems no matter the operating systems. In the case of QBWC it is just XML going back a forth.

How is the QBWC Setup?

So how do you get your SOAP server to talk to the QBWC? Through a "application file" (.qwc file) that you would have to set up. That will be another another lesson, but in short you provide a URL for connecting to your SOAP server (I'll be helping you create this SOAP server in other lessons) and some other parameters. Every two minutes (this is the default but this duration can be adjusted higher), the QBWC kicks up and goes out to ask the SOAP server if it has anything for it to do.

This section is at the 2:20 mark.

Then What?

You would make a queue on your SOAP server with different things for the QBWC to do. Let's say you wanted to know if certain payments in QuickBooks Desktop have now been put in the Deposited Funds chart of account. Your app puts something on the queue asking to query QB Desktop (via the QBWC) for recent payments and what chart of accounts they are in. Or if you wanted to make a customer on your app and then make it on QBD also you would put that request on the queue and on the next two minute run you'll have a customer in QBD. Simple, right? Maybe to explain but not in practice but remember, I'm here to help but again that'll be in another lesson.

This section is at the 3:00 mark.

Conclusion

That's the QBWC in about 3 minutes and instead of being a high-level overview it probably feels more like a 10,000 foot view. Don't worry, there are over 30 lessons in the master class series and every aspect of doing a proper integration will be gone over in detail.

QuickBooks Desktop Integration Master Class Is Here!

2018-11-16T00:00:00Z

My Master Class on QuickBooks Desktop Integration via the QuickBooks Web Connector is now done.

The video portion of the class is completely free!

Don't go it alone. QuickBooks Desktop Integration is very unorthodox. My hands on consulting options will help you and your team go fast and you'll have an integration that will not need to be rewritten after 6 months of rookie mistakes that could have easily been avoided by enlisting me as your guide.

QuickBooks Desktop Integration Training Coming Soon

2018-11-16T00:00:00Z

I am working on a QuickBooks Desktop Integration via the QuickBooks Web Connector training course that I hope to have done by the end of the year. I am going to make it relevant no matter what tech stack you are on.

Getting Started With The Xero Api Gem

2018-11-02T00:00:00Z

Why Another Ruby Xero Gem?

I am slated to begin a Xero integration soon and I took a preliminary look-see. There is quite a bit in common with QuickBooks Online with regards to resources and entities, however, when I started looking closely at the Ruby-Xero gems the current crop of de facto ones were very old, being written at a time when the Xero API was XML only.

This is the same kind of thing that plagued the quickbooks-ruby gem. When constructing an API client to a XML-only endpoint a lot of "cruft" can start to accumulate depending on how you approach building the XML payloads.

Therefore, I built a new Ruby-Xero client that is pure JSON-in, JSON-out and certified to be 100% anti-cruft. Ok, maybe 95% 😇

How Much Anit-Cruft?

Here are the line count totals (of .rb files):

Total LOC count of :
- minimul/xero-api => 910! 🚀
- waynerobinson/xeroizer => 6019
- xero-gateway/xero_gateway => 5545

Get Started Hacking Xero With xero-api

This section is at the 1:30 mark of the screencast. 🎥

Follow and do all in Step 1 from the Getting Started Guide.
git clone git://github.com/minimul/xero-api && cd xero-api
bundle
Create a .env file
1. cp .env.example_app.oauth1 .env
2. Edit the .env file values with consumer_key and consumer_secret.
Start up the example app => ruby example/oauth.rb
In browser go to http://localhost:9393.
Use the Connect to Xero button to connect to your Xero account.
After successfully connecting click on the displayed link => View All Customers
Checkout example/oauth.rb to see what is going on under the hood.
- Important: In the /auth/xero/callback route there is code there that will automatically update your .env file.

Once your .env file is completely filled out you can use the bin/console test to play around

This section is at the 5:29 mark of the screencast. 🎥

bin/console test
>> @xero_api.get :contacts, id: '5345-as543-4-afgafadsafsad-45334'

QuickBooks Connect and Intuit Sign on Buttons in SVG

2018-04-10T00:00:00Z

SVG (plus some tweaking) = Responsive

I got tired of dealing with raster image versions when building responsive views. With SVG browser support having fully arrived it was time to not wait for Intuit and go ahead and get their buttons into the future.

When downloading Intuit's buttons .zip file I noticed that they included an .eps file(s) covering of all the raster image kinds. I converted the .eps files into .svg counterparts and imported that into the awesome Gravit Designer.

From these Gravit Designer source files I created the individual .svg source files and built a Rails plugin.

Demo please

See the demo page and scale the width to see how well these buttons adjust.

The qbo_buttons gem demo page.

I'm not Riding Rails

If you are not on the Rails tech stack, no problem, just grab the Gravit source files or the individual .svg files from the qbo_buttons gem and build your own solution.

Test for QuickBooks API TLS 1.2 support

2017-12-22T00:00:00Z

Intuit is requiring QBO API connections to be done over TLS 1.2 or greater starting on December 31st, 2017. In this article, I'll show you how to test the 2 main QuickBooks Ruby libraries, quickbooks-ruby and qbo_api.

Notes:

# Rails console for app you want to test
# FOR QboApi gem.
# 1. instantiate a QboApi object
$ qbo_api_instance.connection(url: 'https://www.ssllabs.com/ssltest/viewMyClient.html').get
# FOR quickbooks-ruby gem
# 1. instantiate a quickbooks-ruby object
$ quickbooks_ruby_instance.service.send(:do_http_get, 'https://www.ssllabs.com/ssltest/viewMyClient.html')
# Search the HTML output using the search string 'protocol_tls1_2' and see if you get a "Yes*"
# e.g. successful fragement => \"protocol_tls1_2\">Yes*</td>\

Modify the QuickBooks Online Interface with a Chrome Extension

2017-10-25T00:00:00Z

Hacking the QuickBooks Online UI

On a recent client project I had been regularly monitoring the QBO sandbox audit log to make sure we were getting the proper results before going live. To validate these results I thought of providing a CSV file of the audit log table to my client's accounting staff.

At first I was just cutting and pasting some JavaScript functions into the Chrome developer tools but that got old and time consuming so instead I just built a full-fledged extension, remarkably called "QBO Audit Log to CSV".

This is not a public released Chrome extension and it is only available at my Github repo.

The extension adds these 2 links to the Audit Log view only.

I did not officially release the extension on the Chrome Web Store so if you want to use it you'll have to follow the instructions in the next section.

Getting started

You are going to need the latest Node version.

$ mkdir ~/chrome-ext
$ git clone git@github.com:minimul/qbo-audit-log-to-csv.git
$ cd qbo-audit-log-to-csv
$ npm install

In a separate terminal run gulp watch.
Open up Chrome and go to chrome://extensions.
Check "Developer mode:" ✔︎
Click "Load Unpacked Extensions"
And navigate to the /app directory e.g. ~/chrome-ext/qbo-audit-log-to-csv/app

Here are the main points of note when setting up the extension.

Now you can open qbo.intuit.com/app/auditlog or sandbox.qbo.intuit.com/app/auditlog and you'll see the 2 links from Fig. 2.

This section is at the 2:20 mark.

Modifying the UI

The 3 main scripts that do all the work are: app/scripts.babel/background.js; app/scripts.babel/contentscript.js; and /manifest.json. I'll briefly discuss these files and some of things to take note of.

Minimul says —

The gulp watch command will automatically compile the files in the /app/scripts.babel directory to the /app directory whenever there is a file modification.

The manifest.json file

This is your config and setup file. Here is the manifest.json file for the QBO Audit Log To CSV extension.

{
  "name": "QboAuditLog to CSV",
  "version": "1.0.0",
  "manifest_version": 2,
  "description": "QboAuditLog to CSV",
  "icons": {
    "128": "images/128-icon.png"
  },
  "default_locale": "en",
  "background": {
    "scripts": [
      "scripts/chromereload.js",
      "scripts/background.js"
    ]
  },
  "permissions": [
    "tabs",
    "webNavigation",
    "https://*.intuit.com/*/*"
  ],
  "content_scripts": [
    {
      "matches": [
        "https://*.intuit.com/*/*"
      ],
      "js": [
        "scripts/contentscript.js"
      ],
      "run_at": "document_end",
      "all_frames": false
    }
  ]
}

In this file you determine which scripts are "background" and "content_scripts". You set permissions and determine what URL pattern the extension will run against. As you can see only permissions for "tabs" and "webNavigation" were needed.

The background.js file

The background.js file is a bit hard to explain so here is its definition according to the docs

❝

A common need for extensions is to have a single long-running script to manage some task or state.

Background pages to the rescue.

As the architecture overview explains, the background page is an HTML page that runs in the extension process.

It exists for the lifetime of your extension, and only one instance of it at a time is active. (Exception: if your extension uses incognito "split" mode, a second instance is created for incognito windows.)

❞

Let's take a look at the extension's background.js.

'use strict';

console.log('QboAudit Background Script');

chrome.runtime.onInstalled.addListener(details => {
    console.log('QboAudit previousVersion', details.previousVersion);
})

chrome.webNavigation.onHistoryStateUpdated.addListener( (details) => {
    console.log('QboAudit Page uses History API and we heard a pushSate/replaceState.')
    if(typeof chrome._LAST_RUN === 'undefined' || notRunWithinTheLastSecond(details.timeStamp)){
        chrome._LAST_RUN = details.timeStamp
        chrome.tabs.getSelected(null, function (tab) { 
            if(tab.url.match(/.*\/app\/auditlog1/)){
                chrome.tabs.sendRequest(tab.id, 'runQboAuditLog')
            }
        })
    }
})

const notRunWithinTheLastSecond = (dt) => {
    const diff = dt - chrome._LAST_RUN
    if (diff < 1000){
        return false
    } else {
        return true
    }
}

Of note is the highlighted line above. Naturally, you only want to run the extension within the QBO audit log, which has an ending URL like this: *.intuit.com/app/auditlog. To accomplish this I have a basic wild card set in the manifest.json but I couldn't dial in the permissions any further then what is presently set (see manifest.json above) without getting errors, therefore, I had to put the rest of the solution within the background.js file.

Minimul says —

What's with all of the chrome._LAST_RUN stuff?

Since QuickBooks Online is a single page app you'll need to monitor the push or history state to determine if the user is navigating around. There is a "bug" that duplicate push state events will get kicked off almost simultaneously. Therefore, the rest of the code in background.js deals with not running that duplicate event.

The contentscript.js file

The contentscript.js is the one script that will actually get run inside the page in the traditional sense, like as if you are loading it in via the page's <script></script> tag.

This file contains all of the extension's logic and is called by the background script when the conditions are right.

// background.js excerpt that calls the contentscript.js when the page's URL
// suffix of /app/auditlog is navigated to.
if(tab.url.match(/.*\/app\/auditlog/)){
  chrome.tabs.sendRequest(tab.id, 'runQboAuditLog')
}

// contentscript.js
chrome.extension.onRequest.addListener((request, sender, sendResponse) => {
    if (request == 'runQboAuditLog')
        new QboAuditLog()
});

This section is at the 9:28 mark.

Here is the full contentscript.js file:

'use strict';

class QboAuditLog {
    constructor(){
        [this.date, this.time] = new Date().toLocaleString('en-US').split(', ');
        this.init()
    }

    init() {
        const domCheck = setInterval( () => {
            console.log('QboAudit loop running');
            if(document.querySelector('.filterBarContainer')){
                clearInterval(domCheck)
                this.createLinks()
            } else {
                console.log('QboAudit miss');
            }
        }, 2000)
    }

    createLinks(){
        this.csvLink()
        this.removeDupsLink()
    }

    csvLink(){
        const link = document.createElement('a')
        link.innerHTML = 'CSV'
        link.addEventListener('click', () => {
            this.triggerDownload()
            return false
        })
        return document.querySelector('.filterBarContainer').appendChild(link)
    }

    removeDupsLink(){
        const link = document.createElement('a')
        link.innerHTML = 'Remove Dups'
        link.style.paddingLeft = '10px'
        link.addEventListener('click', () => {
            this.removeDups()
            return false
        })
        return document.querySelector('.filterBarContainer').appendChild(link)
    }

    download(csv, filename) {
        const csvFile = new Blob([csv], {type: 'text/csv'})
        const downloadLink = document.createElement('a')
        downloadLink.download = filename
        downloadLink.href = window.URL.createObjectURL(csvFile)
        downloadLink.style.display = 'none'
        document.body.appendChild(downloadLink)
        console.dir(downloadLink);
        downloadLink.dispatchEvent(new MouseEvent('click'))
        document.body.removeChild(downloadLink)
    }

    triggerDownload() {
        let csv = []
        const rows = this.getRows()
        for (let i = 0; i < rows.length; i++) {
            let row = [], cols = rows[i].querySelectorAll('td')
            for (let j = 0; j < cols.length; j++){
                row.push(`"${cols[j].innerText}"`)
            }
            csv.push(row.join(','))
        }
        return this.download(csv.join('\n'), `daily-report-${this.date}.csv`)
    }

    getRows(){
        return document.querySelectorAll('.dgrid-content table tr')
    }

    removeDups() {
        const sel = '.dgrid-column-4';
        const els = document.querySelectorAll(sel)
        els.forEach((item) => {
            const name = item.innerText
            let seen = {}
            this.getRows().forEach((tr) => {
                const txt = tr.querySelector(sel).innerText
                //console.log(`QboAudit ${txt}`);
                if(txt === ''){
                    tr.closest('div').remove()
                    return
                }
                if (name === txt){
                    if(seen[txt]){
                        tr.closest('div').remove()
                    } else {
                        seen[txt] = true
                    }
                }
            })
        })
    }

}

chrome.extension.onRequest.addListener((request, sender, sendResponse) => {
    if (request == 'runQboAuditLog') 
        new QboAuditLog()
});

Pay special attention to the init() method. I had to create a loop to check when the DOM was ready to properly insert the links. I tried various things but only constructing this manual loop worked.

Also, take a look at the download() method. It uses the Blob object but I needed to dispatch a mouseclick event as seen in this line downloadLink.dispatchEvent(new MouseEvent('click')) to actually get the download to work.

Conclusion

Be sure to check out the screencast as I have much more commentary including some useful information on debugging and on the automatic chromereload.js code that comes with the Yeoman Chrome Generator, which is what I used to generate the Chrome extension scaffolding. Lastly, don't forget all the code is in its own Github repo.

Refreshing the QuickBooks OAuth2 access token

2017-08-19T00:00:00Z

The 1 Hour Problem

With QuickBooks OAuth 1a the access token was valid for 6 months. With respect to development, your experience might go something like this. Every 6 months or so when sandbox testing some QuickBooks API feature you would scratch your head a bit but then eventually figure out your development access token expired. You'd clear out some stuff in the database so that the QuickBooks Connect button would reappear and then reconnect to get a new access token. Rinse and repeat every 6 months.

Sometimes I felt like automating this token renewal process (like in production) but with the 6 month expiry grace period the return on investment for automation was always too low.

However, with OAuth 2, access tokens are only valid for 1 hour. This basically forces your hand to come up with development and production environment automated token renewing solutions ‐ immediately.

Proper persistence

In multi-tenant apps I usually use a qbo_accounts table (that belongs to an accounts table) to store credentials for an account.

Here are the minimum columns needed.

$ ap QboAccount.columns.map(&:name)
[
        [ 0] "id",
        [ 1] "access_token",
        [ 2] "refresh_token",
        [ 3] "companyid",
        [ 4] "account_id",
        [ 5] "created_at",
        [ 6] "updated_at",
        [ 7] "token_expires_at",
        [ 8] "reconnect_token_at",
]

Minimul says —

You should be encrypting the access_token, refresh_token, and the companyid columns at the database level for which I leverage the attr_encrypted gem.

Persisting a OAuth2 response

When the OAuth2 response comes back persist it being sure to set the token_expires_at attribute for 60 minutes and the reconnect_token_at attribute for 50 minutes.

  account.create_qbo_account( access_token: response.access_token, refresh_token: response.refresh_token,
                              companyid: params[:realmId], token_expires_at: 60.minutes.from_now,
                              reconnect_token_at: 50.minutes.from_now
                            )

Renewing Rake task

namespace :quickbooks do
task :renew_oauth2_tokens => :environment do
    if (qbo_accounts = QboAccount.where('reconnect_token_at <= NOW() AND token_expires_at >= NOW()')).empty?
        p "OAUTH2_RENEW_TOKEN: nothing to do"
    else
        qbo_accounts.each do |q|
            begin
                client = oauth2_client
                client.refresh_token = q.refresh_token
                if resp = client.access_token!
                    duration_attrs = { reconnect_token_at: 1.hour.from_now, 
                                    token_expires_at: 50.minutes.from_now }
                    attrs = { token: resp.access_token, refresh_token: resp.refresh_token }.merge(duration_attrs)
                    if q.update(attrs)
                        p "SUCCESS_OAUTH2_RENEW_TOKEN: qbo_account: #{q.id}"
                    else
                        p  "FAILED_OAUTH2_RENEW_TOKEN: qbo_account: #{q.id} error_message: #{resp}"
                    end
                end
            rescue => e
                p "FAILED_OAUTH2_RENEW_TOKEN: qbo_account: #{q.id} error_message: #{e.message}"
            end
        end
    end
end
def oauth2_client
    Rack::OAuth2::Client.new(
        identifier: ENV['QBO_API_CLIENT_ID'],
        secret: ENV['QBO_API_CLIENT_SECRET'],
        redirect_uri: 'http://localhost:3000/accounts/oauth2_callback',
        authorization_endpoint: "https://appcenter.intuit.com/connect/oauth2",
        token_endpoint: "https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer"
    )
end
end
end

Minimul says —

The reason I set the reconnect_token_at duration at 50 minutes is so to NOT run the refresh requests excessively. Moreover, we don't want to keep running refresh requests if there is no chance of renewal because the access_token expiry date is past. Therefore, I am only executing a refresh request when inside of this 10 minute window.

The access_token remains static on a successful refresh, it does not change.

The renew_oauth2_tokens rake task uses the rack-oauth2 gem.

Hook Up The Renew Rake Task in Development

For development I use OSX so I will detail making a LaunchD task but for Linux you, of course, have Cron, which I use in production. I am not up to speed on Windows OS but leave a recipe in the comments and I will include it in the article.

$ cd ~/Library/LaunchAgents
$ vim com.minimul.bsmash.oauth2.renew.plist
Example plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.minimul.bsmash.oauth2.renew</string>
  <key>ProgramArguments</key>
  <array>
    <string>/bin/bash</string>
    <string>-l</string>
    <string>-c</string>
    <string>
    cd /Users/minimul/www/projects/bordersmash;
    bin/rake quickbooks:renew_oauth2_tokens
    </string>
  </array>
  <key>StartInterval</key>
  <integer>300</integer>
  <key>RunAtLoad</key>
  <true/>
</dict>
</plist>

Save the .plist task.
$ launchctl load com.minimul.bsmash.oauth2.renew.plist

Minimul says —

This task will run at boot and then every 5 minutes.

Note: In development I use chruby and ruby-install for Ruby management so the above plist may not work when using RVM or rbenv but the /bin/bash -l -c prefix should properly load the intended Ruby environment for all managers.

Production

In production I use the Whenever gem in combination with Cron. So here is an example of my config/schedule.rb

set :output, "/var/log/cron"

every 5.minutes do
  rake "quickbooks:renew_oauth2_tokens"
end

Problem Solved, Sort of

The beauty of this setup is that you'll never have to worry about your QuickBooks API tokens expiring. However, that presupposes that your local development environment is always running. Have your laptop shutdown for over an hour and your access tokens will all be invalidated.

You also must have a production renew job in place from a day one (of your integration), which with OAuth 1a you could have waited a few months before setting that up. Moreover, do you plan on having a maintenance outage for over an hour on your production app? Great all of your app's OAuth 2 access tokens just became invalid. What if Intuit itself has even a brief outage on their OAuth 2 server(s)?

For these reasons I suspect Intuit will raise the expiry duration at some point. Until then, however, if you, your company or client has an existing (created before July 17th) Intuit developer account that supports OAuth 1a don't be quick to create a new Intuit Developer account meaning to switch your integration to OAuth 2 as this 60 minute expiry time will surely come back to bite you.

Lastly, if you insist on implementing OAuth 2 or have a new Developer account and must implement it, consider purchasing my book as I have this OAuth 2 integration in much more detail and you'll be helping to support this educational resource site.

Access the QuickBooks Online API with OAuth2

2017-07-31T00:00:00Z

OAuth2 required for new Intuit Developer Accounts

Starting July 17th, 2017 all new Intuit Developer accounts will need to use OAuth2 for API access. Here is how to use the QboApi gem and OAuth2.

OAuth2 for new Intuit Developer Accounts.

Choosing an OAuth2 gem or not

I really won't bother trying to re-invent the wheel by rolling your own OAuth2 code. That said, the OAuth2 2-legged process is simpler than the 3-legged OAuth 1a process and if you do want to roll your own OAuth2 code take a look at Intuit's Python example for a good starting point.

As for me, I'll choose to leverage the Rack-OAuth2 gem as I like its ability to directly set endpoints.

Spinning up an OAuth2 example

Clone the qbo_api gem, switch into the new directory, and bundle

$ git clone git://github.com/minimul/qbo_api && cd qbo_api
$ bundle

Create a .env file with the client_id and client_secret provided within the App settings page. See Fig. 2.

export QBO_API_CLIENT_ID=
export QBO_API_CLIENT_SECRET=

Make a new app, I called this one QboApi OAuth2 Inc then go into its settings and then click on the Keys tab to get the client id and client secret. Put those values in the .env file.

This section is at the 2:16 mark.

Set the OAuth2 callback or redirect URI to http://localhost:9393/oauth2-redirect

Massively IMPORTANT step

Start up the example app

  $ shotgun example/app.rb

Firing up the QboApi sample app.

Goto https://localhost:9393/oauth2

Make sure to use localhost and not 127.0.0.1. Intuit only allows the host name localhost for OAuth2 sandbox callbacks.

As you can see in the example/app.rb file the callback URI is also properly set to localhost and not 127.0.0.1.

This section is at the 5:19 mark.

Click on the 'Connect To QuickBooks' button, Sign in, and click on Authorize.

If you are not already signed in, you are going to sign in with your Intuit Developer credentials in case you might be confused. In short you are signing in and connecting your QuickBooks app's sandbox to your QuickBooks app's "App". Clear as mud? Lastly, click "Authorize".

This section is at the 8:51 mark.

The response.

Here is a successful response back. Highlighted is the access token.

The response code.

Check out what's going on under the hood on this response.

Click on Click here to make an API call.

Let's test the new access token.

Success. We retrieved Sandbox customer # 5 ‐ "Dukes Basketball Camp".

Reference the example/app.rb to see how to make a basic QuickBooks API call with the QBO API gem.

Getting Started with QuickBooks Online Webhooks

2016-07-26T00:00:00Z

Webhooks finally have landed.

You can start rewriting your CDC polling code now . Well maybe not. As a prerequisite for this tutorial you need to be able to start up the qbo_api example app. If you haven't done that, do it now and come back.

Switch into your local qbo_api directory.
Start up the example app

  $ shotgun example/app.rb

Go to your QuickBooks Online API app you created for your start up example and click on the "Settings" link.

Make sure you are in the "Development" and NOT "Production" area.

Go down to the "Webhooks" section. You will see that we need to submit a URL so Intuit can POST webhook requests to. The standard way to do this in development is to use ngrok.
Download ngrok and put it in a auto-loaded path. e.g. /usr/local/bin/
Fire up ngrok on port 9393.

    $ ngrok http 9393

Here is the output of the ngrok http 9393 command.

Copy the https:// url that the ngrok generates.
Next, go back to https://developer.intuit.com and put this URL with /webhooks added to the end of it.

Add the ngrok URL plus /webhooks route in the app settings page.
Enable "Estimate" events to receive webhooks and hit "Save".

Now we are almost ready to test.

Let's add the /webhooks route to the example app.
Open up example/app.rb and add this post route.

  
post '/webhooks' do
  request.body.rewind
  data = request.body.read
  puts JSON.parse data
  verified = verify_webhook(data, env['HTTP_INTUIT_SIGNATURE'])
  puts "Verified: #{verified}"
end

Next, let's add the verify_webhook method.

  
helpers do
  def verify_webhook(data, hmac_header)
    digest  = OpenSSL::Digest.new('sha256')    
    calculated_hmac = Base64.encode64(OpenSSL::HMAC.digest(digest, VERIFIER_TOKEN, data)).strip    
    calculated_hmac == hmac_header
  end
end

You'll also need to require the openssl and base64 libraries.

require 'openssl'
require 'base64'

You are going to need to add the VERIFIER_TOKEN variable.
Go back Intuit Developer and copy the verifier token to your clipboard.

This section is at the 7:47 mark.

Copying the verifier token.

Add the verifier token to the .env file like so:

...  
export QBO_API_COMPANY_ID=1441111111
export QBO_API_VERIFIER_TOKEN=[put here]

Then in the example/app.rb put in this (below the CONSUMER_SECRET constant):

VERIFIER_TOKEN = ENV['QBO_API_VERIFIER_TOKEN']

This section is at the 10:10 mark.

Open up your sandbox that was used when performing Spinning up an example app step.
Copy this URL (https://sandbox.qbo.intuit.com/app/estimate?txn=100) and paste into the address bar after logging into the sandbox to go directly to Estimate 1001.
Change the Status from "Pending" to "Accepted" and hit "Save".

You don't have to fill out the Accepted Status date.

Go back the console where example app is running and look for the incoming request.

Look here for the incoming webhook request.

In took about 15 seconds but it arrives!

From this point you want to parse the JSON, putting the results into a queue for backend processing.

Conclusion

QuickBooks Online Webhooks support is going to radically simplify syncing user actions on QBO to your app. I am planning on perhaps 2 more webhooks tutorials so sign up for the newsletter below. Lastly, make sure you read Intuit's Best Practices section.

The modern Ruby QuickBooks client: Part 3 - Gem Contributing

2016-03-01T00:00:00Z

Record your own QBO sandbox transactions in a PR

You would like to enhance or fix something in the qbo_api gem but aren't too sure about the "VCR-recorded-sandbox-transaction" part of the specs. Don't you worry a bit about that. Frankly, this "VCR-recorded-sandbox-transaction" thing will actually make it easier for you to contribute and not the other way around. Creating fictional API fixtures is the harder and more error-prone approach.

Fork the qbo_api gem
Clone your fork, switch into the new directory, and bundle

  $ git clone git://github.com/[your fork]/qbo_api && cd qbo_api
  $ bundle

Make a new branch for your PR e.g. git checkout -b cust-ref-name
Create a .env file and fill in all the values

Please see part 1, which will fully explain how to get all the values you need to properly fill in the .env file.

This section is at the 2:22 mark.

Next, run the specs bundle exec rspec spec/.

Let's make sure the specs are green before we move on.

Open the spec spec/create_update_delete_spec.rb
Add a name attribute to the CustomerRef

Here we are modifying an existing spec that creates an invoice. Its transaction has been recorded by VCR.

Change the record setting to "all". record: :all and rerun

We are rerunning the specs with a new payload. With the record: :all setting enabled the spec will test against your sandbox with VCR recording the transaction.

Run the git status to see which files have been modified.

Notice that the VCR recorded file spec/vcr/qbo_api/create/invoice.yml has been updated with the new recording.

Change the record: :all back to record: :none.
Commit the changes: git commit -a -m "Add CustomerRef:name information when create a new invoice"
Then push the branch and submit the pull request.

Conclusion

Contributing to the qbo_api gem is a cinch. The fact that the gem utilizes VCR-recorded transactions against real QuickBooks sandboxes makes it a great choice. That said, don't be intimated at all by VCR; follow this tutorial and you will easily be able to contribute in making the gem even better.

The modern Ruby QuickBooks client Part 2

2016-01-23T00:00:00Z

"Real world" fixtures

The qbo_api gem's specs were built against an official QuickBooks sandbox and then recorded using the VCR gem. Therefore, you have a fantastically quick way to get started with your integration project in that you can see "real world" QBO API transaction without your own sandbox or even a network connection. Allow me to demonstrate.

Clone the qbo_api gem, switch into the new directory, and bundle

  $ git clone git://github.com/minimul/qbo_api && cd qbo_api
  $ bundle

Create a .env file If you are just running the specs then at minimum your .env needs to look like the following:

export QBO_API_CONSUMER_KEY=
export QBO_API_CONSUMER_SECRET=
export QBO_API_ACCESS_TOKEN=
export QBO_API_ACCESS_TOKEN_SECRET=
export QBO_API_COMPANY_ID=12345

This section is at the 2:48 mark.

Now you can run the specs by doing a bundle exec rspec spec/

Let's get some green before we dive in further. Note: the be is a bash alias for bundle exec.

Let's open up the spec/create_update_delete_spec.rb
Then go to the first spec where abouts the VCR cassette is being recorded.

Here you see how the gem is initialized.

The creds method is defined in the spec/spec_helper.rb

The .env file is loaded by the Dotenv gem.

Minimul says —

If you want to see an example of an advanced VCR custom matcher keep reading the spec/spec_helper.rb file. The purpose of the matcher is to make VCR more lenient so that any QuickBooks sandbox can be used.

This section is at the 5:29 mark.

The qbo_api initialization and many other methods use keyword arguments, which is the primary reason for the Ruby 2.2.2 requirement.

Before the initialize set QboApi.log = true and run the individual spec.

Use the log feature to view the HTTP transaction to QBO API.

Here is the full (real not a fictional fixture) request and response for creating an invoice.

Now let's mess around with the response by outputing the invoice's customer name

Add a p response['CustomerRef']['name'] and then comment out the QboApi.log = true to isolate the output to only the customer name.

This section is at the 7:44 mark.

Next, open up the spec/error_spec.rb and goto the spec titled "handles a validation error".

The spec displays how you can detect an error and how to potentially respond.

Conclusion

When getting started with a QuickBooks integration project using the qbo_api gem leverage the "real world" recorded specs to help you get started quickly.

Multiple QuickBooks Sandboxes

2016-01-19T00:00:00Z

Adding and naming a sandbox

Minimul says —

Intuit allows a developer account to have up to 5 sandboxes. Let's take a look at making a new sandbox and giving it a descriptive name.

Sandboxes are tied to your developer account not your apps.

Here is an example of a default developer sandbox.

Sandbox countries supported besides U.S. are Austraila, Canada, India, and U.K.

Click the "Add" button.

After the screen refreshes you will see the second sandbox.

The new sandbox is not too descriptive but let's change that.
Open up "Go to company" into a new browser tab.

Be nice if there was an easier way to change the sandbox company name but for the time being we have go into the account.

Once into the sandbox account click on the gear icon and then "Company settings".

(1) Click gear icon; (2) then "Company settings".

Then within the "Company" section => "Company Name" section, click on the pencil icon.

Clicking pencil/edit icon.

Since I want to use this sandbox for testing the qbo_api gem I will name this sandbox accordingly.

Edit the name inline, click "Save", and then "Done".

Go back to your Intuit developer account tab and click "Reload".

Now we have a nice descriptive name for our new sandbox.

Conclusion

You don't have fit all of your integration needs by using just one sandbox. Instead, take advantage of the ability to make additional descriptive QuickBooks Online sandboxes to aid in your developer experience.

Getting starting with the modern Ruby QuickBooks Online client, the qbo_api gem, Part 1

2016-01-18T00:00:00Z

Spin up an example app

Ok, I made the arguments why the qbo_api gem is the "modern" Ruby QuickBooks Online API client but what is the best way to get started using it? I'd advise you to spin up the example app included in the library.

Clone the qbo_api gem, switch into the new directory, and bundle

  $ git clone git://github.com/minimul/qbo_api
  $ cd qbo_api
  $ bundle

Create a .env file with your QuickBooks Online API app's consumer key & consumer secret
Consumer key and secret? Keep following.
If needed create an account at https://developer.intuit.com
Click "Get started coding"

First screen after creating a new account.

Create an app with both the Accounting & Payments selected.

Although, Payments is not needed for the example it is turned on in the example app "Connect to Intuit" button.

Go to the Development tab and copy and paste the consumer key and secret into the .env file.

Copy the "OAuth Consumer Key" and the "OAuth Consumer Secret"

# and put'em the .env file (located at the qbo_api root dir) like so
export QBO_API_CONSUMER_KEY=<Your QuickBooks apps consumer key>
export QBO_API_CONSUMER_SECRET=<Your QuickBooks apps consumer secret>

This section is at the 5:33 mark.

Start up the example app

$ ruby example/app.rb

Goto http://localhost:9393

Simple page with just the "Connect to QuickBooks" button

Use the Connect to QuickBooks button to connect to your QuickBooks sandbox, which you receive when signing up at https://developer.intuit.com.

This section is at the 10:07 mark.

To launch the sandbox

Click on "Go to company"

Here is your sandbox. Note: it is tied to your login and not the created app. Listen to me talk more about sandboxes on the screencast.

Click on "Connect to QuickBooks"

You will be presented with this view if you are already logged into your Intuit developer account. Otherwise, you will get a login screen before this view.

After authorizing you will be returned to the example app. Your OAuth info will be displayed for convenience, although not needed for this tutorial. The token, token_secret, and realm_id are needed to initialize the qbo_api gem.

Next, goto the address is http://localhost:9393/customer/5

Should get "Dukes Basketball Camp". Check out the code to see how it works.

Dukes Basketball Camp is a sandbox customer.

Summary

The fastest way to dig into the qbo_api gem is to spin up the example app. After you accomplish that take a look under the hood and you will be ready to integrate your app with QuickBooks Online.

Introducing a Faraday-powered, JSON-only Ruby-QuickBooks client

2016-01-05T00:00:00Z

Jealousy

The JSON-only node-quickbooks package has provoked me to a certain level of jealousy when compared to using the XML-only quickbooks-ruby gem. Using JSON means I can get closer to the metal when constructing requests and interpreting responses. Since all the QBO API examples now-a-days are in JSON having a JSON client is essential for a smooth development experience.

Problems with the current defacto Ruby QuickBooks Online library.

Since the QBO API v2 was XML only, Cody Caughlan the creator and maintainer of the v2 quickeebooks gem naturally used a similar XML-centric approach when creating the new QBO API v3 gem, quickbooks-ruby. The choice was practical and sound as it even appeared early on (in v3) that Intuit seemed to favor XML as some entities had better XML support than JSON. That has perceived favoritism has flipped.

Intuit employee Tony Chang comments on the future of data formats with regards to the QuickBooks Online API. Read the full conversation. tldr; The present and future of the QuickBooks Online API is the JSON data format.
Because of the XML choice the quickbooks-ruby gem spends a lot code trying (and rightly so) to abstract XML's verbosity. As a result you need to be constantly looking at the gem code (models in quickbooks-ruby) to see how the QBO API is being translated to quickbooks-ruby models. With a JSON client all of this cruft is not needed. You can literally just grab the JSON from an API example and form a request e.g.

  
invoice = {
  "Line": [
    {
      "Amount": 100.00,
      "DetailType": "SalesItemLineDetail",
      "SalesItemLineDetail": {
        "ItemRef": {
          "value": "1",
          "name": "Services"
        }
      }
    }
  ],
  "CustomerRef": {
    "value": "1"
  }
}
response = qbo_api.create(:invoice, payload: invoice)

The response is simply JSON.parse'd into a Ruby Hash e.g.

p response['Id'] # => 65

Wouldn't it be nice to able to do that in Ruby?

You can! Introducing the qbo_api gem.

It is based on Ruby >=2.2 and Faraday and is incredibly lightweight compared to the quickbooks-ruby gem.

Features:

JSON-only
Has robust error handling built in.
Has specs written against official QBO sandboxes.
- Uses the VCR gem to record sandbox transactions so you're not having to construct fictional fixtures.

Why not just use node-quickbooks?

Using Node.js feels like going back many steps compared to the Ruby ecosystem (especially Ruby 2.2 and greater).

Node.js Cons:

No Rails equivalent.
The fact that ES6 is only now being aggressively merged into Node.js core is a real detriment to using Node.js. This should have been done long ago as most code is still ES5.
Even ES6 is still so far from the polish, design, and features that is Ruby 2.2 and greater.
The fact that everything is asynchronous is annoying and results in "silly" troubleshooting situations. I like asynchronous programming when it makes sense, but not as a default.
Node.js is akin to the "wild west" and too much is in "flux" for me spend time keeping up with it. I run a consulting business not a lab.
- Do I use ES5 or ES6 or Babel or TypeScript or Coffeescript? Seriously.
- In comparison, Ruby/Rails is stable and "grown-up".

My future with quickbooks-ruby?

I'm an official contributor and have clients using quickbooks-ruby. Personally, I will continue looking at and submitting PRs, answering issues, and so forth. There are a huge number of organizations using quickbooks-ruby and many more will continue to choose the gem for new projects. I just released qbo_api and there are virtually no downloads . The qbo_api gem also has a hard Ruby 2.2 and greater requirement so who knows what adoption it will achieve. On the other hand, the quickbooks-ruby gem is the entrenched de facto Ruby library and will continue to be well into the future. I will be helping maintain it for at a minimum, professional reasons, but I also enjoying helping developers with QuickBooks Online integration.

That said, all of my new QuickBooks integration projects will be with the qbo_api gem and my time will be focused (there is still a ton to do, like Payments API, etc.) on it. I don't plan on dedicating any time to enhancing quickbooks-ruby with respect to new features and will not be appending to the JSON support I and raecoo added in 0.3.0.

Summary

A new QuickBooks Online Ruby JSON-only client, qbo_api, has been released but the existing Ruby client, quickbooks-ruby remains a viable option.

Getting started with Nodejs and QuickBooks Online Part 4

2015-09-17T00:00:00Z

Let's create a Sales Receipt!

In Part 4, I'll show how you can use the node-quickbooks's tests to create a SalesReceipt transaction against your developer sandbox. Specifically, I will be answering this question from the Intuit Developer forums.

Make a new branch.

  $ git branch salesreceipt

Turn on debugging in config.js.

-  debug:           false,
+  debug:           true,

Open up test/index.js.
Go down to the test starting with describe('SalesReceipt', ...
Let's put this test that creates a sales receipt into its own test file test/salesreceipt.js.
Then let's apply the JSON request example in the question.

var os         = require('os'),
    fs         = require('fs'),
    util       = require('util'),
    expect     = require('expect'),
    async      = require('async'),
    _          = require('underscore'),
    config     = require('../config'),
    QuickBooks = require('../index'),
    qbo        = new QuickBooks(config);

describe('SalesReceipt', function() {

  this.timeout(30000);

  it('should create a new SalesReceipt', function (done) {
    var sr = {
      "Line": [{
        "Id": "1",
        "LineNum": 1,
        "Amount": 35.0,
        "DetailType": "SalesItemLineDetail",
        "SalesItemLineDetail": {
          "ItemRef": {
            "value": "61",
            "name": "10 Pack Group X Classes"
          },
          "UnitPrice": 35,
          "Qty": 1,
          "TaxCodeRef": {
            "value": "NON"
          }
        }
      }]
    }
    qbo.createSalesReceipt(sr, function(err, salesReceipt) {
      expect(err).toBe(null)
      expect(salesReceipt.Fault).toBe(undefined)
      done()
    })
  })

})

Minimul says —

Ok, so we modified the test/salesreceipt.js test with the JSON request from the forums question. But one glaring problem is the ItemRef: "61" is not going to work because there is no Item with an Id of 61 in the sandbox. The Item Id 61 is coming from the users QBO.

Therefore, we need to find an adequate replacement from the developer sandbox but the sandbox UI doesn't show Ids for Items. The API does show ids so let's create a temporary "test" that will display sandbox items and their Ids.

This section is at the 5:33 mark.

Make a another test above the current one like this.

  
// ...
this.timeout(30000);

it.only('find sandbox items', function (done) {
  qbo.findItems(function(_, items) {
    items.QueryResponse.Item.forEach(function(item) {
      console.log("id:" + item.Id + " name:" + item.Name + " type:" + item.Type)
    })
  })
});

// ...

Minimul says —

Notice, the it.only syntax. These tests use the mocha framework, which allows using only so only this one test will run and all others will be skipped. Perfect for what we need here, which is simple request so we can plug in a valid ItemRef Id to the other test.

Now let's run the test

  $ npm test test/salesreceipt.js

You should see a listing of sandbox items.

This section is at the 9:54 mark.

Let's use a Service type item so Item Id = 6, "Gardening" should work just fine.

  
          "ItemRef": {
-            "value": "61",
+            "value": "6",
            "name": "10 Pack Group X Classes"
          },

Next, make sure you either delete the test from step 7 or mark it "skip".

  
-  it.only('find sandbox items', function (done) {
+  it.skip('find sandbox items', function (done) {

Run the test

  $ npm test test/salesreceipt.js

That did the trick.

Conclusion

That's a wrap for this 4 part series, cumulating in creating a transaction entity in QuickBooks Online. Also, reference the code for this article as well as Part 3.

Getting started with Nodejs and QuickBooks Online Part 3

2015-09-15T00:00:00Z

Let's get `npm test` working

In part 1 and part 2 we just got our feet wet. An important part of digging deeper is to check out the tests, which display more complex transactions. Now, in part 3 we will get npm test working being it is not as simple as you might think.

Grab the latest from node-quickbooks or your fork of it.

git checkout pull upstream master

Minimul says —

I am back to using the node-quickbooks master so in that regard I am not picking up directly from part 2.

We need to spin up the example app again to get the access tokens and realm id so we can record them into config.js, which is used by npm test to properly talk to your sandbox.

I noticed some changes in for example/package.json after the upstream pull so:

  $ cd example
  $ npm install

Edit example/app.js and make the following mods:

-var consumerKey    = '',
-    consumerSecret = ''
+var consumerKey    = process.env.MINIMULCASTS_CONSUMER_KEY, // substitute your env variable here
+    consumerSecret = process.env.MINIMULCASTS_CONSUMER_SECRET
// ...
-                         true); // turn debugging on
+                         false); // turn debugging off
// ...
       accounts.QueryResponse.Account.forEach(function(account) {
-        console.log(account.Name)
+        //console.log(account.Name)
       })

Still in the example dir do a nodemon app.js
Go to the browser http://localhost:3000/.
Click the "Connect to QuickBooks" button and authenticate with your sandbox.

Minimul says —

Make sure your Intuit app is enabled both for "QuickBooks" & "Payments" or you will get an error when connecting.

Need to be enabled for both API capabilities.

Go back to your console running nodemon app.js and you should see the information we need for the config.js

Copy the app tokens and realm id from the console.

This section is at the 8:44 mark.

You can shutdown the example app now.
Create a .env file (don't commit to source control) in the project root directory looking like this:

export OAUTH_TOKEN_SECRET=[ paste secret here (from step 7) ]
export OAUTH_TOKEN=[ paste token here ]
export REALM_ID=[ paste realm id here ]

Make sure to "source" this file in all of your console windows: source .env

This section is at the 10:33 mark.

Edit config.js to look like this:

module.exports = {
  consumerKey:     process.env.MINIMULCASTS_CONSUMER_KEY, // change for your app's consumer key
  consumerSecret:  process.env.MINIMULCASTS_CONSUMER_SECRET, // change for your app's consumer secret
  token:           process.env.OAUTH_TOKEN,
  tokenSecret:     process.env.OAUTH_TOKEN_SECRET,
  realmId:         process.env.REALM_ID,
  useSandbox:      true,
  debug:           false,
  //
  // Set useSandbox to false when moving to production. For info, see the following url:
  // https://developer.intuit.com/v2/blog/2014/10/24/intuit-developer-now-offers-quickbooks-sandboxes

  testEmail:       ''  // Use this email address for testing send*Pdf functions
}

Now you are ready to run the tests, so again in the console that you ran source .env run npm test

  $ source .env
  $ npm test

Getting some green!

Conclusion

That's a wrap for part 3, in which we "simply" got the tests running. In part 4 I am going to be leveraging this test setup to answer a question on the Intuit developer forums that will show how you can leverage the tests to getting going on more complex transactions. Also, reference the code for this and part 4 of the tutorial.

Getting started with Nodejs and QuickBooks Online Part 2

2015-09-08T00:00:00Z

Continuing from Part 1

In part 1 we just did the bare minimum. Now, in part 2 we are going to go a bit further by creating a customer route where we will pass in an id and then retrieve the associated customer from the developer sandbox and output their "DisplayName" value.

Let's start by making that new route right below the /start route in app.js.


app.get('/customer/:id', function (req, res) {
  console.log(req.params.id);
  res.render('customer.ejs', { locals: { customer: customer }})
}

Then make a new customer view in views/customer.ejs

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title></title>
</head>
<body>
  <h1>Customer</h1>
</body>
</html>

Go to the browser and run the route http://localhost:3000/customer/5.
You should see "5" output to the console running nodemon app.js.
Next, we are going implement basic persistence with the cookie-session NPM package

Minimul says —

We need to persist the OAuth token, secret, and Intuit's realmId (now referred as the "company id") to make repeated API calls. In a real app you would use a data store like Postgres, Redis, etc. Here we will use sessions, however, the express-session only persists for a short duration and is meant for data stores. Therefore, let's use the cookie-session package to get some basic persistence.

$ cd example/
$ npm install cookie-session --save // --save option saves the entry to example/package.json

Back in app.js make the following modifications.

....
cookieParser = require('cookie-parser'),
-    session    = require('express-session'),
+    cookieSession    = require('cookie-session'),
....
-app.use(session({resave: false, saveUninitialized: false, secret: 'smith'}));
+app.use(cookieSession({name: 'session', keys: ['key1']}))
....

Let's save the OAuth token, secret, and realmId. Go to line 78 or app.js and insert this code to persist these values across requests.

    // Line 78
    req.session.qbo = {
      token: accessToken.oauth_token,
      secret: accessToken.oauth_token_secret,
      companyid: postBody.oauth.realmId
    };

We must make a way to call the Quickbooks initialization code a little easier and DRYer.
Go to the end of app.js and make a global function to easily initialize the Quickbooks object from node-quickbooks.

var getQbo = function (args) {
  return new QuickBooks(consumerKey,
                       consumerSecret,
                       args.token,
                       args.secret,
                       args.companyid,
                       true, // use the Sandbox
                       true); // turn debugging on

};

Replace this similar code from the /callback method after the session save code in step 7.

    qbo = getQbo(req.session.qbo);

Now modify the /customer/:id route to look like this:

app.get('/customer/:id', function (req, res) {
  console.log(req.session);
  var qbo = getQbo(req.session.qbo);
  qbo.getCustomer(req.params.id, function(err, customer) {
    console.log(customer);
    res.render('customer.ejs', { locals: { customer: customer }})
  })
})

Then modify the views/customer.ejs to output the DisplayName.

  <h1>Customer <%= customer.DisplayName %></h1>

Go back to the browser at http://localhost:3000/start and click on the "Connect to QuickBooks" button and run through OAuth again. The will save your OAuth token, secret, and realmId in sessions.
After that run the http://localhost:3000/customer/5 route.
You should get:

"Dukes Basketball Camp" is sandbox customer id 5.

Conclusion

That's a wrap for part 2, in which I created a customer route that looked up and outputted a QuickBooks Online customer "DisplayName". Also, reference the code for this 2-part tutorial.

Getting started with Nodejs and QuickBooks Online Part 1

2015-09-08T00:00:00Z

A Great tech stack and NPM package

Michael Cohen has written a full-featured NPM package for QuickBooks Online integration called node-quickbooks. Nodejs is merging with Iojs and will continue its march as a formidable tech stack. What's great about Node is its robust NPM ecosystem. Since Node is relatively new the NPM packages are fresh and generally constructed with modern best practices. In the case of node-quickbooks it has full support for JSON, which Intuit has blessed as its primary data format for API version 3. This is something of a challenge for other libraries such as quickbooks-ruby and quickbooks-php, which are primary XML based. With all of those bonus points, let's investigate getting up and running with some basic integration.

Clone either your fork or the main repo, switch into it, and make sure to run npm install in both the root and in the example directory.

$ git clone git@github.com:mcohen01/node-quickbooks.git
$ cd node-quickbooks
$ npm install
$ cd example
$ npm install

Run tree -I "node_modules|build"

$ cd ..
$ tree -I "node_modules|build"
.
├── README.md
├── config.js
├── example
│   ├── app.js
│   ├── package.json
│   └── views
│       └── intuit.ejs
├── index.js
├── package.json
└── test
    ├── batch.js
    ├── cdc.js
    ├── charge.js
    └── index.js

Minimul says —

All of the integration code is in index.js. We are mostly going to be working within the example directory.

While still in the example directory fire up the example app. You can simply node app.js but do yourself a favor and use nodemon instead.

  $ pwd
  $ ../node-quickbooks/example
  $ nodemon app.js
[nodemon] v1.4.1
[nodemon] to restart at any time, enter `rs`
[nodemon] watching: *.*
[nodemon] starting `node app app.js`
Express server listening on port 3000

Go to http://localhost:3000/start and you will see a bare-bones page with the "Connect to QuickBooks" Button

Next open up example/app.js and notice the /start route

app.get('/start', function(req, res) {
  res.render('intuit.ejs', {locals: {port:port, appCenter: QuickBooks.APP_CENTER_BASE}})
})

Right above that code are variables for CONSUMER_KEY and CONSUMER_SECRET. These values are from an "Intuit app". You must make an QuickBooks app with Intuit if you want to integrate with the Online API.
Goto https://developer.intuit.com, sign up, and login.
Once logged in hit the "Create a new app" button.
Follow the steps and then grab the consumer key and secret.

Click on the "Keys" tab to reveal the consumer key and secret.

Plug these values into app.js

var consumerKey    = 'aqerba34524sfasfdfafdadfasdf',
    consumerSecret = '52345adfa4qoxouagfaouasfdsy3422'
// Or the more "proper" way is to pass in as ENV variables
var consumerKey    = process.env.MINIMULCASTS_CONSUMER_KEY,
    consumerSecret = process.env.MINIMULCASTS_CONSUMER_SECRET

Also open update views/index.ejs and turn off the payments API if you didn't enable it when you created the Intuit QuickBooks app.

  
intuit.ipp.anywhere.setup({
  grantUrl: 'http://localhost:' + <%= port %> + '/requestToken',
  datasources: {
    quickbooks : true,  // set to false if NOT using Quickbooks API
    payments : false
  }
});

Go back to http://localhost:3000/start and click on "Connect to QuickBooks".
Finish the the 3-legged OAuth.

Minimul says —

If you are prompted for a username and password supply your Intuit developer credentials created earlier. When you create an Intuit QuickBooks app you will automatically have a sandboxed QuickBooks Online client app created for your developer account, therefore, this is what you are going to be connecting to with the "Connect to QuickBooks" button.

Click here to access your developer sandbox.

After OAuth you will be returned the /start page.
Go back to the console where you are running the nodemon app.js you should see the following output.

This output is the dev sandbox chart of account names.

You can see from app.js starting at line 78 what the actually find code is.

// test out account access
qbo.findAccounts(function(_, accounts) {
  accounts.QueryResponse.Account.forEach(function(account) {
    console.log(account.Name)
  })
})

Conclusion

That'll do it for part 1. In part 2 I will expand briefly on this by creating a customer route that will look up and output the QuickBooks Online customer "DisplayName". Also, reference the code for this 2-part tutorial.

How I test against the QuickBooks Online API

2015-03-04T00:00:00Z

A better way to write your QuickBooks integration code

Are you just "winging it" with your production QuickBooks integration code? Pushing changes and hoping all goes well? Or perhaps you are a bit more righteous and manually test against the sandbox. Even then, why create 30 duplicate invoices when working on some simple QBO API error handling code? I am going to demonstrate in less than 20 minutes how to get your Rails app ready for testing against live QBO API interactions in an automated way. As a baseline I am going to start with my minimulcasts account branch, which is a Rails 4.1 app. That said, most of this tutorial should should translate well for a Rails 3.2 app.

Clone my minimulcasts account branch and switch into it.

$ git clone -b account git@github.com:minimul/minimulcasts.git
$ cd minimulcasts

Update the quickbooks-ruby gem.

$ bundle update quickbooks-ruby

Add these to the Gemfile next

group :development do
  gem 'spring'
  gem 'better_errors'
  gem 'spring-commands-rspec'
end

group :test do
  gem 'rspec-rails'
  gem 'factory_girl_rails'
  gem 'vcr'
  gem 'webmock'
end

$ bundle install

Next, enable spring and spring-rspec commands.

$ bundle exec spring binstub --all

Run the rspec install generator.

$ bin/rails g rspec:install

Get OAuth tokens from your Intuit developer account.

This is fastest way to get OAuth Creds.

Put those credentials into environmental shell variables.
Open up spec/rails_helper.rb and modify it as such.

This section is at the 6:47 mark.

  
require 'factory_girl_rails'
require 'vcr'

VCR.configure do |config|
  config.cassette_library_dir = Rails.root.join('spec', 'vcr')
  config.hook_into :webmock
  config.filter_sensitive_data('<ACCESS_TOKEN>') { URI.encode_www_form_component(ENV['MINIMULCASTS_ACCESS_TOKEN']) }
  config.filter_sensitive_data('<CONSUMER_KEY>') { URI.encode_www_form_component(ENV['MINIMULCASTS_CONSUMER_KEY']) }
end

Also add FactoryGirl syntax methods within the RSpec configure block

  
RSpec.configure do |config|
  # Remove this line if you're not using ActiveRecord or ActiveRecord fixtures
  config.fixture_path = "#{::Rails.root}/spec/fixtures"
  config.include FactoryGirl::Syntax::Methods

Create a spec/factories.rb and put in an account factory.

FactoryGirl.define do
  factory :account do
    name 'Tamar Trick'
    qb_token ENV['MINIMULCASTS_ACCESS_TOKEN']
    qb_secret ENV['MINIMULCASTS_ACCESS_TOKEN_SECRET']
    qb_company_id '1292740145'
  end
end

Create a spec/requests directory with a spec called qbo_spec.rb.

  
require 'rails_helper'

describe 'QBO requests' do
  it 'creates an invoice' do
    account = create(:account)
    base = Quickbooks::Base.new(account, :invoice)
    invoice = base.qr_model(:invoice)
    invoice.customer_id = 2

    line_item = base.qr_model(:invoice_line_item)
    line_item.amount = 50
    line_item.description = "Plush Baby Doll"
    line_item.sales_item! do |detail|
      detail.unit_price = 50
      detail.quantity = 1
      detail.item_id = 1
      detail.tax_code_id = 'NON'
    end

    invoice.line_items << line_item
    VCR.use_cassette("qbo/invoice/create", record: :all) do
      result = base.service.create(invoice)
      expect(result.id).to eq 159
    end
  end
end

We are ready to run the spec.

$ bin/rspec spec

Minimul says —

The first run will take a bit of time as we have on record: :all, which is making a live request to the sandbox. This run will fail because I have hard coded the resulting id back from the API. I use this expectation so to verify that only the recorded cassette is being used when record: :none is invoked on the next run.

This section is at the 19:02 mark.

After the successful run you can grab the returned ID and stick in the expectation. Then change the record option to :none and re-run the spec.

  VCR.use_cassette("qbo/invoice/create", record: :none) do
    result = base.service.create(invoice)
    expect(result.id).to eq Put in the returned ID you get from the previous run.
  end

Run the spec again and you will notice how fast it runs as it is using the recorded cassette from VCR.
Finally, take a look at the recorded cassette at spec/vcr/qbo/invoice/create.yml.

Conclusion

Not so bad, eh? Now you can develop integration code in a more assured fashion. This approach can also aid you when working on a PR for the quickbooks-ruby gem as you can take the XML from the cassette and put into a fixture. The code for this tutorial can be found on Github.

Encoding a QuickBooks QBXML Request

2015-02-05T00:00:00Z

In short: QBSDK doesn't like non ASCII characters

Are you receiving a QuickBooks found an error when parsing the provided XML text stream and are not missing required tags, tags are in the exact order, tags are all closed, and XML attributes are properly escaped? Then you probably have a non-ASCII character in your request.

This encoding is built-in to my to_qbxml gem but if you are using just using Nokogiri you can simply use .to_xml(encoding: 'US-ASCII') to get the proper encoding. If you aren't using Ruby you can use a standard HTML entities library with decimal encoding to get special characters into QuickBooks via the SDK.

QuickBooks v3 API error: An application error has occurred while processing your request: System Failure Error: java.lang.NumberFormatException: For input string: ""

2014-12-31T00:00:00Z

Problem:

In this particular case, an invoice had a line item with just a <ItemId />. If you include the ItemId node within an invoice it must be filled in with a value or you need to leave it off completely. If you are getting this error on another transaction or name entity then look for blank nodes.

QuickBooks Web Connector and subdomains

2014-12-29T00:00:00Z

You don't have to use SSL/TLS (HTTPS) when testing against the QuickBooks Web Connector. You can just use something like http://localhost or basically some URL with localhost at the start e.g. http://localhost-qbsdk or if a subdomain like this http://localhost.localhost but this http://demo.localhost will not work. Again, it must have localhost right after the http://.

Connect Rails and QuickBooks Online via Sandbox

2014-11-15T00:00:00Z

A better way: Sandboxes

In my series on wiring up Rails and QBO you needed to have a real QBO account to test against. Intuit was good about giving free trial accounts but that process has been eliminated with regards to U.S. based QuickBooks Online. In its place is the much more proper concept of a sandbox. In this screencast, I will upgrade the "Minimulcasts" app to use a sandbox, therefore, see this as an amendment to part 1 of the original series.

tl;dw

To create a sandbox, go to https://developer.intuit.com and sign in. At the bottom of the page, click on the link for setting up a sandbox.
Upgrade Rails and the Quickbooks-Ruby Gem

  
# previous : gem 'rails', '4.0.2'
gem 'rails', '4.1.6'
 
# previous : gem 'quickbooks-ruby', git: 'git://github.com/ruckus/quickbooks-ruby.git'
gem 'quickbooks-ruby', github: 'ruckus/quickbooks-ruby'

Bundle update Rails and Quickbooks-Ruby Gem

$ bundle update rails
  $ bundle update quickbooks-ruby

Enable Sandbox mode in config/initializers/quickbooks.rb and use shell variables.


# previous : QB_KEY = ""
# previous : QB_SECRET = ""
QB_KEY = ENV['MINIMULCASTS_CONSUMER_KEY']
QB_SECRET = ENV['MINIMULCASTS_CONSUMER_SECRET']

# add to the end of file
Quickbooks.sandbox_mode = true

Restart pow

$ touch tmp/restart.txt

Go to http://minimulcasts.dev
Click on the "Connect to Intuit button" and authorize your sandbox for usage.
To test, make a new vendor. Don't update an existing vendor as that will not work because it doesn't exist in this new sandbox.
Vendor should show up in your sandbox. (make sure you refresh the Vendor's link on the left side).

Remember the check the screencast for more details as well as the repo.

Connect to QuickBooks Angular directive

2014-11-03T00:00:00Z

Simple Connect button rendering

I was attempting to answer this SO question which referenced this angular directive for rendering a "Connect to QuickBooks" button. I fired up the gulp-angular generator but couldn't get that directive to work and in the process was was able to come up with a simpler approach.

Install the gulp-angular Yeoman generator, make a new dir, and run the generator.

  $ npm install -g generator-gulp-angular
  $ cd ~/github/labs
  $ mkdir connect-intuit-angular && cd $_
  $ yo gulp-angular

Install no additional items when prompted by the Yeoman wizard.

Barebones setup

Oops. The bower install failed.

Bower install crashes with EMALFORMED in bower.json

Take out the comma to fix.

Re-run bower install.
Test the generator doing a gulp serve.

Ok, the generator scaffolding is working.

Let's clean up some of the scaffolding stuff. Remove the awesomeThings array in src/app/main/main.controller.js

Remove awesomeThings array in controller.

Then remove the corresponding ng-repeat in src/index.html.

Clean up the view as well.

Make a new file src/app/main/directives.js and add the following.

/* src/app/main/directives.js */
angular.module('connectIntuitAngular')
.directive('connectToQuickbooks', function($window){
  return {
    restrict: 'E',    template: "<ipp:connectToIntuit></ipp:connectToIntuit>",
    link: function(scope) {
        var script = $window.document.createElement("script");
        script.type = "text/javascript";
        script.src = "//js.appcenter.intuit.com/Content/IA/intuit.ipp.anywhere.js";
        script.onload = function () {
           scope.$emit('intuitjs:loaded');
        };
        $window.document.body.appendChild(script);
        scope.$on('intuitjs:loaded', function (evt) {
          $window.intuit.ipp.anywhere.setup({ grantUrl: '/' });
          scope.connected = true;
          scope.$apply();
        });
    }
  }
});

Then in src/index.html do:

<!-- index.html -->
<div class="jumbotron" ng-init="connected = false">
  <div class="control-group">
    <div class="controls" ng-show="!connected">
      Loading QuickBooks Connect button
    </div>
    <div class="controls" ng-show="connected">
      <connect-to-quickbooks />
    </div>

  </div>
</div>

Let's check it out.

Connect to QuickBooks button is ready to go.

Handling external Javascript

There a few other ways to handle external Javascript dependencies in Angular but I like using the onload attribute in combination with Angular events as it is simple and easy to follow. In this refactoring I was able to save quite a few lines of code while improving read-ability.

Bare-bones QuickBooks Single Sign On with Rails

2014-10-27T00:00:00Z

Fundamental Rails/QuickBooks Single Sign On (SSO)

In my previous tutorial I went over implementing SSO with Rails and Devise. This tutorial will focus on a basic implementation featuring just Rails (4.1.6) with subdomains

Fire up a new rails app

$ rails new intuit_sso -T
$ cd intuit_sso

Add these to the Gemfile next

gem "omniauth", ">= 1.0.3"
gem 'omniauth-openid'

  bundle install

The config/initializers/omniauth.rb should look like this.

Rails.application.config.middleware.use OmniAuth::Builder do
  provider :open_id, :name => 'intuit', :identifier => 'https://openid.intuit.com/openid/xrds'
end

While in the initializers edit the config/initializers/cookies_serializer.rb

Rails.application.config.action_dispatch.cookies_serializer = :marshal

Minimul says —

It seems one of the core underlying gems, ruby-openid, is not playing nicely with the Rails 4.1 default of Rails.application.config.action_dispatch.cookies_serializer = :json

Make a Login controller with 2 actions, index and callback.

$ bin/rails g controller Login index callback

In app/views/login/index.html.erb put the Intuit SSO button.

<h1>Login#index</h1>
<ipp:login href="/auth/intuit" type="horizontal"></ipp:login>
<script type="text/javascript" src="https://appcenter.intuit.com/Content/IA/intuit.ipp.anywhere.js"></script>

Add these routes.

  
match '/auth/:provider/callback' => 'login#callback', via: [:get, :post]
root 'login#index', :constraints => { :subdomain => /.+/ }

Minimul says —

Just a reminder: Make sure you add both :get and :post for the callback.

Before we start working on the callback let's make a user.

  $ bin/rails g model User email password

The app/models/user.rb should look like this:

class User < ActiveRecord::Base

  def self.find_for_open_id(access_token)
    data = access_token.info
    if user = User.where(:email => data["email"]).first
      user
    else
      User.create!(email: data["email"], password: generate_token)
    end
  end

  def self.generate_token
    Digest::SHA1.hexdigest("#{Rails.application.config.secret_token}#{Time.now.to_i}")
  end

end

Now we can implement the callback action within app/controllers/login_controller.rb as so:

  
class LoginController < ApplicationController
  skip_before_filter :verify_authenticity_token, :only => [:callback]

  def index
  end

  def callback
    if user = User.find_for_open_id(request.env["omniauth.auth"])
      session[:user_id] = user.id
      redirect_to start_index_url
    else
      redirect_to root_url, notice: 'Auth fail'
    end
  end
end

Minimul says —

If you like to spin your wheels a bit and waste an hour or so go ahead and NOT skip the verify_authenticity_token.

You may have noticed a redirect to a non-existent route and controller, start_index_url, so let's implement that now.

$ bin/rails g controller Start index

In conjunction, let's fill in the route, controller, and view for this start redirect.

  # config/routes.rb
  get 'start/index', :constraints => { :subdomain => /.+/ }

# app/controllers/start_controller.rb
class StartController < ApplicationController
  def index
    @current_user = User.find(session[:user_id])
  end
end


<h1>Start#index</h1>
<h2><%= "Welcome #{@current_user.email}" %></h2>
<p>Find me in app/views/start/index.html.erb</p>

Now we are ready to test.

$ bin/rails s

Pump in a subdomain with lvh.me:3000 and click "Sign in with Intuit".

Fill in your QBO creds.

Successful sign on.

That concludes the tutorial for Bare-bones QuickBooks Single Sign On with Rails

Be sure to check out the screencast for more commentary as well as the code. For feedback use the comments area below rather than my email. If the question is broader than this tutorial use the Intuit Developer Forums, in which I regularly hang out.

Easily turn a Ruby Hash to QuickBooks XML

2014-10-07T00:00:00Z

I recently released a new Gem called to_qbxml. I created it in response to the current de facto Ruby Gem, Qbxml. Let me state right off the bat that I used much of that Gem's code for to_qbxml and want to thank the author, Alexsey, for all his OSS QuickBooks contributions.

Here are some of the issues I had with the Qbxml Gem:

QBXML requires repeatable nodes such as the InvoiceLineAdd node in the sample below but I had no idea how to do this with the Qbxml Gem.

<?xml version="1.0" encoding="utf-8"?>
<?qbxml version="7.0"?>
<QBXML>
  <QBXMLMsgsRq onError="stopOnError">
    <InvoiceAddRq requestID="1">
      <InvoiceAdd>
        <InvoiceLineAdd>
          <!-- omitted -->
        </InvoiceLineAdd>
        <InvoiceLineAdd>
          <!-- omitted -->
        </InvoiceLineAdd>
      </InvoiceAdd>
    </InvoiceAddRq>
  </QBXMLMsgsRq>
</QBXML>

Qbxml

repeat

# ----
# to_qbxml gem example of creating repeatable nodes
# ----
def line_item(line_number)
  {
    invoice_line_add: {
      item_ref: {
        list_id: '3243'
      },
      desc: "Line #{line_number}",
      amount: 10.99,
      is_taxable: true,
      quantity: 3,
      rate_percent: 0,
      repeat: [{
        line: {
          desc: 'inside'
        }
      }]
    }
  }
end
hash = { repeat: [ line_item(1), line_item(2) ] }
xml = ToQbxml.new(hash).make(:invoice)

Reliance on ActiveSupport::Inflector to handle QBXML case conversions

used within Rails

to_qbxml

Built-in validation is not needed.

OCR docs

QBXML validator and SDKTest utilities

Turning QBXML into a Ruby hash is not useful when it comes to reading QBXML

Nokogiri

to_qbxml

doc: true

n = ToQbxml.new(hash, doc: true).make(:invoice, action: :query)
expect(n.at('InvoiceQueryRq > IncludeLineItems').content).to eq 'true'
expect(n.at('InvoiceQueryRq > ModifiedDateRangeFilter > FromModifiedDate').content).to eq hash[:modified_date_range_filter][:from_modified_date]
expect(n.at('InvoiceQueryRq > ModifiedDateRangeFilter > ToModifiedDate').content).to eq hash[:modified_date_range_filter][:to_modified_date]
end

Hence a new Gem is born

Therefore, I ripped out these and some other "features" to create a lightweight and flexible but yet powerful Ruby Hash to QBXML library. Enjoy, and check out the screencast for more commentary.

Improve your QuickBooks/Ruby integration experience with the quickbooks-ruby-base gem

2014-04-21T00:00:00Z

Code from screencast and tutorial is available on Github.

Real-world to gem

I was recently able to wrap up a pattern from my QuickBooks/Ruby consulting into a gem. The gem complements and extends the quickbooks-ruby gem. Let's see how.

Speed up QB integration.

First, install the gem along with quickbooks-ruby.

Don't forget to bundle install.

Now you need to configure the persistent locations of the Intuit OAuth connection.

For example, if you are storing the token, secret, and company_id like this:

  account = Account.find(1)
  account.qb_token
  account.qb_secret
  account.company_id

Your config file might look like this.

This example comes from config/initializers/quickbooks.rb.

Next, I am going fire up the rails console to further demonstrate.
To create a quickbooks-ruby service takes only one line of code.

The service method is available off the base object so you can quickly access query, create, and update.

This one line saves 4 lines of code and is generic.

There is a qr_model method that generates and initializes a quickbooks-ruby model, which are long to type out by hand.

Before

After

You can pass as many arguments to the model as it takes.

This is an example of the email_address model.

Lastly, the show method will return a "smart" array, customers in this example.

"Smart" because the DESC value returned adapts to which service is being shown. For example, if its the invoice service calling show, then the doc_number is displayed for DESC (for customer service its display_name).
The show method saves you from having type the following below and it is most useful for console usage.

 $ base.service.query.entities.map{ |e| "ID: #{e.id} DESC: #{e.display_name}" }

You can also pass the same options you would to the quickbooks-ruby query method e.g.

  $ base.show(page: 1, per_page: 150)

The show alone method is worth installing the gem.

Contributing

I want to keep the gem light weight but I would love to see pull requests coming from your QuickBooks/Ruby integration experiences. You can see the making of this gem in this 4 part series.

Integrating Rails and QuickBooks Online via the version 3 API: Part 3

2014-02-07T00:00:00Z

Tutorial and screencast use Rails 4, Ruby 1.9.3, and Pow. Be sure to watch the screencast above as I unveil more details and tidbits than can be found in the article itself.

Code from screencast is available on Github

Continuing with Part 2, let's change the email address to test the update functionality. Go back to the browser and click 'Edit'.

Stop at the edit view so we can add some code to the vendors controller.

Add the following to the update action within the vendors_controller.

  def update
    respond_to do |format|
      if @vendor.update(vendor_params)
        vendor = @vendor_service.query.entries.find{ |e| e.given_name == vendor_params[:name] }
        # If you have more than 20 Vendor's use this
        # vendor = @vendor_service.query("SELECT * FROM VENDOR WHERE GivenName = '#{vendor_params[:name]}'").entries.first
        vendor.email_address = vendor_params[:email_address]
        @vendor_service.update(vendor)
        format.html { redirect_to @vendor, notice: 'Vendor was successfully updated.' }
        format.json { head :no_content }
      else
        format.html { render action: 'edit' }
        format.json { render json: @vendor.errors, status: :unprocessable_entity }
      end
    end
  end

The query.entries line is searching over your QuickBooks vendors that match the submitted name and then returning the vendor.

Go back to the browser and alter the email address.

Modify the email and click 'Update Vendor'.

Go back to QuickBooks Online and ascertain that the update was successful.

Go to the detail view to see if the email address was updated.

The email address update worked!

Now that you can connect your Rails app to QuickBooks Online and create and update objects, let me demonstrate how to use logging to examine API interaction more closely.
Add the following right above the update action in the vendors_controller.rb.


def update
  Quickbooks.logger = Rails.logger
  Quickbooks.log = true
  vendor = @vendor_service.query.entries.find{ |e| e.given_name == vendor_params[:name] }
  vendor.email_address = vendor_params[:email_address]
  @vendor_service.update(vendor)
  # ..omitted

Change the email address again and hit 'Update Vendor'.
Open the log/development.log

The quickbooks-ruby logging is demarcated with ------ New Request ------

Stay tuned

Now you should be pretty dangerous when tackling Rails and QBO integration using the version 3 API. I do have more articles and screencasts coming so be sure to sign up for my newsletter.

Integrating Rails and QuickBooks Online via the version 3 API: Part 2

2014-02-05T00:00:00Z

Tutorial and screencast use Rails 4, Ruby 1.9.3, and Pow. Be sure to watch the screencast above as I unveil more details and tidbits than can be found in the article itself.

Code from screencast is available on Github

Continuing with Part 1, add an email_address attribute to the Vendor.

$ rails g migration add_email_address_to_vendors email_address
$ bundle exec rake db:migrate

Update the views to reflect adding email_address.

app/views/vendors/_form.html.erb

... omitted
<div class="field">
    <%= f.label :email_address %><br>
    <%= f.email_field :email_address %>
</div>
... omitted

app/views/vendors/index.html.erb

   ... omitted
    <tr>
      <th>Name</th>
      <th>Email address</th>
      <th></th>
      <th></th>
    </tr>
  </thead>

  <tbody>
    <% @vendors.each do |vendor| %>
      <tr>
      ... omitted
        <td><%= vendor.email_address %></td>
        <td><%= link_to 'Show', vendor %></td>
        <td><%= link_to 'Edit', edit_vendor_path(vendor) %></td>
        <td><%= link_to 'Destroy', vendor, method: :delete, data: { confirm: 'Are you sure?' } %></td>
      </tr>
    <% end %>
  ... omitted

app/views/vendors/show.html.erb

... omitted
<p>
  <strong>Email address:</strong>
  <%= @vendor.email_address %>
</p>
... omitted

Reload browser to test that the views have been updated.
Create a new vendor on Rails and QuickBooks Online.

Create a before_action filter within app/controllers/vendors_controller.rb to activate the vendor service.


class VendorsController < ApplicationController
  before_action :set_vendor, only: [:show, :edit, :update, :destroy]
  before_action :set_qb_service, only: [:create, :edit, :update, :destroy]
#... omitted
    private
#... omitted
    def set_qb_service
      oauth_client = OAuth::AccessToken.new($qb_oauth_consumer, session[:token], session[:secret])
      @vendor_service = Quickbooks::Service::Vendor.new
      @vendor_service.access_token = oauth_client
      @vendor_service.company_id = session[:realm_id]
    end
end

Whitelist the email_address attribute within the vendors_controller.

    def vendor_params
      params.require(:vendor).permit(:name, :email_address)
    end

Alter the create action within the vendors_controller.

  # .. omitted

  def create
    @vendor = Vendor.new(vendor_params)
    vendor = Quickbooks::Model::Vendor.new
    vendor.given_name = vendor_params[:name]
    vendor.email_address = vendor_params[:email_address]
    @vendor_service.create(vendor)
    respond_to do |format|
    # .. omitted
  end

For a “real app” you should have the quickbooks-ruby code always handy to guide you in mapping your vendors (or customers, employees, etc.). In this example, use the quickbooks-ruby vendor model code as a reference.

To see all available Vendor attribute mappings, reference the gem code itself.

Also be aware that many models have mixed-in methods, so check for include keywords. For example, the vendor model draws methods from the NameEntity module.

Reload browser and then click New vendor link.

Fill in form and click 'Create Vendor'.
Go over to your QuickBooks Online account and check if the vendor was composed.

Goto 'Company' tab, then to 'Activity Log' submenu. Next, click on the vendor's name within the activity tab to get more details.

Looking good.

Next, updating a vendor in Rails and QuickBooks Online

In Part 3 I demonstrate updating an entity at QBO. I also exhibit basic debugging using the logging feature of quickbooks-ruby.

Integrating Rails and QuickBooks Online via the version 3 API: Part 1

2014-02-03T00:00:00Z

Minimul says —

IMPORTANT: Intuit has introduced and requires developing against sandboxes for U.S. QBO.

See my new article, Connect Rails and QuickBooks Online via Sandbox, which would come in around step 4 or so for this article.

Tutorial and screencast use Rails 4, Ruby 1.9.3, and Pow. Be sure to watch the screencast above as I unveil more details and tidbits than can be found in the article itself.

Code from screencast is available on Github

If you haven't already, sign up at Intuit Partner Platform

If you already have a QBO account you can use your username and password to join as a developer. If you are a developer desiring a test account then email Intuit @ ippdevelopersupport@intuit.com and request a developer subscription to QBO.

Create a new app.

Select 'Quickbooks API'.

Fill in the form like in this figure and "Save". Note: the minimulcasts.io is provided because a real domain is needed to get past the validations.

Next, your app tokens and keys are generated.

Create a new Rails app and hook it up with Pow.

$ cd ~/www/labs # example
$ rails new minimulcasts
$ ln -s ~/www/labs/minimulcasts ~/.pow
$ curl -L minimulcasts.dev | grep "Welcome" # Test POW
$ cd minimulcasts

Add the quickbooks-ruby and oauth-plugin gems.

# Gemfile -> add these two gems:
gem 'quickbooks-ruby'
gem 'oauth-plugin'
$ bundle install

Beget Vendor scaffolding

$ rails g scaffold Vendor name
$ bundle exec rake db:migrate

Create config/initializers/quickeebooks.rb.


QB_KEY = "<copy from developer.intuit.com>"
QB_SECRET = "<copy from developer.intuit.com>"

$qb_oauth_consumer = OAuth::Consumer.new(QB_KEY, QB_SECRET, {
    :site                 => "https://oauth.intuit.com",
    :request_token_path   => "/oauth/v1/get_request_token",
    :authorize_url        => "https://appcenter.intuit.com/Connect/Begin",
    :access_token_path    => "/oauth/v1/get_access_token"
})

Modify config/routes.rb.

Minimulcasts::Application.routes.draw do
  resources :vendors do
    collection do
      get :authenticate
      get :oauth_callback
    end
  end

  root to: 'vendors#index'
end

Make sure application level changes take by reloading with a touch tmp/restart.txt
Next, hook actions up to those new routes app/controllers/vendors_controller.rb.

Minimul says —

Pay attention to the Rails 4.1 and greater notes in the next 2 methods.

  # app/controllers/vendors_controller.rb
  # .. code omitted

  def authenticate
    callback = oauth_callback_vendors_url
    token = $qb_oauth_consumer.get_request_token(:oauth_callback => callback)
    session[:qb_request_token] = token
    # If Rails >= 4.1 you need to do this => session[:qb_request_token] = Marshal.dump(token)
    redirect_to("https://appcenter.intuit.com/Connect/Begin?oauth_token=#{token.token}") and return
  end

  def oauth_callback
    at = session[:qb_request_token].get_access_token(:oauth_verifier => params[:oauth_verifier])
    # If Rails >= 4.1 you need to do this =>  at = Marshal.load(session[:qb_request_token]).get_access_token(:oauth_verifier => params[:oauth_verifier])
    session[:token] = at.token
    session[:secret] = at.secret
    session[:realm_id] = params['realmId']
    redirect_to root_url, notice: "Your QuickBooks account has been successfully linked."
  end

  private

  # .. code omitted

You will persist the token, secret & realmId to the database. Those 3 items are needed to communicate with QBO. For brevity, sessions are used for persistence.

Add Intuit Connect button to application layout at app/view/layouts/application.html.erb.

  .. omitted
  <body>
    <!-- REPLACE THE BODY of the default application.html.erb with this -->

    <% unless session[:token] %>
      <ipp:connectToIntuit></ipp:connectToIntuit>
    <% end %>

    <% if notice %>
      <div style="padding: 10px;background: gainsboro;font-weight: 900;width: 50%;"><%= notice %></div>
    <% end %>

    <%= yield %>

    <script type="text/javascript" src="https://appcenter.intuit.com/Content/IA/intuit.ipp.anywhere.js"></script>

    <script>
        intuit.ipp.anywhere.setup({menuProxy: '/path/to/blue-dot', grantUrl: '<%= authenticate_vendors_url %>'});
    </script>
  </body>

In your browser go to: http://minimulcasts.dev

Connect with QuickBooks button is generated from Intuit.

Click on the 'Connect with QuickBooks' button

Put in your QuickBooks Online username and password.

Then click the 'Authorize' button.

Once authenticated Intuit will return a GET request to the /vendors/oauth_callback.

We are now authorized to communicate with QuickBooks Online.

Finally, double check that the QBO connection was successful by logging into QuickBooks Online then go to the 'Company' tab and then to the 'Activity Log' submenu.

That confirms it.

Next, creating a vendor in Rails and QuickBooks Online

In Part 2 I demonstrate actually creating an entity over at QBO.

Get started integrating Rails 4 and QuickBooks Online with the Quickeebooks Gem: Part 4 : Implementing Single Sign On.

2014-01-02T00:00:00Z

Part 1: Make an OAuth connection between a Rails 4 app & QBO.
Part 2: Create a Vendor on both Rails app and QBO.
Part 3: Disconnecting from QBO.
Part 4: Implementing Single Sign On.
Code presented below is also available on Github

Part 4: Implementing Single Sign On for a Rails app.

Install devise for authentication

Add gem 'devise' in Gemfile and run bundle install
Run rails g devise:install on command line
Modify config/environments/development.rb

  config.action_mailer.default_url_options = { host: 'billtastic.dev' }

Modify config/routes.rb with root to: 'vendors#index'

Billtastic::Application.routes.draw do
  resources :vendors
  resources :quickbooks do
    collection do
      get :authenticate
      get :oauth_callback
      get :disconnect
    end
  end
  root to: 'vendors#index'
end

Create a Devise user.

  rails g devise user
  bundle exec rake db:migrate

Add sign up code to the app/views/layouts/application.html.erb

  <section id="sign-in">
    <% if user_signed_in? %>
        Signed in as <strong><%= current_user.email %></strong>.
      <%= link_to 'Edit profile', edit_user_registration_path %> |
      <%= link_to "Sign out", destroy_user_session_path, method: :delete %>
    <% else %>
      <%= link_to "Sign up", new_user_registration_path %> |
      <%= link_to "Sign in", new_user_session_path %>
    <% end %>
  </section>

Issue a touch tmp/restart.txt to reload Rails.

Refresh billtastic.dev/vendors and you will see a basic sign in implementation

Note: Styling code, which is very minimal, will not be included in the tutorial. See the source instead.

Add the "Sign on with Intuit" button.

Add the omniauth-openid gem to the Gemfile and bundle install.
Modify config/initializers/devise.rb with the following:

require 'openid/store/filesystem'
Devise.setup do |config|
  # ommited ....
  # Insert this next line down in the Omniauth section
  config.omniauth :open_id, :store => OpenID::Store::Filesystem.new('/tmp'), :name => 'intuit', :identifier => 'https://openid.intuit.com/openid/xrds', :require => 'omniauth-openid'

Modify app/models/user/rb:

class User < ActiveRecord::Base
  # Include default devise modules. Others available are:
  # :confirmable, :lockable, :timeoutable and :omniauthable
  devise :database_authenticatable, :registerable,
         :recoverable, :rememberable, :trackable, :validatable,
                  :omniauthable, :omniauth_providers => [:intuit]
         
           def self.find_for_open_id(access_token, signed_in_resource=nil)
             data = access_token.info
             if user = User.where(:email => data["email"]).first
               user
             else
               User.create!(:email => data["email"], :password => Devise.friendly_token[0,20])
             end
           end
end

Create a new file app/controllers/users/omniauth_callbacks_controller.rb:

class Users::OmniauthCallbacksController < Devise::OmniauthCallbacksController
  skip_before_filter :verify_authenticity_token, :only => [:intuit]

  def intuit
    @user = User.find_for_open_id(request.env["omniauth.auth"], current_user)

    if @user.persisted?
      flash[:notice] = I18n.t "devise.omniauth_callbacks.success", :kind => "Intuit"
      sign_in_and_redirect @user, :event => :authentication
    else
      session["devise.intuit_data"] = request.env["omniauth.auth"]
      redirect_to new_user_registration_url
    end
  end
end

Modify the Devise users route in config/routes.rb to:

Billtastic::Application.routes.draw do
  devise_for :users, :controllers => { :omniauth_callbacks => "users/omniauth_callbacks" }
  # ommitted

Add "Sign on with Intuit" button to app/views/layouts/application.html.erb.

  <!-- omitted .. -->
      <%= link_to "Sign up", new_user_registration_path %> |
      <%= link_to "Sign in", new_user_session_path %> | 
      <ipp:login href="<%=
      user_omniauth_authorize_path(:intuit) %>"></ipp:login>
    <% end %>

Issue a touch tmp/restart.txt to reload Rails.

Refresh billtastic.dev/vendors and you will now see the official Intuit Sign On button.

Automatically authenticate with the QBO API after signing on with Intuit.

  <!-- app/views/layouts/application.html.erb -->
  <!-- ommited.. -->
  <script type="text/javascript" src="https://appcenter.intuit.com/Content/IA/intuit.ipp.anywhere.js"></script>
  <!-- configure the Intuit object: 'grantUrl' is a URL in your application which kicks off the flow, see below -->
  <script>
      intuit.ipp.anywhere.setup({menuProxy: '/path/to/blue-dot', grantUrl: '<%= authenticate_quickbooks_url %>'});
    <% if user_signed_in? && !session[:token] %>
        intuit.ipp.anywhere.directConnectToIntuit();
    <% end %>
  </script>
</body>

Discussion: Even though we are using Intuit's authentication to sign into our Rails app we still need to "connect" to QuickBooks to integrate with the QBO API. The directConnectToIntuit() Javascript function automatically starts the API authentication process where the connectToIntuit() requires a user to click the button.

Note: We are simply using the Devise's user_signed_in? method but in a real-world implementation we would have to further distinguish whether the login originated at Intuit.

Since directConnectToIntuit() will not be launched in a popup we need to modify the app/views/vendors/close_and_redirect.html.erb view to handle this condition.

<script>
setTimeout(function(){
    if(window.opener == null){
      window.location = '<%= @url %>';
    }else{
      window.opener.location = '<%= @url %>';
      window.close();
    }
}, 10000);
</script>

Note: If window.opener is null then the Intuit API authentication request is not running in a popup (as seen in Part 1).

Now we are ready to sign in using Intuit.

Click on the "Sign in with Intuit" button.

Next, you will be prompted for your QuickBook's credentials.

You will then be briefly brought back to the Rails app, which then the directConnectToIntuit() code will kick in and take you to this page.

Here is the close_and_redirect.html.erb modifications from step 3 in action.

Lastly, we make it back again to the Rails app. Notice that the diconnect link is showing because we are authenticated against the Intuit API (1). Moreover, using Devise we are properly logged into the Billtastic Rails app (2) using our Intuit credentials.

The infamous "blue dot" menu

Stay tuned to Part 5 where I will implement the Intuit blue dot menu.

Get started integrating Rails 4 and QuickBooks Online with the Quickeebooks Gem: Part 3 : Disconnecting with QuickBooks

2013-12-17T00:00:00Z

Part 1: Make an OAuth connection between a Rails 4 app & QBO.
Part 2: Create a Vendor on both Rails app and QBO.
Part 3: Disconnecting from QBO.
Part 4: Implementing Single Sign On.
Code presented below is also available on Github

Part 3: Disconnect the Rails app from QB0.

Let's start by updating the view, app/views/layouts/application.html.erb, to show a disconnect link

  <% unless session[:token] %>
    <ipp:connectToIntuit></ipp:connectToIntuit>
  <% else %>
    <div>
      <%= link_to 'Disconnect from QuickBooks', '', data: { confirm: 'Are you sure you want to disconnect?' 
    </div>
  <% end %>

Reload

Simple disconnect link to get the ball rolling. We'll come back later and add the href target.

DISCUSSION: We need a disconnect action but the vendors_controller is getting crowded, therefore, let's create the quickbooks_controller. This is also a perfect place for the authenticate and oauth_callback actions so we are going to move them before creating the disconnect action.

Make a new quickbooks_controller and move the authenticate and oauth_callback actions from the vendors_controller to here.

The new controller at app/controllers/quickbooks_controller.rb should look like the code below. Notice the highlighted sections that also need to be modified.

class QuickbooksController < ApplicationController

  def authenticate
    callback = oauth_callback_quickbooks_url
    token = $qb_oauth_consumer.get_request_token(:oauth_callback => callback)
    session[:qb_request_token] = token
    redirect_to("https://appcenter.intuit.com/Connect/Begin?oauth_token=#{token.token}") and return
  end

  def oauth_callback
    at = session[:qb_request_token].get_access_token(:oauth_verifier => params[:oauth_verifier])
    session[:token] = at.token
    session[:secret] = at.secret
    session[:realm_id] = params['realmId']
    flash.notice = "Your QuickBooks account has been successfully linked."
    @msg = 'Redirecting. Please wait.'
    @url = vendors_path
    render 'vendors/close_and_redirect', layout: false  end

end

Modify config/routes.rb:

Billtastic::Application.routes.draw do
  resources :vendors
  resources :quickbooks do
    collection do
      get :authenticate
      get :oauth_callback
    end
  end
end

Then modify the following line in app/views/layouts/application.html.erb to reflect the new authenticate route.

  <script>
      intuit.ipp.anywhere.setup({menuProxy: '/path/to/blue-dot', grantUrl: '<%= authenticate_quickbooks_url %>'});
  </script>

Finally, make sure you issue a touch tmp/restart.txt to restart the app as the routes have changed.

DISCUSSION: We are still not done with the refactoring. The disconnect action uses a different Quickeebooks service then from the one used in the vendors controller so let's make the set_qb_service method more flexibility.

Allow set_qb_service to create additional services.

Remove the set_qb_service from vendors_controller and move it to application_controller and modify it as such:

class ApplicationController < ActionController::Base
  # Prevent CSRF attacks by raising an exception.
  # For APIs, you may want to use :null_session instead.
  protect_from_forgery with: :exception

  private

    def set_qb_service(type = 'Vendor')
      oauth_client = OAuth::AccessToken.new($qb_oauth_consumer, session[:token], session[:secret])
      @service = "Quickeebooks::Online::Service::#{type}".constantize.new
      @service.access_token = oauth_client
      @service.realm_id = session[:realm_id]
    end
end

Next, modify the vendors_controller instance vars of @vendor_service to be just @service

Reload billtastic.dev/vendors to test that the refactorings have taken effect with no errors.
Add the disconnect route.

Billtastic::Application.routes.draw do
  resources :vendors
  resources :quickbooks do
    collection do
      get :authenticate
      get :oauth_callback
      get :disconnect
    end
  end
end

Add the disconnect action to the quickbooks_controller


  def disconnect
    set_qb_service('AccessToken')
    result = @service.disconnect
    if result.error_code == '270'
      msg = 'Disconnect failed as OAuth token is invalid. Try connecting again.'
    else
      msg = 'Successfully disconnected from QuickBooks'
    end
    session[:token] = nil
    session[:secret] = nil
    session[:realm_id] = nil
    redirect_to vendors_path, notice: msg
  end

DISCUSSION: The disconnect action uses the AccessToken module/service from Quickeebooks. It provides a disconnect instance method that makes an API call requesting the disconnect. Intuit states that an error_code of 0 indicates a successful request but I have found that an error_code of '22' worked fine and the connection was properly disconnected. The session's are cleared in all cases because even on a disconnect failure this indicates that the current credentials are invalid and creating a new connection may be the solution.

IMPORTANT: There are many points were the Intuit v2 API doesn't work exactly as stated in the docs as in the above example were I received an error code of '22' but the disconnect worked fine. Don't beat yourself up because you are not obtaining responses precisely as described in the documentation. Just shrug your shoulders and move on.

Before we test disconnecting, let's log into the Intuit Partner Platform like we did in Part 1. From there navigate to My Apps->Manage My Apps and then to the Billtastic app.

Notice that you should have at least one live API connection

We will use this view to confirm that we successfully disconnected.

While we are here let's also change the disconnect url to billtastic.dev/quickbooks/disconnect.

Before

After

NOTE: This url change is not needed for this tutorial and is only used for when a disconnect action is initiated from the Intuit App Center. We want to make the change now while we are here and the new disconnect route is fresh in our minds.

Let's go back to the Billtastic.app at billtastic.dev/vendors and click on the 'Disconnect from QuickBooks' link.

Click thru the confirmation dialog.

Yeah! A successfully disconnect.

The 'Connect to QuickBooks' button also correctly displays now that the session[:token] is nil.

Let's make sure the disconnect occurred by checking over at the Intuit Partner Platform.

Ok, that confirms it. There was 1 connection last time we checked (see Fig. 2).

Implementing Single Sign On

Stay tuned to Part 4 in where I will hook up the Billtastic app with the ability to use your Intuit QBO credentials to sign on. This is referred to as "Single Sign On" by Intuit and is needed if you desire to have your application listed on their App Center.

Get started integrating Rails 4 and QuickBooks Online with the Quickeebooks Gem: Part 2

2013-11-04T00:00:00Z

Part 1: Make an OAuth connection between a Rails 4 app & QBO.
Part 2: Create a Vendor on both Rails app and QBO.
Part 3: Disconnecting from QBO.
Part 4: Implementing Single Sign On.
Code presented below is also available on Github

Part 2 aim

Create and update a vendor on both the Rails app and QB0.

Add an email_address attribute to the Vendor.

$ rails g migration add_email_address_to_vendors email_address
$ bundle exec rake db:migrate

Add email_address to the views.

app/views/vendors/_form.html.erb

... omitted
<div class="field">
    <%= f.label :email_address %><br>
    <%= f.email_field :email_address %>
</div>
... omitted

app/views/vendors/index.html.erb

   ... omitted
    <tr>
      <th>Name</th>
      <th>Email address</th>
      <th></th>
      <th></th>
    </tr>
  </thead>

  <tbody>
    <% @vendors.each do |vendor| %>
      ... omitted
      <tr>
        <td><%= vendor.email_address %></td>
      
        <td><%= link_to 'Show', vendor %></td>
        <td><%= link_to 'Edit', edit_vendor_path(vendor) %></td>
        <td><%= link_to 'Destroy', vendor, method: :delete, data: { confirm: 'Are you sure?' } %></td>
      </tr>
    <% end %>
  ... omitted

app/views/vendors/show.html.erb

... omitted
<p>
  <strong>Email address:</strong>
  <%= @vendor.email_address %>
</p>
... omitted

Reload browser at billtastic.dev/vendors and test that the views have been updated.
Create a new vendor locally and within QBO.

Add a before_action filter within app/controllers/vendors_controller.rb to activate the Quickeebooks vendor service.


class VendorsController < ApplicationController
  before_action :set_vendor, only: [:show, :edit, :update, :destroy]
  before_action :set_qb_service, only: [:create, :edit, :update, :destroy]
#... omitted
    private
#... omitted
    def set_qb_service
      oauth_client = OAuth::AccessToken.new($qb_oauth_consumer, session[:token], session[:secret])
      @vendor_service = Quickeebooks::Online::Service::Vendor.new
      @vendor_service.access_token = oauth_client
      @vendor_service.realm_id = session[:realm_id]
    end
end

DISCUSSION: Put before_action after the set_vendor filter, which was created by the scaffolding generator in Part 1. The set_qb_service method should be private and the very last method of the class.

Whitelist the email_address attribute within the vendors_controller.

    def vendor_params
      params.require(:vendor).permit(:name, :email_address)
    end

Modify the create action within the vendors_controller.

  def create
    @vendor = Vendor.new(vendor_params)
    vendor = Quickeebooks::Online::Model::Vendor.new
    vendor.name = vendor_params[:name]
    vendor.email_address = vendor_params[:email_address]
    @vendor_service.create(vendor)
    respond_to do |format|
      if @vendor.save
        format.html { redirect_to @vendor, notice: 'Vendor was successfully created.' }
        format.json { render action: 'show', status: :created, location: @vendor }
      else
        format.html { render action: 'new' }
        format.json { render json: @vendor.errors, status: :unprocessable_entity }
      end
    end
  end

Go to the browser and refresh billtastic.dev/vendors and then click New vendor link.

Fill in these fields and click 'Create Vendor'.
Go over to QBO and check to see that the vendor was created.

Navigate to the 'Company' tab and then to the 'Activity Log' submenu. Also, click on the vendor's name within the activity tab to get more details.

Great, we can see that the email address was also created.

Now let's change the email address to exercise Quickeebooks' update functionality. Go back to the browser and click 'Edit'.

After you get to the edit view stop as we are going add some code the vendors_controller.rb.

Modify the update action within the vendors_controller.

  def update
    respond_to do |format|
      if @vendor.update(vendor_params)
        vendor = @vendor_service.list.entries.find{ |e| e.name == vendor_params[:name] }
        vendor.email_address = vendor_params[:email_address]
        @vendor_service.update(vendor)
        format.html { redirect_to @vendor, notice: 'Vendor was successfully updated.' }
        format.json { head :no_content }
      else
        format.html { render action: 'edit' }
        format.json { render json: @vendor.errors, status: :unprocessable_entity }
      end
    end
  end

DISCUSSION: The first highlighted line is searching your QBO vendor entries that match the submitted name and then returning the vendor. Notice in the next line that I only have the email_address as an update-able attribute and not name. This is because the name attribute for a Vendor (and other QBO entities such as Employee and Customer) is a unique attribute and can't be modified.

Let's go back to the browser, which should be at the url billtastic.dev/vendors/1/edit.

Change the email address and click 'Update Vendor'.

Go back to QBO and check to see that the update was successful.

Click on the vendor's name to see if the email address was updated.

Yay! The email address update worked!

Finished Next

This concludes a 2-part tutorial where a QuickBooks Online entity was created and updated from a Rails app. I sincerely hope this series aids your ramp up time in getting integrated with QuickBooks Online. Of course, don't hesitate to point out errors or ask for clarification within the article's comments. This tutorial continues with Part 3 that demonstrates disconnecting from QBO.

Get started integrating Rails 4 and QuickBooks Online with the Quickeebooks Gem: Part 1

2013-10-31T00:00:00Z

Part 1: Make an OAuth connection between a Rails 4 app & QBO.
Part 2: Create a Vendor on both Rails and QBO.
Part 3: Disconnecting from QBO.
Part 4: Implementing Single Sign On.
Code presented below is also available on Github

IMPORTANT: Tutorial uses Rails 4, Ruby 1.9.3, and Pow(hence OSX). Adapt for your ecosystem.

Part 1 aim

Perform all the steps necessary to make an OAuth connection from a Rails 4 app (called Billtastic) to your QuickBooks Online (QBO) Account.

Join the Intuit Partner Platform

DISCUSSION: I am going to assume you have a QBO account, which you can use your existing QBO username and password to join as a developer. If you are a developer and want to have a sandbox account then email Intuit @ ippdevelopersupport@intuit.com and request a developer subscription to QBO Plus.

After joining you will be asked to confirm your email. Even after confirming, you may continue to receive an error stating that you haven't confirmed. To get past this, log on and then off again.

Create a new app.

After joining up and confirmation your email, create a new QuickBooks API app.

Fill in your card like this one and click the "Save". Note: the billtastic.io is entered just because you need a real domain to get past the field's validations.

After saving, your app tokens and keys will be presented. The consumer key and secret need to be added to the Rails app, which is down in step 6.

Create a new Rails app and hook it up with Pow.

$ cd ~/www/labs # My experimental area
$ rails new billtastic
$ ln -s ~/www/labs/billtastic ~/.pow # Hook up Pow
$ curl -L billtastic.dev | grep "Welcome" # Test hook up

Add the quickeebooks and oauth-plugin gems to the Gemfile and run bundle install.

# Edit the Gemfile and add these two gems:
gem 'quickeebooks'
gem 'oauth-plugin'
$ bundle install

Generate Vendor scaffolding

$ rails g scaffold Vendor name
$ rake db:migrate

DISCUSSION: In Part 2 a Vendor will be created in both Rails & QBO but for now we are going to piggyback on the Vendor scaffolding view code to do the authentication.

Create a new YAML config file called config/quickbooks.yml:

# The values here are just examples. Cut and paste the values that were generated in Step 2. See Fig. 3
key: qshfas789asfa98fafdafaff
secret: FFasfafs435345FAADFGAGA452345345afdfaffasdfaf

Create config/initializers/quickeebooks.rb.

QB_CREDS = YAML.load(File.read(File.expand_path('./config/quickbooks.yml', Rails.root)))

$qb_oauth_consumer = OAuth::Consumer.new(QB_CREDS['key'], QB_CREDS['secret'], {
  site:                "https://oauth.intuit.com",
  request_token_path:  "/oauth/v1/get_request_token",
  authorize_url:       "https://appcenter.intuit.com/Connect/Begin",
  access_token_path:   "/oauth/v1/get_access_token"
})

Add the following routes to config/routes.rb.

Billtastic::Application.routes.draw do
  resources :vendors do
    collection do
      get :authenticate
      get :oauth_callback
    end
  end
end

Add the actions app/controllers/vendors_controller.rb for the routes we added in the previous step.

  # app/controllers/vendors_controller.rb
  # .. code omitted

  def authenticate
    callback = oauth_callback_vendors_url
    token = $qb_oauth_consumer.get_request_token(:oauth_callback => callback)
    session[:qb_request_token] = token
    redirect_to("https://appcenter.intuit.com/Connect/Begin?oauth_token=#{token.token}") and return
  end

  def oauth_callback
    at = session[:qb_request_token].get_access_token(:oauth_verifier => params[:oauth_verifier])
    session[:token] = at.token
    session[:secret] = at.secret
    session[:realm_id] = params['realmId']
    flash.notice = "Your QuickBooks account has been successfully linked."
    @msg = 'Redirecting. Please wait.'
    @url = vendors_path
    render 'close_and_redirect', layout: false
  end

  private
  # .. code omitted

DISCUSSION: In a real app you will persist the token, secret & RealmID to the database for a user. Those 3 items are needed to communicate with QBO. For convenience, sessions are being used for persistence in this tutorial.

Add Intuit Connect button code to application layout on app/view/layouts/application.html.erb.

  .. omitted
  <body>
    <!-- REPLACE THE BODY of the default application.html.erb with this -->

    <% unless session[:token] %>
      <ipp:connectToIntuit></ipp:connectToIntuit>
    <% end %>

    <% if notice %>
      <div style="padding: 10px;background: gainsboro;font-weight: 900;width: 50%;"><%= notice %></div>
    <% end %>

    <%= yield %>

    <script type="text/javascript" src="https://appcenter.intuit.com/Content/IA/intuit.ipp.anywhere.js"></script>

    <script>
        intuit.ipp.anywhere.setup({menuProxy: '/path/to/blue-dot', grantUrl: '<%= authenticate_vendors_url %>'});
    </script>
  </body>

DISCUSSION: For a tutorial it is a bit heavy handed to put this code into the application layout, however, for a production app Intuit requires that their blue dot menu to be displayed on each page so you might find yourself putting Intuit scripts in the layout.

Reload with a touch tmp/restart.txt.
Let's take a look. Navigate your browser to billtastic.dev/vendors and you should see this:

Now we are almost ready to Connect with QuickBooks

Create app/views/vendors/close_and_redirect.html.erb to handle the redirect from QuickBooks.

<!DOCTYPE html>
<html>
<head>
  <title><%= @msg %></title>
</head>
<body>
<h3><%= @msg %></h3>

<script>
 setTimeout(function(){ window.opener.location = '<%= @url %>'; window.close(); }, 10000);
</script>
</body>
</html>

DISCUSSION: Go back to step 9 and checkout the oauth_callback action as it is responsible for rendering the close_and_redirect view. Also, read my article that explains this above code in more detail.

Go back to the browser on billtastic.dev/vendors, click on the 'Connect with QuickBooks' button, and sign in

Put in your QBO username and password and click the 'Sign in' button.

Then click the 'Authorize' button.

After a successful authentication, Intuit will return a GET request to the /vendors/oauth_callback. Again, see the oauth_callback action in step 9 to see what is going on.

This is the Step 13 view code in action.

Success! We are now authorized to communicate with QuickBooks.

Lastly, let's double check that the QBO connection was indeed successful. Go to QBO, login, and navigate to the 'Company' tab and then to the 'Activity Log' submenu.

You should see that you signed in.

Next episode, creating an entity

In Part 2 I will dig a bit more into the Quickeebooks gem by creating a vendor on the Rails app as well as in QBO.

Does Intuit require OpenID for QuickBooks Online integration?

2013-08-26T00:00:00Z

You do not need to implement OpenID to integrate with QuickBooks Online (QBO). However, if you want your app listed on the Intuit App Center than yes, OpenID support is required.

First, ask yourself if your app needs a Intuit App Center listing.

It might seem like a no brainer to desire an Intuit App Center listing but since implementing OpenID is just another checkbox in your long list of integration todos considering skipping the App Center listing if your application has the following characteristics:

It is not a horizontal, financial based application.
- Applications that benefit most from App Center exposure are going to be ones that are financial in nature such as a SAAS billing service since they have strong ties into accounting. Horizontal applications, whether financial in essence or not, may also stand to benefit from a listing.
Is an "internal" application only used inside the company firewall.
Your sign ups are primarily coming from different marketing channels.
- If your application sells say, cedar-based sidings, your target audience is not going to find you through the Intuit App Center but instead from channels closely aligned to your niche.

In short, take some time to consider the importance of App Center publicity so as to not further delay the launch of your application's QBO integration.

Handling the QuickBooks OAuth callback

2013-07-03T00:00:00Z

Intuit requires a popup to OAuth.

When OAuth'ing with another service like Twitter, EBay, etc. it is common to redirect the user using the entire page as it makes returning back to the host application technically easier. Intuit, however, requires for C2QB compliance that authentication happens in a popup.

Solution: 2 step process to handle the QuickBooks OAuth callback

Example is in Rails but easily translates to different web dev ecosystems.

1.

Example of the controller action that maps to the Intuit App Card route/url regarding the handling of the OAuth callback (e.g. /quickbooks/oauth_callback). The "Intuit App Card" is what they call the area that various names and urls are set for development and production. Make sure to persist the QuickBooks OAuth credentials in this step.


  def oauth_callback
    # ... code omitted for saving the account's OAuth secret and token
    if # ... omitted ...
      # Set flash.notice as this will persist even when using the javascript based redirect in step 2
      flash.notice = "Your QuickBooks account has been successfully linked to your account."
      @msg = 'Redirecting. Please wait.'
      @url = quickbooks_accounts_path
    end
    render 'shared/close_and_redirect'
  end

2.

Here is the content of shared/close_and_redirect rendered from step 1. The window.opener refers to your main or original page that initiated the authentication popup. Therefore, the window.opener.location will navigate to the route you specified in @url within the main page. Lastly, the authentication popup is closed and the user is properly OAuth'd and ready to communicate with QuickBooks.

!!!
%html
  %head
    %title= @msg 
  %body
    %h3= @msg

    :javascript
      setTimeout(function(){ window.opener.location = '#{@url}';window.close(); }, 2000);