docs: Angular Acq Sprint 0 Tools and Infrastructure

[Evergreen.git] / docs / modules / admin / pages / actiontriggers.adoc

= Notifications / Action Triggers =
:toc:


== Introduction ==

indexterm:[action triggers, event definitions, notifications]

Action Triggers give administrators the ability to set up actions for
specific events. They are useful for notification events such as hold notifications.

To access the Action Triggers module, select *Administration* -> *Local Administration* ->  *Notifications / Action triggers*.

[NOTE]
==========
You must have Local Administrator permissions to access the Action Triggers module.
==========

You will notice four tabs on this page: <<event_definitions, Event Definitions>>, <<hooks, Hooks>>, <<reactors, Reactors>> and <<validators, Validators>>.


[#event_definitions]

== Event Definitions ==

Event Definitions is the main tab and contains the key fields when working with action triggers. These fields include:

=== Table 1: Action Trigger Event Definitions ===


|==============================================
|*Field*                         |*Description*
| Owning Library                 |The shortname of the library for which the action / trigger / hook is defined.
| Name                           |The name of the trigger event, that links to a trigger event environment containing a set of fields that will be returned to the <<validators, Validators>> and/or <<reactors, Reactors>> for processing.
| <<hooks, Hook>>                |The name of the trigger for the trigger event. The underlying action_trigger.hook table defines the Fieldmapper class in the core_type column off of which the rest of the field definitions ``hang''.
| Enabled                        |Sets the given trigger as enabled or disabled. This must be set to enabled for the Action trigger to run.
| 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 |Used to batch actions based on its associated group.
| <<reactors, Reactor>>          |Links the action trigger to the Reactor.
| <<validators, Validator>>      |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_.
| Event Repeatability Delay      |Allows events to be repeated after this delay interval.
| Failure Cleanup                |After an event is reacted to and if there is a failure a cleanup module can be run to clean up after the event.
| Granularity                    |Used to group events by how often they should be run. Options are Hourly, Daily, Weekly, Monthly, Yearly, but you may also create new values.
| Max Event Validity Delay       |Allows events to have a range of time that they are valid.  This value works with the *Processing Delay* to define a time range.
| Message Library Path           |Defines the org_unit object for a Patron Message Center message.
| Message Template               |A Template Toolkit template that can be used to generate output for a Patron Message Center message.  The output may or may not be used by the reactor or another external process.
| Message Title                  |The title that will display on a Patron Message Center message.
| Message User Path              |Defines the user object for a Patron Message Center message.
| Opt-In Settings Type           |Choose which User Setting Type will decide if this event will be valid for a certain user.  Use this to allow users to Opt-In or Opt-Out of certain events.
| Opt-In User Field              |Set to the name of the field in the selected hook's core type that will link the core type to the actor.usr table. 
| Success Cleanup                |After an event is reacted to successfully a cleanup module can be run to clean up after the event.
| Template                       |A Template Toolkit template that can be used to generate output.  The output may or may not be used by the reactor or another external process.
|==============================================


== Creating Action Triggers ==

. From the top menu, select *Administration* -> *Local Administration* ->  *Notifications / Action triggers*.
. Click on the _New_ button.
+
image::media/new_event_def.png[New Event Definition]
+
. Select an _Owning Library_.
. Create a unique _Name_ for your new action trigger.
. Select the _Hook_.
. Check the _Enabled_ check box.
. Set the _Processing Delay_ in the appropriate format. E.g. _7 days_ to run 7 days from the trigger event or _00:01:00_ to run 1 hour after the _Processing Delay Context Field_.
. Set the _Processing Delay Context Field_ and _Processing Group Context Field_.
. Select the _Reactor_ and _Validator_.
. Set the _Event Repeatability Delay_.
. Select the _Failure Cleanup_ and _Granularity_.
. Set the _Max Event Validity Delay_.
+
image::media/event_def_details.png[Event Definition Details]
+
. If you wish to send a User Message through the Message Center, set a _Message Library Path_.  Enter text in the _Message Template_.  Enter a title for this message in _Message Title_, and set a value in _Message User Path_.
. Select the _Opt-In Setting Type_.
. Set the _Opt-In User Field_.
. Select the _Success Cleanup_.
+
image::media/event_def_details_2.png[Event Definition Details]
+
. Enter text in the _Template_ text box if required. These are for email messages. Here is a sample template for sending 90 day overdue notices:


  [%- USE date -%]
  [%- user = target.0.usr -%]
  To: [%- params.recipient_email || user.email %]
  From: [%- helpers.get_org_setting(target.home_ou.id, 'org.bounced_emails') || lib.email || params.sender_email || default_sender %]
  Subject: Overdue Items Marked Lost
  Auto-Submitted: auto-generated

  Dear [% user.family_name %], [% user.first_given_name %]
  The following items are 90 days overdue and have been marked LOST.
  [%- params.recipient_email || user.email %][%- params.sender_email || default_sender %]
  [% FOR circ IN target %]
    Title: [% circ.target_copy.call_number.record.simple_record.title %]
    Barcode: [% circ.target_copy.barcode %]
    Due: [% date.format(helpers.format_date(circ.due_date), '%Y-%m-%d') %]
    Item Cost: [% helpers.get_copy_price(circ.target_copy) %]
    Total Owed For Transaction: [% circ.billable_transaction.summary.total_owed %]
    Library: [% circ.circ_lib.name %]
  [% END %]

  [% FOR circ IN target %]
    Title: [% circ.target_copy.call_number.record.simple_record.title %]
    Barcode: [% circ.target_copy.barcode %]
    Due: [% date.format(helpers.format_date(circ.due_date), '%Y-%m-%d') %]
    Item Cost: [% helpers.get_copy_price(circ.target_copy) %]
    Total Owed For Transaction: [% circ.billable_transaction.summary.total_owed %]
    Library: [% circ.circ_lib.name %]
  [% END %]

. Once you are satisfied with your new event trigger, click the _Save_ button located at the bottom of the form.


[TIP]
=========
A quick and easy way to create new action triggers is to clone an existing action trigger.
=========

=== Cloning Existing Action Triggers ===

. Check the check box next to the action trigger you wish to clone.
. Click _Clone Selected_ on the top left of the page.
. An editing window will open. Notice that the fields will be populated with content from the cloned action trigger. Edit as necessary and give the new action trigger a unique Name.
. Click _Save_.

=== Editing Action Triggers ===

. Double-click on the action trigger you wish to edit.
. The edit screen will appear. When you are finished editing, click _Save_ at the bottom of the form. Or click _Cancel_ to exit the screen without saving.

[NOTE]
============
Before deleting an action trigger, you should consider disabling it through the editing form. This way you can keep it for future use or cloning.
============

=== Deleting Action Triggers ===

. Check the check box next to the action trigger you wish to delete
. Click _Delete Selected_ on the top-right of the page.

=== Testing Action Triggers ===

. Go to the list of action triggers.
. Click on the blue link text for the action trigger you'd like to test.
+
image::media/test_event_def.png[Blue Link Text]
+
. Go to the Test tab.
. If there is a test available, fill in the required information.
. View the output of the test.

image::media/test_event_def_output.png[Test Output]

WARNING: If you are testing an email or SMS notification, use a test account and email as an example. Using the Test feature will actually result in the notification being sent if configured correctly.  Similarly, use a test item or barcode when testing a circulation-based event like Mark Lost since the test will mark the item as lost.

[#hooks]

=== Hooks ===

Hooks define the Fieldmapper class in the core_type column off of which the rest of the field definitions ``hang''.


==== Table 2. Hooks ====


|=======================
| *Field*        | *Description*
| Hook Key       | A unique name given to the hook.
| Core Type      | Used to link the action trigger to the IDL class in fm_IDL.xml
| Description    | Text to describe the purpose of the hook.
| Passive        | Indicates whether or not an event is created by direct user action or is circumstantial.
|=======================

You may also create, edit and delete Hooks but the Core Type must refer to an IDL class in the fm_IDL.xml file.


[#reactors]

=== Reactors ===

Reactors link the trigger definition to the action to be carried out.

==== Table 3. Action Trigger Reactors ====


|=======================
| Field        | Description
| Module Name  | The name of the Module to run if the action trigger is validated. It must be defined as a subroutine in `/openils/lib/perl5/OpenILS/Application/Trigger/Reactor.pm` or as a module in `/openils/lib/perl5/OpenILS/Application/Trigger/Reactor/*.pm`.
| Description  | Description of the Action to be carried out.
|=======================

You may also create, edit and delete Reactors. Just remember that there must be an associated subroutine or module in the Reactor Perl module.


[#validators]

=== Validators ===

Validators set the validation test to be preformed to determine whether the action trigger is executed.

==== Table 4. Action Trigger Validators ====


|=======================
| Field         | Description
| Module Name   | The name of the subroutine in `/openils/lib/perl5/OpenILS/Application/Trigger/Reactor.pm` to validate the action trigger.
| Description   | Description of validation test to run.
|=======================

You may also create, edit and delete Validators. Just remember that their must be an associated subroutine in the Reactor.pm Perl module.

[#processing_action_triggers]
== Processing Action Triggers ==

To run action triggers, an Evergreen administrator will need to run the trigger processing script. This should be set up as a cron job to run periodically. To run the script, use this command:

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

You have several options when running the script:

* --run-pending: Run pending events to send emails or take other actions as
specified by the reactor in the event definition.

* --process-hooks: Create hook events

* --osrf-config=[config_file]: OpenSRF core config file. Defaults to:
/openils/conf/opensrf_core.xml

* --custom-filters=[filter_file]: File containing a JSON Object which describes any hooks
that should use a user-defined filter to find their target objects. Defaults to:
/openils/conf/action_trigger_filters.json

* --max-sleep=[seconds]: When in process-hooks mode, wait up to [seconds] for the lock file to go
away. Defaults to 3600 (1 hour).

* --hooks=hook1[,hook2,hook3,...]: Define which hooks to create events for. If none are defined, it
defaults to the list of hooks defined in the --custom-filters option.
Requires --process-hooks.

* --granularity=[label]: Limit creating events and running pending events to
those only with [label] granularity setting.

* --debug-stdout: Print server responses to STDOUT (as JSON) for debugging.

* --lock-file=[file_name]: Sets the lock file for the process.

* --verbose: Show details of script processing.

* --help: Show help information.

Examples:

* Run all pending events that have no granularity set. This is what you tell
CRON to run at regular intervals.
+
----
perl action_trigger_runner.pl --run-pending
----

* Batch create all "checkout.due" events
+
----
perl action_trigger_runner.pl --hooks=checkout.due --process-hooks
----

* Batch create all events for a specific granularity and to send notices for all
pending events with that same granularity.
+
----
perl action_trigger_runner.pl --run-pending --granularity=Hourly --process-hooks
----