HBCI data structures and Gnucash
Christian Stimming
stimming@tuhh.de
Thu, 9 May 2002 22:58:18 +0200
-----BEGIN PGP SIGNED MESSAGE-----
This should describe the basic data structures that are used by the German
online banking standard HBCI and their relation to the data structures found
in Gnucash.
1. Intro
The communication protocol according to the HBCI standard has been
implemented in the project OpenHBCI http://openhbci.sf.net . Since that
implementation provides an API that still requires some knowledge about the
HBCI internals, another library has been implemented as a wrapper API around
OpenHBCI and that one is called libaqmoney http://aqmoney.sf.net . All
HBCI-related functions that will be used from inside gnucash are going to be
located inside that wrapper API. (I'm now a developer on both projects.)
Apart from those details, online banking deals with just a few different data
types, and I'm going to describe which ones they are and where they should
belong to inside Gnucash, IMHO. This is meant to kick off a discussion for
both the HBCI developers as well as other Gnucash developers (especially if
they are working on yet more online banking standards) on whether this seems
to be the "right way" of implementing online banking in Gnucash.
2. HBCI
Online banking in HBCI deals with Banks, Accounts, and Customers.
An Account belongs to one Bank. An Account belongs to one Customer (of that
Bank). An Account offers a bunch of different actions that can be performed
upon it: "get balance", "get statement" (in german "Umsatz" bzw.
"Kontoauszug"), "perform money transfer", and more. (Those actions will be
performed instantly through means of the HBCI protocol, but that will be
discussed in a later posting during the next days.) An account has an account
number that is unique within its Bank (both in real-life and HBCI). A user
can assign a clear-text name to an Account, but that would just be for
presentation purposes and has no technical meaning for HBCI.
A Bank has a number of Accounts that belong to it, and a number of Customers
that belong to it. For the HBCI protocol, a Bank has an IP address and port
number (unique, of course :). A Bank has a bank number (german:
"Bankleitzahl", BLZ) that is unique (both in real-life and HBCI) within
Germany (I don't know about other countries). A Bank has a public-private key
pair for authentication and encryption; its public key will be verified by
the customer through means of the key fingerprint being sent to the customer
via paper mail. Additionally, a Bank has a name and a postal address, but for
HBCI those don't matter.
A Customer belongs to one Bank. A Customer can have a number of Accounts that
belong to it. A Customer has a user ID (i.e. text string) that uniquely
identifies the customer to the Bank (specifically for HBCI). A Customer has a
public-private key pair for authentication and encryption; his public key
will be verified by the bank through means of an "Ini-Letter", where the user
prints the key fingerprint on paper, signs it and sends it to the bank via
paper mail. (Alternatively there's a chip card based solution, where a
Customer owns a chip card that was given to him by the Bank.) Also, a
Customer has a real-life clear-text name, but IIRC for HBCI that doesn't
matter.
3. Gnucash
In Gnucash, we "only" have accounts. An account may or may not have parent
accounts and may or may not have child accounts. Each account belongs to one
book. A Book is "a set of accounting books" (uh?) -- in most cases a book is
one gnucash data file (sorry, I don't use the SQL backend, so I can only talk
about the file backend).
Transactions are done between accounts, i.e. an account has a list of Splits.
Every split belongs to one transaction. A Transaction consists of two or more
splits that (for correct book-keeping) should sum up to zero.
4. HBCI support in Gnucash
I think the HBCI concept of an Account *directly* maps to the Gnucash concept
of an account. But the HBCI concept of Banks and Customers do not have any
direct counterpart in Gnucash -- a user can have accounts belonging to
different banks inside the same gnucash book, and the accounts inside one
gnucash book don't need to belong to the same person or HBCI Customer.
The wrapper API for HBCI will provide functions which take configuration data
as arguments, so that the API will learn about the HBCI Banks, Accounts and
Customers that I'm about to use. For enabling HBCI support in Gnucash, IMHO
that configuration data should be stored in the same place as the gnucash
accounting data, namely, in the gnucash datafile or database backend.
Several data structures of Gnucash provide means of storing and retrieving
arbitrary data through what is called "kvp_frame", sets of key-value
association pairs. There is a kvp_value type "binary" which holds raw data
(with the length being specified). As Dave told me recently, Gnucash will
automagically provide the storage and retrieval of those kvp_frames (correct
me here if I'm wrong). Therefore in that places we could store any
configuration data that the HBCI API needs for working. The data can be
generated by the HBCI API at account setup time, be returned to gnucash for
storage, and passed back to the HBCI API when HBCI actions should be
performed.
I think that the data for the HBCI data type "Account" should be stored in
the kvp_frame of gnucash's accounts. I.e., each gnucash account that has a
real-life counterpart which is accessible via HBCI should have a kvp_value
that holds the configuration data for the corresponding HBCI Account. The
HBCI Account will need information about its HBCI Bank and Customer which do
not have any counterpart in gnucash. So I think that the configuration data
about HBCI Banks and Customers might just be stored in the kvp_frame of the
gnucash Book. I.e. the list of HBCI Banks and Customers used is stored once
in the gnucash data file and that's it.
5. Usage Example
The user requests a HBCI action e.g. when the "transfer" dialog has a button
meaning "Commit this transfer, and perform it in HBCI too". Then gnucash
grabs the HBCI data of the originating account from the kvp_frame of that
account. That account belongs to one HBCI Bank and Customer. Gnucash thus
grabs the HBCI data of the HBCI Bank and HBCI Customer from the book's
kvp_frame. This three objects are plugged into the HBCI API to initialize it.
Then gnucash tells the initialized HBCI API to "perform a money transfer".
(Alternatively those actions can be queued so that a bunch of jobs can be
performed in one connection, but that will be discussed at a later stage).
Then the HBCI API talks to the bank according to the HBCI protocol, performs
the action, and returns the result "Money transfer completed". That's it.
Comments? Improvements?
Christian
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.5 (GNU/Linux)
Comment: For info see http://www.gnupg.org
iQCVAwUBPNri6mXAi+BfhivFAQHufgP/YfG3SDVo9jLnSfM95xc4bdKOxLwvZWR+
nCIVCviDplqTk6l60NtAkcmSi7gCahFpJbF2Eo+KKjRlnT5Krne8zsf9ttIE19Se
de+tIOQ/h+FHIIlhfehV6dtnO336UzjshOxBo4UeKzLLAU1ZqKHsUOl2ctMqUVxw
635MnoD7I/0=
=It3t
-----END PGP SIGNATURE-----