[OPEN-ILS-DEV] ***SPAM*** Understanding the action / trigger / hook / reactor / validator architecture

[Dan Scott]

I have been trying to get the action / trigger mechanisms working for
basic notification purposes. The short term goal is to support
notification at different intervals for different libraries in the
consortium. The longer term goal is to generate notices using different
templates depending on the language preference of our users (as stored
in a patron statistical category.

I'm going to describe how I _think_ things work, and then hopefully
people can correct me, because I have been able to get exactly nowhere
in 1.6.0.3. Perhaps this can serve as proto-documentation; the
architecture seems extremely powerful, but it also seems to be extremely
complex - and without documentation, I suspect very few people are
actually capable of taking advantage of it.

>From Admin -> Local Administration -> Notifications / Action triggers,
you get an interface with the following fields (assuming that you are
either logged in as the admin / open-ils account or have been granted
the appropriate permissions - as of 1.6.0.4, granted to all Local System
Administrators):

  * Owning library
  * Name
  * Hook
  * Active
  * Processing Delay
  * Processing Delay Context Field
  * Processing Group Context Field
  * Validator
  * Reactor
  * Max Event Validity Delay

"Owning Library" seems straightforward - it's the shortname of the
library for which the action / trigger / hook is defined. (You can see
that the first problem that I'm having is what exactly to call these
things... I guess, given the name of the dialogue, that these are
"Trigger events"). It's not clear, though, if this field operates
similar to library settings where the more specific library overrides
parent settings.

"Name" is the name of the trigger event, that links to a trigger event
environment containing a set of fields (objects?) that will be returned
to the Validator / Reactor for processing.

"Hook" is the name of the trigger for the trigger event (?). These
appear in /openils/conf/action_trigger_filters.json, and also in (?).
The underlying action_trigger.hook table defines the Fieldmapper class
in the core_type column that is what the rest of the field definitions,
etc, hang off of.

"Active" describes whether the given trigger event is a passive event or
an active event (_not_ whether the event has been enable or not). A
passive event must be triggered by the running of the
action_trigger_runner.pl script with an explicit call to process that
hook (--process-hooks argument); these events get created and placed in
pending mode, and then are fired once the action_trigger_runner.pl
script is called with the --run-pending argument.

"Processing delay" defines how long after a given trigger / hook event
has occurred before the associated action ("Reactor") will be taken.

"Processing delay context field" defines the field associated with the
event on which the processing delay is calculated. For example, the
processing delay context field on the hold.capture hook (which has a
core_type of ahr) is capture_time

"Processing group context field" defines the field associated with the
event that is used somewhere (?)

"Validator" is a Perl subroutine defined
in /openils/lib/perl5/OpenILS/Application/Trigger/Validator.pm. The
subroutines receive the trigger environment as an argument (see the
linked "Name" for the environment definition) and returns either 1 if
the validator is true or 0 if the validator returns false.

"Reactor" is a Perl subroutine defined either as a subroutine
in /openils/lib/perl5/OpenILS/Application/Trigger/Reactor.pm or via the
module name
in /openils/lib/perl5/OpenILS/Application/Trigger/Reactor/*.pm - this
will only be run if the Validator returned a 1

"Max Event Validity Delay" seems to define the threshold for how far
back the action_trigger_runner.pl script should reach to generate a
batch of events.

Given all of this, I was attempting to set up holds email notification
via the action / trigger events mechanism rather than the old-school
method as a first test. My first problem was in figuring out how to add
a definition for a new hook
to /openils/conf/action_trigger_filters.json; atz eventually suggested
to just add:

"hold.available": {},

(http://evergreen-ils.org/irc_logs/evergreen/2010-03/%
23evergreen.05-Fri-2010.log). The {} is a JSON object expressing a set
of conditions which filter the actions based on the core_type (I think)
associated with the hook, so {} should just run them over everything
matched by the core type. In theory. I then set up the 1.6.0.3 test
system so that a hold would be captured and ran the
action_trigger_runner.pl script with a bunch of different arguments in
hopes of stumbling across the right sequence of events - basically the
following calls:

/openils/bin/action_trigger_runner.pl --process-hooks

/openils/bin/action_trigger_runner.pl --run-pending

Ultimately, however, I was unable to generate any holds notices.
Similarly, by manipulating the due date of various checked out items, I
was unable to generate any actions as the result of the 7 days overdue
or 90 days overdue default events.

Questions:
  * If there are two Owning Libraries for a given Hook - say, CONS and
BR1 - does the deeper library in the hierarchy override the definition
for the hook, or does the action get triggered for both libraries in the
hierarchy for what is essentially the same event?
  * Given the "delay time" column in the action/trigger configuration,
can the action/trigger mechanism support pre-overdue notices (e.g. a
negative delay)?
  * Would it be possible to deliver an annotated
action_trigger_filters.json.example file with some of the more common
hooks enabled by default (for example, hold.available)?
  * What am I doing wrong?