handle Agreement changes over time

Current behavior

At the moment, pressing "Analyze Agreement" (backend: POST /from-agreement) will populate the AGREEMENT_ENTRIES table with new entries based on Agreement Lines. Existing entries will not be modified but during reporting entries with the same agreementId will be considered "duplicate" and will be subsequently filtered out when retrieving individual reports. adam please confirm this is correct

This means that changes to the agreement or related objects may not be represented correctly in the reports.

Expected behavior

The "Analyse Agreement" functionality should always clear all previous AGREEMENT_ENTRIES that refer to the analysed agreement – e.g no history should be retained/cached.

Additionally, the "Analyze Agreement" process should handle the fact that the Agreement, Agreement Lines, Packages, Purchase Order Lines and Invoice Lines may change as follows:

• Agreement: it's an ongoing contract for access to a specific resource(s). The Agreement represents both past and present e.g new subscription info will be attached to the Agreement via POLines and Invoices.

• Agreement Lines: the assumption is that Agreement Lines will not be removed or added unless this change should apply to all subscription periods (e.g fixing a data entry error). Instead, if a particular Agreement Line represents an item that has been removed from or added to a specific subscription period the corresponding "Active from" and "Active to" fields will be filled out by the librarian. Hence all history is retained on the Agreement and the "Analyze Agreement" process should capture these fields and handle them appropriately during reporting.

• Packages: a similar mechanism for indicating the "Active from" and "Active to" fields is present in the KB which stores the Package contents. These fields too should be handled by the "Analyze Agreement" process to ensure that title count data is valid for all subscription periods.

• Purchase Order Lines: generally, when a specific Agreement (or part of) is extended for a new subscription period a new Invoice Line will be attached to an existing POLine. But while unlikely, it is possible, that a given item is attached to multiple PO Lines hence all POLines (with all attached Invoice Lines) should be considered for calculating items cost across all subscription periods.

• Invoice Lines: the most common approach is to create a new Invoice Line for a new subscription period and attach it to an existing PO Line. This new Invoice Line will indicate the subscription period directly with the "Subscription from" and "Subscription to" fields. If these fields are missing the Fiscal Year attached to the Invoice Line should be assumed as the subscription period, even though quite often this may be wrong: e.g normally subscription for a calendar year 2021 are charged in FY which runs from Aug 2020 to June 2021.