User Tools

Site Tools


evergreen-user:action_trigger

This is an old revision of the document!


Action/Trigger (Notifications)

Author: Bill Erickson
Created on: Dec. 7, 2009

Important Concepts & Terminology

IDL

See the description in Dan Scott's Evergreen Workshop

Hook

A reference to an action within the ILS. This is how we indicate what types of behaviour we want to react to. Examples include "hold.available" (item became ready for pickup from the holds shelf) and "checkout.due" (circulating item is due).

  • Hooks have a core object type which defines the primary context object for the action. The core type is represented by the IDL class name. For example, the core type for "checkout.due" is "circ", the core type for "hold.available" is "ahr".
  • Hooks can be active or passive. An active hook is one whose event creation occurs in real time. An example of an active hook is "hold.available". It is considered "active", because an action occurs within the ILS from which to fire off the event creation. In other words, a copy was physically scanned in and put on the shelf. Events for passive hooks are created in batch via regularly scheduled (CRON) processes. An example of a passive hook would be "checkout.due". There is no action within the ILS that occurs the moment an item becomes due. It's simply the result of passing time.
Validator

Module that validates context data prior to reaction. This is critical for supporting delayed reactions. Common examples include "HoldIsAvailable", "CircIsOverdue", and "CircIsOpen".

For developers: The system looks for validator modules in the OpenILS::Application::Trigger::Validator namespace. If they are not found, it searches the Perl library path

Reactor

Module that defines how the system should respond to actions that match configured hooks. The most common example is "SendEmail".

For developers: The system looks for reactor modules in the OpenILS::Application::Trigger::Reactor namespace. If they are not found, it searches the Perl library path.

Cleanup

Module that performs post-reaction cleanup operations. The system support success cleanups and failure cleanup modules. This type of module is useful for cleaning up temporary files, etc.

Event Definitions

The Event Definition is the heart of the action/trigger configuration. It ties together a hook, validator, reactor, cleanup(er), template, and other settings to define a single reaction context. If you said, "I want to set up 7-day overdue email notices", you'd be talking about configuring an event definition.

Under normal circumstances, the hooks, validators, reactors, and cleanup modules will already be in place. All an administrator needs to do is set up the event definition to pull those pieces together. Below is a discussion of the event definition fields and how they are used.

Event Definition Fields

Owning Library

The context library for the event definition. This can be any organization unit in the hierarchy. This value is important because it defines the scope of the event definition. If the Owning Library has descendant org units (e.g. a consortium or a system), actions that occur at all descendant org units are relevant to the event definition. If the owning library is a single branch, then only actions at that branch are relevant. This gives admins the flexibility to define, for example, a single 7-day overdue notice for an entire consortium, or one per system, branch, etc.

Name

Human-friendly name for an event definition. This can be anything as long as it is unique to the owning library. A good rule of thumb for naming an event definition is to summarize the hook, reactor, and delay. For example, "7-Day Courtesy Email Notice".

Hook

A reference to the hook (described above)

Active

Event definitions can be turned off by setting the active flag to false.

Processing Delay

This value defines the amount of time the system should wait after a target object becomes "relevant" before reacting on that target object. Some examples will help here:

  • Overdue notices use the "checkout.due" hook. An item is technically due the second the due date hits. It is at that point the circulation becomes relevant in the context of the checkout.due hook. The goal for this type of notice, though, is to react 7 days after the item becomes relevant, i.e. 7 days past due (aka overdue). Note, for interval fields, you can use English text like "7 days", "3 months", etc.
  • Courtesy notices also use the "checkout.due" hook. In this context, though, we take advantage of looking into the future, which is something that can only be done when using passive hooks. Remember, passive hook event creation occurs as the result of batch processes and not from something happening within the ILS. The fact that, technically, the item won't yet be relevant in the context of the checkout.due hook is OK. In fact, the item may never relevant, because it may be checked in before it becomes due. We don't care. (Nerd aside: It's the Schrodinger's cat of event definitions. It may become relevant, but we'll never know, because we're not going to look.) All we care about is when it theoretically would become relevant. In this case, you would use a negative delay to signify the notification should be delivered exactly X days before the target becomes relevant in the context of the hook. In the delay field, you would enter a value like "-3 days".
  • Hold available notification using the hold.available hook. The hold is available (thus, relevant) the moment it is scanned in at the pickup library. You may want to delay the notice by an hour to make sure the copy is in good condition, etc.
Processing Delay Context Field

This is the field on the target object that defines the time stamp to use as the base time for determining if the target object falls within the configured processing delay.

Processing Group Context Field
Validator
Reactor
Failure Cleanup
Success Cleanup
Granularity
Max Event Validity Delay
Opt-In Setting Type
Opt-In User Field
Template
evergreen-user/action_trigger.1260223897.txt.gz · Last modified: 2022/02/10 13:33 (external edit)

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki

© 2008-2022 GPLS and others. Evergreen is open source software, freely licensed under GNU GPLv2 or later.
The Evergreen Project is a U.S. 501(c)3 non-profit organization.