… or “how does KMyMoney map accounts to/from AqBanking“.
Since the author of AqBanking recently posted the question how this works, I think it is a good idea to document it in a publically visible way. First of all: why do we need mapping at all? KMyMoney as well as AqBanking deal with the representation of bank accounts and assign each such object an internal ID. Unfortunately, both of them use a different ID for the same account and so one needs some way of turning a KMyMoney ID into an AqBanking ID and vice versa. This is what we are talking here.
Since KMyMoney does not only support AqBanking as an online banking backend it provides a standardized interface to all of them. Also, a set of procedures is defined to support a wide range of possible backends. Now we deal with two different interfaces: one required for KMyMoney and another one required by AqBanking. The trick here is the glue-logic residing in KBanking. It does all the magic that is needed for a successful marriage of the two participants.
How the connection is constructed
The connection between the two accounts on each side of the glue-logic is called mapping. It is started by a call to KBanking::mapAccount(). This method takes two parameters: the account object in KMyMoney and a key-value-store which holds all variables required in the process that need to be stored with the account object. The contents of that key-value-store is only known to KBanking (or any other online banking glue code).
mapAccount() itself creates the dialog KBMapAccount and displays all available AqBanking account inside a list. The user can select an account out of the list for the mapping. Once this has been done, KBanking creates a unique mappingId for the KMyMoney account which consists of the storage ID and the account ID. This needs to be done, because the same account ID may exist in different KMyMoney files but identifies completely different accounts. This allows to map the same account ID in different files to the same or different AqBanking account without problems. Check KBankingExt::mappingId() how it is constructed.
This unique mapping ID is then assigned as alias to the AqBanking account using AB_Banking_SetAccountAlias(). Next the account reference for the AqBanking account will be constructed out of the routing and account number by extracting data from AB_Account_GetBankCode() and AB_Account_GetAccountNumber(). Leading zeros are stripped and both elements are joined with a dash (‘-‘) in between. This resulting value is stored in the key-value-store under the key kbanking-acc-ref.
From KMyMoney to AqBanking
The method KBanking::aqbAccount() takes a reference to a KMyMoney account and returns a pointer to the respective AB_Account structure by calling AB_Banking_GetAccountByAlias() with the above mentioned unique ID.
The other way around
Based on values returned by AB_Banking_GetAccountByAlias() and AB_ImExporterAccountInfo_GetBankCode() the acc-ref is constructed and searched within the set of available KMyMoney accounts. This is performed as part of the import process in KBankingExt::importAccountInfo().