gnucash/doc/README.OFX

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 developement 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 http://bugzilla.gnome.org/
* gnucash-devel@gnucash.org or gnucash-user@gnucash.org (Subscriber-only list;
please subscribe on http://www.gnucash.org/cgi-bin/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 http://bugzilla.gnome.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 wan't 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 usefull 
info,please add a comment to the bug above (even if only to say you encountered 
the bug,and your version of the previously mentionned 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
adress, 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<47>goire <bock@step.polymtl.ca>
The Generic Import Infrastructure was written by Benoit Gr<47>goire 
<bock@step.polymtl.ca>, Christian Stimming <stimming@tuhh.de> and Derek Atkins 
<warlord@mit.edu>.

By Benoit Gr<47>goire <bock@step.polymtl.ca>
Sunday, Feb 2, 2003