Adding Support For Another Institution
Clone this wiki locally
You can help expand the list of supported institutions in two ways:
- 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.
- 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!
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
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.
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.
Write The Code
You can look at the Zions Bank implementation (lib/syrup/institutions/zions_bank.rb) for ideas or help.
- 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
rakefrom the terminal or command prompt).
- Create a file for the new institution in the lib/syrup/institutions folder.
- Start a new class in the
- Your new class should:
- Inherit from
- 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
Accountobjects representing all accounts at the institution
fetch_account- Accepts an
account_id. Either returns one
Accountor an array like
fetch_accountswhere one of the accounts in the array has the corresponding
fetch_transactions- Accepts an
starting_atdate, and an
ending_atdate. Returns an array of
Transactionobjects. The dates are both inclusive (eg. 2011-01-01 to 2011-01-31 returns all transactions for January).
- Inherit from
- Submit a pull request and I'll review it and accept it!
Each of the fetching methods will have access to three properties:
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