-----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----- _______________________________________________ gnucash-devel mailing list [EMAIL PROTECTED] http://www.gnucash.org/cgi-bin/mailman/listinfo/gnucash-devel
