Adding Support For Another Institution

You can help expand the list of supported institutions in two ways:

1. Find a way to get me a username and password to the bank's website so that I can implement it. This is pretty risky for you AND me. We'd need to talk about this if you are willing to go this route.
2. You can implement support for this institution yourself. This is preferred because of an issues with trust and I don't have to do it!

Overview

I tried to make it fairly simple and straightforward to implement new institutions/banks. Supposedly, there is a standard way to access banks the way Microsoft Money or Quicken does it using OFX or a variation of OFX. However, institution support for those methods is really hard to find. So, after doing some research, it appears that Mint.com and other websites have resorted to scraping the bank's websites for the data. That is the method that is used in this gem.

A Couple Things To Get Familiar With

1. Mechanize - This is a Ruby Gem that makes it really simple to get webpages, simulate button clicks, etc. It uses Nokogiri to allow you to get data off of the page.

   • Getting Started With Mechanize
   • Mechanize Documentation
   • Mechanize Examples
   • Nokogiri Documentation

2. Firebug/Developer Tools in your browser. It is really nice to use Firebug for Firefox or the Developer Tools in other browsers to figure out which webpages are being requested. For example, once you're logged into Zions Bank, there are several AJAX requests that get fired. One of them returns JSON with all the details of all of the user's accounts. Because of this, requesting the main Zion's Bank page is useless. Only the request for the JSON is needed.

   • Firebug homepage
   • Chrome Developer Tools

Write The Code

You can look at the Zions Bank implementation (lib/syrup/institutions/zions_bank.rb) for ideas or help.

1. The first thing to do is fork the repository, clone it to your computer and run the tests to make sure they all pass (just run rake from the terminal or command prompt).
2. Create a file for the new institution in the lib/syrup/institutions folder.
3. Start a new class in the Syrup::Institutions namespace.
4. Your new class should:
   • Inherit from InstitutionBase
   • Have two class methods:
     • name - returns the name of the institution
     • id - returns an id of the institution (eg. 'zions_bank'). This is what you'll use to get an instance of this class.
   • Have three instance methods:
     • fetch_accounts - Returns an array of Account objects representing all accounts at the institution
     • fetch_account - Accepts an account_id. Either returns one Account or an array like fetch_accounts where one of the accounts in the array has the corresponding account_id.
     • fetch_transactions - Accepts an account_id, a starting_at date, and an ending_at date. Returns an array of Transaction objects. The dates are both inclusive (eg. 2011-01-01 to 2011-01-31 returns all transactions for January).
5. You can create a test file (e.g. ./spec/syrup/institutions/your_institution_spec.rb) to try out your code. To run your tests use the rspec ./path/to/test.rb command.
6. Submit a pull request and I'll review it and accept it!

Each of the fetching methods will have access to three properties: username, password, and a Hash of secret_questions where the key is the question and the value is the answer.

If the username, password, or secret_questions are invalid or weren't supplied, you should raise an InformationMissingError.