Friday, October 19, 2007

GnuCash 2.2 on Ubuntu Gutsy - with OFX Direct Connect!

When I started running Ubuntu Gutsy (7.10) about a month and a half ahead of its release this week, its GnuCash package was still in the 2.0 series, and I wanted to run 2.2. While 2.2 is now in the official repositories, I understand that a licensing issue prevents the Ubuntu GnuCash package from shipping with OFX Direct Connect enabled (it will import qfx/ofx files but not connect directly to financial institutions to retrieve transactions, as one of mine requires). So, with both of these goals in mind, I set out to build my own GnuCash 2.2 with OFX Direct Connect. Unfortunately, this process is not for the average user...

Building GnuCash

First, get a terminal open and install all the dependencies for this process:

sudo aptitude install libktoblzcheck1-dev libqt3-mt-dev libofx-dev libxml2-dev libgconf2-dev guile-1.6-slib guile-1.6-dev libglib2.0-dev libgtk2.0-dev libgnomeui-dev libgoffice-0-dev libgtkhtml3.8-dev libgwenhywfar38-dev slib gettext devscripts build-essential

Whew! Now we need to build libchipcard3-3.0.3, a dependency of the aqbanking library we will build later. This has no dependencies. For the uninitiated, this process consists of unpacking the archive and then executing the following in a terminal:

cd [folder in which you unpacked libchipcard]
sudo make install

That done, we build aqbanking 2.3.2. This is similar to building libchipcard above, but you have to pass some arguments when running the configure step:

./configure --with-frontends="cbanking g2banking qbanking"

Now download and unpack the latest GnuCash 2.2 source. You are looking for the latest archive starting with just "gnucash." Go through the same process again, except do the following for the configure step:

./configure --enable-ofx --enable-hbci

Configuring OFX Direct Connect

That's it--once you are done, you should have a shiny installed GnuCash 2.2 with OFX Direct Connect support (you will have an Actions > Online Actions menu). Next comes the frustrating process of figuring out how to connect to your bank! This is where applications like Quicken and Microsoft Money have done the hard work for you and baked in all these details. Unfortunately, it is somewhat difficult to find out the parameters you need to pass from the Direct Connect interface to get a successful download. The GnuCash wiki has a nice article that details some of the settings and contains instructions for downloading a script that will pull down the raw information about thousands of financial institutions. Follow these instructions to get the configuration information about your bank.

Add a User

Once you have this done and have located the details for your financial institution, in GnuCash, go to Tools > Online Banking Setup. The Online Banking Setup Wizard will launch. Click the Forward button until you see the button labeled Start Aqbanking Wizard, and click it. In the AqBanking Wizard, go to the Users tab and click New.

Here's where the guesswork begins. Many fields exist in the wizard that may or may not be used by your particular institution. For example, for Charles Schwab, I put my online login (user) name in all three of the User name, User Id, and Customer Id fields. If you are downloading transactions from a bank account, put your bank's ABA routing number (the number at the bottom left of your checks) in the Bank Id field, and specify the country of your bank. For my credit card, I did specify the country, but put arbitrary text in the Bank Id field (I probably could have left it blank).

Now let's move on to the OFX tab. Using the information downloaded about your financial institution, enter any of the FID, ORG, and Broker Id values that the institution is using (there will be values for those nodes in the downloaded XML file). Put the OFX server URL in the Server URL field in its complete https:// format. It doesn't seem to matter if you specify HTTP 1.0 or 1.1, and in fact with the version of the code I compiled, it always saves it as 1.0 regardless of what I do.

For the checkboxes at the bottom, typically just check the following and then click the Get Accounts button:
  • Supports Account List Download
  • Supports Statement Download
  • (and, if a credit card) Send Empty Bank Id

You will be prompted for your password, and then it should pull down all the settings for the account(s) you have at that institution under the Accounts tab. You may wish to review what it downloaded and poke around in these settings, but I can't give any specific advice.

Downloading Transactions

Once you have set up your institutions and accounts, you are ready to download. NOTE: some institutions (like Chase) have a setting in your online (not GnuCash) account configuration to enable OFX download before any of this will work. To get your transactions, open the account in GnuCash and click Actions > Online Actions > Get Transactions. When downloading for the first time, you may be prompted to accept the SSL certificate of the site, and you WILL be prompted to associate the GnuCash account with the OFX account you set up. Once you have done this, for subsequent downloads, just open the GnuCash account, go to the Get Transactions as above, and key in your password (the application does not store passwords).

I hope this helps someone. While not for the faint of heart, it IS possible to have GnuCash downloading transactions directly from your bank/credit card company without any intervening file downloads.

1 comment:

  1. If I wanted to write a program independent of GnuCash, Quickbooks, Quicken or whatever to connect to my financial institutions directly and download my financial information automatically, then how would I do this? Can anyone point me in the right direction? I have tried contacting multiple banks and they aren't any help?