Generic Account Mapper

Benoit Grégoire bock@step.polymtl.ca
Mon, 11 Nov 2002 14:58:51 -0500


On November 11, 2002 02:02 pm, Derek Atkins wrote:
> Christian and I were discussing the generic (target) account mapper
> on #gnucash earlier today.  This email is a summary of the results
> and a proposed API for the _engine_ portion of the mapper.  The
> UI portion is still undefined.
>
> The basic design is that each import protocol could define the
> types of matches to map, and the precedence of the map.  The core
> infrastructure has no particular tie to any match category.
>
> The API is based around a GncImportMatchMap object, which is a map
> database for a particular import object.  There could be an ImportMap
> for each import account, or it could be per-book:
>
>  typedef struct _GncImportMatchMap GncImportMatchMap;
>
>  GncImportMatchMap* gnc_imap_map_from_account (Account*);
>  GncImportMatchMap* gnc_imap_map_from_book (GNCBook*);
>
> Within an import map there is a "map category" (or a map-type) and a
> key that will map to an account.  There is an API to lookup an Account
> based on the category and key, and another API to _set_ the map to an
> Account based on the category and key:
>
>  void gnc_imap_set_account (GncImportMatchMap*, const char* category,
>                             const char* key, Account*);
>  Account* gnc_imap_get_account (GncImportMatchMap*, const char* category,
>                                 const char* key);
>
> We could also define some "well known" match categories:
>
>  #define GNC_IMAP_DESC	"desc"
>  #define GNC_IMAP_MEMO	"memo"
>  #define GNC_IMAP_PAYEE	"payee"
>
> The UI will need some way to prioritize the various categories and
> provide getter functions for each category type in order to read the
> data from the to-be-imported transactions.  However, that discussion
> is for another email.
>
> Any comments on this API?

Sorry, didn't have time to answer your previous emails on that subject.  It's 
been a very hectic week (but a very profitable one...).

Personally, I don't really see the usefullness of the match categories as 
proposed.  There are to possibilities as to where the match functions are 
called.  

Option 1:  Protocol level
The match functions are designed to be called before the transaction structure 
is passed to the generic importer (which means they are called by the ofx or 
HBCI modules.  In that case the protocol knows what are the best fields to 
match with.  The gnc_imap functions don't have to know what they are 
matching, it should just match against one big table per source account.  The 
protocol module can try to match as many strings as it wants, in wathever 
order it wants.  Life would be perfect, except that we will then have a UI 
nightmare when we want to change the match manually.  The generic matcher 
will have no reliable way to know that a split was auto created and can be 
changed by the user.  So this brings us to:

Option 2:  Generic matcher level
Here, we are in Gnucash world.  The only strings available for matching are 
the transaction "Description" and "Note" fields, and the splits "Memo" 
fields.  So there is a finite number of "match categories".  The only way 
around that is to pass the match strings as part of the parameters of 
gnc_import_add_trans.  In that case the parameters would be some generic 
"match_string_1", "match_string_2" etc., but I think two would be enough.  
The strings would only be matched against a single table, with no type.  If 
match_string_1 doesn't match anything, try with match_string_2 on the same 
table.  I can't think of a case where matching against a single list of 
string per acount would give wrong or misleading results compared to matching 
against one table per priority.

Perhaps I missed something....