HBCI data structures and Gnucash

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-----