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

[Dan Scott]

Some further corrections and answers, based on IRC assistance from Mike
Rylander, Bill Erickson, and Benjamin Shum today:

On Tue, 2010-03-23 at 16:10 -0400, Dan Scott wrote:

> "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.

Wrong-o! Bill corrected me in that "Active" actually means whether the
given hook has been enabled or not - not active vs. passive. I've
changed the description of this in the user interface to "Enabled" for
any future release of Evergreen. This also explains why none of the
events would fire: the only event definition that is enabled out of the
box has to do with acquisitions.

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

This is the field that is used to group / batch events together - for
example, if you are want to send a single email per user that lists
multiple overdue items, you would group by the "usr" field. Which is
exactly what the event definitions and templates do out of the box.

> 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.

Once I changed the event definitions' "Active" (soon to be "Enabled") to
"True" instead of "False", running the script with these options did
what I expected - at least for overdue notices. I haven't been able to
dig into holds, etc but I'm confident that they will work now.

> 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?

Bill answered this - the answer is no. However, you can clone the base
definition, leave that disabled, and enable the clone(s) at the system
or branch levels with their respective values. Note that if you have one
branch that wants a different event definition parameter - say,
processing delay - you will need to create event definitions for all
branches within the same system, even if the other 99 branches under the
same system have identical parameters.

>   * Given the "delay time" column in the action/trigger configuration,
> can the action/trigger mechanism support pre-overdue notices (e.g. a
> negative delay)?

Benjamin confirmed that negative delays do in fact work; they're running
pre-due notices using the action / trigger infrastructure in their
system today.

>   * 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)?

Yep. There was a discussion elsewhere in the thread about whether
various JSON parsers choke on comments, which is somewhat of a secondary
concern to me; having an action_trigger_filters.json.annotated_example
with the first comment being "/* DELETE ALL COMMENTS TO MAKE THIS WORK
*/" would be fine, or action_trigger_filters.json.README, or the like,
would equally suit the purpose of illustrating what's happening and why.

The more pressing matter to my mind is working out what things should
work out of the box; one of my goals has been trying to make the base
setup "just work" with respect to permissions for various levels of
staff, but a corollary is making integral pieces of functionality like
notifications work with a minimum of effort. We might not want a system
set up to start sending email notifications without the administrator
doing anything (that way lies madness, particularly for a test server),
but having all of the default hooks getting processed out of the box and
requiring the administrator to (minimally) 1. enable the corresponding
event definitions in the Admin -> Local Administration -> Actions /
Notifications interface and 2. schedule the action_trigger_runner.pl
cron job seems reasonable.

>   * What am I doing wrong?

Oh, undoubtedly all sorts of things, but I have a better idea of what
I've been doing wrong in the action/trigger space :)

Also, note to self: one needs to modify either the templates or the
event parameters (sender_email) to ensure that the correct library email
address gets inserted into the From: header of the outgoing email.