Transaction Import - misterhaan/abe GitHub Wiki

Transaction import relies on code in the bank-specific files in /etc/class/banks/, each of which extends the abeBank class. Most banks provide a handful of formats for transaction downloads, usually including CSV and Quicken (QFX). Typically CSV is the most efficient because PHP supports it and the file contains very little other than the data. In some cases the bank does not include all of the data Abe can use in the CSV format so it’s necessary to use one of the others, which is usually OFX SGML.

Each bank class should include at least one static function named ParseExtTransactions where Ext is the file extension (such as ParseCsvTransactions or ParseOfxTransactions) with the first character in upper case and the other letters in lower case. It will be passed the filename to read transactions from as a parameter. A Parse*Transactions function should read transactions from the file and collect them in an array as objects with properties matching the transactions table (leave out id, account, category, splitcat, and reviewed). leave the properties null or as empty strings if the bank does not provide them. abeBank provides a TitleCase function which is usually used for the name, city, and notes fields so that they aren’t in all caps. Sum up all the amounts from the transactions and save that in the net property of the return object. The array of transactions must be the transactions property of the return object. Return false if unable to parse transactions. The return object is expected to conform to the following structure:

// objects like $transaction for each transaction
$transaction->extid = null;  // transaction id from the financial institution, or null if not provided
$transaction->transdate = null;  // transaction date formatted YYYY-MM-DD, or null if not provided
$transaction->posted = '2016-12-31';  // transaction posting date formatted YYYY-MM-DD (required)
$transaction->name = '';  // transaction name, generally name of the other party
$transaction->amount = 12.34; // transaction amount (positive for income / credit / refund, negative for spending.  required)
$transaction->city = null;  // transaction city, or null if not provided
$transaction->state = null;  // transaction state, or null if not provided
$transaction->zip = null;  // transaction zip code, or null if not provided
$transaction->notes = '';  // transaction notes, or empty string if not provided

// return an object like $return
$return->transactions = [$transaction, $transaction2, $transactionN];  // array of all transaction objects from the file
$return->net = 123.45;  // sum of all transaction amounts

It’s possible to define more than one Parse*Transactions function to support multiple file types. Sometimes more than one download option provide almost the same contents but with different extensions (for example, Microsoft Money, Quicken, and Quickbooks are all OFX SGML files). In those cases the Parse*Transactions function could just call another one.

Bank classes are defined in the banks table, which the setup script installs from banks.csv. Add a new row for the new bank, with the name of the bank’s class (and filename) as the first column, the display name as the second column, and the URL to the bank’s login page as the third column. This update to a data file means the Data value in abeVersion needs to be incremented and the setup script needs some code to add the new row.

Since bank websites aren’t always the easiest to navigate especially when looking for transactions downloads, consider adding instructions to the Abe Usage Guide.