LP#1672775 Action/Trigger retention interval release notes

Signed-off-by: Bill Erickson <berickxx@gmail.com>
Signed-off-by: Galen Charlton <gmc@equinoxinitiative.org>

diff --git a/docs/RELEASE_NOTES_NEXT/Administration/purge-at-events.adoc b/docs/RELEASE_NOTES_NEXT/Administration/purge-at-events.adoc
new file mode 100644 (file)
index 0000000..87e5fbe
--- /dev/null
+++ b/docs/RELEASE_NOTES_NEXT/Administration/purge-at-events.adoc
@@ -0,0 +1,63 @@
+Action/Trigger Events Data Purging
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Action/Trigger event definitions have a new field called "Retention 
+Interval".  When an optional interval value is applied, events and
+template output data linked to the event definition will be deleted
+from the database once they reach the specified age.
+
+Retention Interval Restrictions for Passive Hooks
++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Restrictions are placed on retention interval values for event definitions
+using passive hooks to prevent data from being deleted while it's still
+needed by the system.
+
+The presence of event data is how the system knows not to send duplicate
+events.  As long as a scenario exists where a duplicate event may be
+generated, the events must be retained.
+
+To apply a retention interval value to a passive-hook event definition:
+
+ * The event definition must have a max_delay value.
+ * The retention interval must be larger than the difference between
+   the delay and max_delay values.
+
+For example, if the delay is 7 days and max_delay is 10 days, the retention
+interval must be greater than 3 days to ensure no duplicate events are 
+created between the first event on day 7 and the end of the event validity
+window on day 10.
+
+Deployment
+++++++++++
+
+A new purge_at_events.sh script is installed in the bin directory
+(typically /openils/bin) wich should be added to CRON for regular
+maintanence.
+
+NOTE: On large data sets, this script can take a long time to run and
+create higher than normal I/O load as it churns though the event and
+event_output tables.  You may wish to run the script by hand the first
+time so it can be monitored.  It can be run in psql like so:
+
+[source,sql]
+---------------------------------------------------------------
+SELECT action_trigger.purge_events();
+---------------------------------------------------------------
+
+NOTE: On *very* large data sets (10s to 100s of millions of event and
+event_output rows), it may be advisable to first to repopulate the event
+and event_output tables with only the desired data before starting
+regular purges.  This can be done, for example, using the copy to temp
+table, truncate source table, repopulate source table from temp table
+approach.  This will be much faster than the purge_events() function
+in cases where most of the data will be purged.
+
+Hook Data Cleanup
++++++++++++++++++
+
+A number of action_trigger.hook entries which have always been treated
+as active hooks, though are configured as passive hooks, have been 
+updated to properly reflect the non-passive-ness.  This allows for 
+simpler configuration of their retention interval values.
+