README.OFX ----------- 1. Introduction 2. Requirements 3. Implemented features 4. The import process and transaction matching 5. When it goes wrong... 6. FAQ 7. Credits 1. Introduction ----------- Since the first 1.7.x beta releases, GnuCash features OFX online banking support. This makes it the world's first *free* OFX-enabled personal finance manager. The development of OFX and HBCI support also spawned the a new generic import infrastructure, including a much improved transaction matcher. OFX (Open Financial eXchange) is an open standard increasingly popular for offering bank, credit card and investment statement download, as well as other services, such as bill payment. Features requiring direct access to a bank's OFX server are not yet supported. 2. Requirements ------------ LibOFX 0.7.0 or later http://libofx.sourceforge.net/ which in turn requires: OpenSP 1.3.x or later, http://openjade.sourceforge.net/ Then you enable OFX support by building GnuCash with: --enable-ofx added to ./autogen.sh (for CVS) or ./configure (for tarballs) make If successful, an item will appear in Gnucash's File/Import sub menu. If you installed libofx in a non-standard location, you may also have to use: --with-libofx-prefix=/your/libofx/prefix 3. Implemented features ------------ Implemented features (some of these are from the generic import module): -OFX/QFX response file import -Account matching, using unique OFX account ID -Full OFX bank and credit card transaction support. -Explicit support for investment transactions, including stock reinvest and dividends. -Commodity import and matching, for investment transactions. -Transaction duplicate detection, using the unique OFX transaction ID. Even if downloaded twice, transactions are only imported once. -Transaction duplicate detection, using amount, date, check number, full or partial memo, full or partial description. -"Destination" account matching, using exact string match on either memo or description. -Saves ALL transaction data currently supported by LibOFX. When no gnucash equivalent, it is put in the Transaction's Note field. You must have double-line mode enabled to view the notes field. -Files containing multiple statements are supported, and transactions can be matched at the same time. 4.The import process and transaction matching ---------- First, you must successfully download an OFX response file from your bank. If you successfully built GnuCash with ofx support, you will be able to select the file from the File / Import / Import OFX/QFX menu item. Note that Ofx files can contain information for multiple accounts, depending on the number of accounts in your file, and the presence of absence of investment transactions, the following two windows will popup one or multiple times: A) Account matching window. -Look carefully at the information in the top part of the window. From that info you should be able to determine which of your accounts this is. -Select the matching GnuCash account from the list if there is one, or create a new one with the button at the bottom. If you choose to create a new one, currency, account type and name will be filled in for you. Feel free to change the name to whatever you like. NOTE: -investment accounts will cause more than one account to be matched/created in GnuCash. Most will cause a cash and a stock account to be created. In addition, if there are dividends in the transaction, you will be asked to choose an Income account. -All account matches are remembered, and you will not be asked on subsequent imports. B) Commodity matching window If your statement contains information like stock transactions, you will be asked to match the stock to a GnuCash commodity. The process is similar to account matching above. The match is remembered by the Commodity CUISP. Once the process of account and commodity matching is done, you will be presented with the transaction matcher window. Let's learn how to use it by an example. Let's assume you import Credit Card/Savings/Checking accounts in that order (3 separate imports), and your accounts start with no transactions: You will first have all new transactions in Credit Card, some of which are transfers going into checking. You then import you savings Savings account, which will also have misc transactions, and presumably some going into Checking. You then import your Checking account. The matcher will see duplicate transactions in checking (Those who have a split in Credit Card and Savings), and will only clear the split in Checking for those. The other transactions in savings will be imported as new. What most people don't understand about this process is that there are two different types of matches that can be done by the importer on a single transaction. The first kind of match will determine if a duplicate of this transaction exists in GnuCash. If that match determines that there isn't (or if the user overrides), a second match will be done to try and find the appropriate account to add a split to the transaction (only if the transaction isn't already balanced). Now, for the specifics, there are two possibilities: A- You are a "Do everything daily" kind of guy. You write a GnuCash transactions every time you write a check, spend money, etc. Suppose you spend 40$ on your credit card at "Overpriced Restaurant". When you come back or at the end of the week when you get rid of all the receipt in your wallet, you enter a 40$ transaction from "Credit Card" to "Expenses->Restaurant". At the end of the week, month, year or whenever, you download your credit card statement. The importer will spot duplicates (with a certain confidence level represented by the red, yellow and green bars) and by default mark them as cleared. If you forgot to enter some transactions, the matcher will have an inconclusive match or will consider them as new and treat them like in the next scenario. B- You are an "Do everything at once kind of guy". You don't write your transactions as they occur, instead you download your statement at the end of the month. Now the importer should find that all transactions in your credit card are new (except maybe payments, if you imported your checking account prior to your credit card account). The first time you import from that account, all transactions will say "Need an account to Auto-Balance xxx$". You will then pick an account for each one. In the case of the 40$ we talked about, you select "Expenses->Restaurant" (the importer already knows it's coming from "Credit Card"). Now the next month (since you never learn) you go to "Overpriced Restaurant" AGAIN. Assuming your bank gives you a minimum of info electronically, the importer will remember that a transaction at "Overpriced Restaurant" from account "Credit Card", goes to "Expenses->Restaurant". All transactions are already cleared at this stage. In both scenarios, all transactions are balanced at creation time, and are in the exact same accounts. 5. When it goes wrong... ----------------- Tough much effort has been put in implementing relevant parts of the OFX standardas well as possible, and gracefully treating parts that are not supported, OFX is not implemented in a consistent manner across banks. If you do encounter a problem, please report it to the developers (ideally with a sample file) If you encounter an error, you can report it in one of the following ways (in order of effectiveness for you, but ANY report is apreciated): * Open a bug at https://bugs.gnucash.org/ * gnucash-devel@gnucash.org or gnucash-user@gnucash.org (Subscriber-only list; please subscribe on https://lists.gnucash.org/mailman/listinfo/ ) * http://lists.sourceforge.net/lists/listinfo/libofx-devel/ if ofxdump doesn't give you the expected data. * many developers hang on the IRC channel #gnucash on irc.gnome.org Please remember to include the following information in your report: The version numbers of gnucash, libofx and OpenSP as well as any console output and/or output of the ofxdump utility on your file. 6. FAQ ---------- (1) GnuCash simply hangs when importing an OFX file This is probably bug https://bugs.gnucash.org/show_bug.cgi?id=101738 Unfortunately the main developpers are unable to reproduce. So far, this bug only occurs with OpenSP 1.5. It does not occur for anyone with OpenSP 1.3.x, which is shipped on most Linux distro as part of openjade, so you may want to downgrade. (Please note that OpenSP 1.3.x has several other issues however) This bug is beleived to be a threading issue, and may be a problem in GnuCash, LibOFX, OpenSP, or some versions of the Linux kernel. If you have any useful info,please add a comment to the bug above (even if only to say you encountered the bug,and your version of the previously mentioned packages). (2) Why doesn't GnuCash support direct connections to bank like Quicken/Money I am striving to get this working, but banks are simply not cooperative in general, and my bank doesn't support it at all, so it will not be easy to debug once implemented. All I can say is "We're working on it...". But there are many steps left to be taken. (3) I don't see the File / Import / Import OFX/QFX menu item! If you don't see the menu mentioned above, then GnuCash was not built/compiled with --enable-ofx. Please try to compile GnuCash by yourself or contact the place where you got your pre-compiled version of GnuCash from. (4) When I import in OFX/HBCI, and change the destination account in the matcher, why doesn't other transaction with the same memo/description change? The matcher already "learns" where transactions are assigned. The only problem is thatcurrently, it only uses what it has learned on the next import. Re-processing the list during the import process is a feature you can hopefor early in the 1.8 series. (5) Can GnuCash support QFX files (Quicken Financial eXchange?) As far as GnuCash is concerned, QFX and OFX files are identical. (6) What about OFC support (Open Financial Connectivity, a Microsoft standard) OFC is a SGML based format still very commonly used in Brazil, and less frequently by banks all over the world. The main author of LibOFX managed to find specs, but needs the OFC DTD (Data Type Definition) to add support. That file is supposed to be available from a link an this page: http://support.microsoft.com/default.aspx?scid=kb%3Ben-us%3B162872 However, despite numerous requests to Microsoft to either fix the broken link or send him a copy of the file, they still haven't done so. That file is probably free to redistribute, and was part of their OFC development toolkit. If you still have a copy or know where to get one, please send the information to bock@step.polymtl.ca (7) Where do I find/How do I download OFX files for bank XYZ? Somewhere on one of the banks website. We can't say anymore than this, the address, interface, and origin of the info used as user id and password changes from bank to bank. (8) Can I export my Gnucash data in QIF, OFX, CSV, etc. ? Export capability is currently being built into LibOfx. 7. Credits------- The LibOFX library is written by Benoit Gr�goire The Generic Import Infrastructure was written by Benoit Gr�goire , Christian Stimming and Derek Atkins . By Benoit Gr�goire Sunday, Feb 2, 2003