LP1672775 Action/Trigger purge release notes

Signed-off-by: Bill Erickson <berickxx@gmail.com>

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..c42a285
--- /dev/null
+++ b/docs/RELEASE_NOTES_NEXT/Administration/purge-at-events.adoc
@@ -0,0 +1,48 @@
+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 intervalue 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 many minutes to run the
+first time, becuase it removes orphaned template outputs, regardless
+of retention interval settings.  The script should be run by hand the
+first time or any time a retention interval change might result in large
+numbers of rows being deleted.
+
+[source,sql]
+---------------------------------------------------------------
+SELECT action_trigger.purge_events();
+---------------------------------------------------------------
+