Merging a new account tree into an existing file
[GUI]

Files
file	druid-merge.h
	API for merging two QofBook* structures with collision handling.
Defines
#define	GNC_QSF_IMPORT   "gnc-qsf-import-druid"
Functions
void	gnc_ui_qsf_import_merge_druid (QofSession *original, QofSession *import)
void	currency_transfer_cb (QofInstance *ent, gpointer user_data)
	gncCommodity is not QOF enabled, need to set a default commodity before the merge
void	reference_parent_cb (QofInstance *ent, gpointer user_data)
	workaround for AccountGroup not being fully QOF enabled. Eh?

---

Detailed Description

Collision handling principles.

This druid builds a second QofBook in memory using QofSession and populates the book with accounts created using the usual New Account Tree code. The druid then uses qof_book_merge_init to begin the merge of the new book (created with QofSession) with the existing QofBook (loaded by the user), with user intervention and collision handling.

1. Always check for a GncGUID first and compare. qof_book_merge only accepts valid QofBook data and therefore ALL objects in the import book will include valid GncGUID's.
2. If the original import data did not contain a GncGUID (e.g. an external non-GnuCash source) the GncGUID values will have been created by QofSession and will not match any existing GncGUID's in the target book so objects that do not have a GncGUID match cannot be assumed to be MERGE_NEW - parameter values must be checked.

• If a GncGUID match exists, set QofBookMergeRule::mergeAbsolute to TRUE.
  1. If ALL parameters in the import object match the target object with the same GncGUID, set QofBookMergeResult to MERGE_ABSOLUTE.
  2. If any parameters differ, set MERGE_UPDATE.
• If the import object GncGUID does not match an existing object, mergeAbsolute is unchanged from the default FALSE The parameter values of the object are compared to other objects of the same type in the target book.
  1. If the same data exists in the target book with a different GncGUID, the object is tagged as DUPLICATE.
  2. If the data has changed, the object is tagged as REPORT.
  3. If the data does not match, the object is tagged as NEW

More information is at http://code.neil.williamsleesmill.me.uk/

Each foreach function uses g_return_if_fail checks to protect the target book. If any essential data is missing, the loop returns without changing the target book. Note that this will not set or return an error value. However, g_return is only used for critical errors that arise from programming errors, not for invalid import data which should be cleaned up before creating the import QofBook.

Only qof_book_merge_init, qof_book_merge_update_result and qof_book_merge_commit return any error values to the calling process.