docs/admin/actiontriggers.adoc

   1 Notifications / Action Triggers
   2 -------------------------------
   3
   4 Introduction
   5 ~~~~~~~~~~~~
   6
   7 indexterm:[action triggers, event definitions, notifications]
   8
   9 Action Triggers give administrators the ability to set up actions for
  10 specific events. They are useful for notification events such as hold notifications.
  11
  12 To access the Action Triggers module, select *Administration* -> *Local Administration* ->  *Notifications / Action triggers*.
  13
  14 [NOTE]
  15 ==========
  16 You must have Local Administrator permissions to access the Action Triggers module.
  17 ==========
  18
  19 You will notice four tabs on this page: <<event_definitions, Event Definitions>>, <<hooks, Hooks>>, <<reactors, Reactors>> and <<validators, Validators>>.
  20
  21
  22 anchor:event_definitions[]
  23
  24 Event Definitions
  25 ~~~~~~~~~~~~~~~~~
  26
  27 Event Definitions is the main tab and contains the key fields when working with action triggers. These fields include:
  28
  29 Table 1: Action Trigger Event Definitions
  30 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  31 |==============================================
  32 |*Field*                         |*Description*
  33 | Owning Library                 |The shortname of the library for which the action / trigger / hook is defined.
  34 | 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.
  35 | <<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''.
  36 | Enabled                        |Sets the given trigger as enabled or disabled. This must be set to enabled for the Action trigger to run.
  37 | Processing Delay               |Defines how long after a given trigger / hook event has occurred before the associated action (``Reactor'') will be taken.
  38 | 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_.
  39 | Processing Group Context Field |Used to batch actions based on its associated group.
  40 | <<reactors, Reactor>>          |Links the action trigger to the Reactor.
  41 | <<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_.
  42 | Event Repeatability Delay      |Allows events to be repeated after this delay interval.
  43 | 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.
  44 | 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.
  45 | 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.
  46 | 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.
  47 | 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.
  48 | Success Cleanup                |After an event is reacted to successfully a cleanup module can be run to clean up after the event.
  49 | 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.
  50 |===============================================
  51
  52
  53 Creating Action Triggers
  54 ~~~~~~~~~~~~~~~~~~~~~~~~
  55 . From the top menu, select *Administration* -> *Local Administration* ->  *Notifications / Action triggers*.
  56 . Click on the _New_ button.
  57 . Select an _Owning Library_.
  58 . Create a unique _Name_ for your new action trigger.
  59 . Select the _Hook_.
  60 . Check the _Enabled_ check box.
  61 . 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_.
  62 . Set the _Processing Delay Context Field_ and _Processing Group Context Field_.
  63 . Select the _Reactor_, _Validator_, _Failure Cleanup_.
  64 . Select the _Granularity_.
  65
  66 . Set the _Max Event Validity Delay_.
  67
  68 . Select the _Opt-In Setting Type_.
  69
  70 . Set the _Opt-In User Field_.
  71
  72 . Select the _Success Cleanup_.
  73
  74 . 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:
  75
  76
  77   [%- USE date -%]
  78   [%- user = target.0.usr -%]
  79   To: [%- params.recipient_email || user.email %]
  80   From: [%- helpers.get_org_setting(target.home_ou.id, 'org.bounced_emails') || lib.email || params.sender_email || default_sender %]
  81   Subject: Overdue Items Marked Lost
  82   Auto-Submitted: auto-generated
  83
  84   Dear [% user.family_name %], [% user.first_given_name %]
  85   The following items are 90 days overdue and have been marked LOST.
  86   [%- params.recipient_email || user.email %][%- params.sender_email || default_sender %]
  87   [% FOR circ IN target %]
  88     Title: [% circ.target_copy.call_number.record.simple_record.title %]
  89     Barcode: [% circ.target_copy.barcode %]
  90     Due: [% date.format(helpers.format_date(circ.due_date), '%Y-%m-%d') %]
  91     Item Cost: [% helpers.get_copy_price(circ.target_copy) %]
  92     Total Owed For Transaction: [% circ.billable_transaction.summary.total_owed %]
  93     Library: [% circ.circ_lib.name %]
  94   [% END %]
  95
  96   [% FOR circ IN target %]
  97     Title: [% circ.target_copy.call_number.record.simple_record.title %]
  98     Barcode: [% circ.target_copy.barcode %]
  99     Due: [% date.format(helpers.format_date(circ.due_date), '%Y-%m-%d') %]
 100     Item Cost: [% helpers.get_copy_price(circ.target_copy) %]
 101     Total Owed For Transaction: [% circ.billable_transaction.summary.total_owed %]
 102     Library: [% circ.circ_lib.name %]
 103   [% END %]
 104
 105 . Once you are satisfied with your new event trigger, click the _Save_ button located at the bottom of the form.
 106
 107 [TIP]
 108 =========
 109 A quick and easy way to create new action triggers is to clone an existing action trigger.
 110 =========
 111
 112 Cloning Existing Action Triggers
 113 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 114
 115 . Check the check box next to the action trigger you wish to clone.
 116 . Click _Clone Selected_ on the top left of the page.
 117 . 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.
 118 . Click _Save_.
 119
 120 Editing Action Triggers
 121 ^^^^^^^^^^^^^^^^^^^^^^^
 122
 123 . Double-click on the action trigger you wish to edit.
 124 . 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.
 125
 126 [NOTE]
 127 ============
 128 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.
 129 ============
 130
 131 Deleting Action Triggers
 132 ^^^^^^^^^^^^^^^^^^^^^^^^
 133
 134 . Check the check box next to the action trigger you wish to delete
 135 . Click _Delete Selected_ on the top-right of the page.
 136
 137
 138 anchor:hooks[]
 139
 140 Hooks
 141 ^^^^^
 142 Hooks define the Fieldmapper class in the core_type column off of which the rest of the field definitions ``hang''.
 143
 144 Table 2. Hooks
 145 ++++++++++++++
 146 |=======================
 147 | *Field*        | *Description*
 148 | Hook Key       | A unique name given to the hook.
 149 | Core Type      | Used to link the action trigger to the IDL class in fm_IDL.xml
 150 | Description    | Text to describe the purpose of the hook.
 151 | Passive        | Indicates whether or not an event is created by direct user action or is circumstantial.
 152 |=======================
 153
 154 You may also create, edit and delete Hooks but the Core Type must refer to an IDL class in the fm_IDL.xml file.
 155
 156
 157 anchor:reactors[]
 158
 159 Reactors
 160 ^^^^^^^^
 161
 162 Reactors link the trigger definition to the action to be carried out.
 163
 164 Table 3. Action Trigger Reactors
 165 ++++++++++++++++++++++++++++++++
 166
 167 |=======================
 168 | Field        | Description
 169 | 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`.
 170 | Description  | Description of the Action to be carried out.
 171 |=======================
 172
 173 You may also create, edit and delete Reactors. Just remember that there must be an associated subroutine or module in the Reactor Perl module.
 174
 175
 176 anchor:validators[]
 177
 178 Validators
 179 ^^^^^^^^^^
 180
 181 Validators set the validation test to be preformed to determine whether the action trigger is executed.
 182
 183 Table 4. Action Trigger Validators
 184 ++++++++++++++++++++++++++++++++++
 185
 186 |=======================
 187 | Field         | Description
 188 | Module Name   | The name of the subroutine in `/openils/lib/perl5/OpenILS/Application/Trigger/Reactor.pm` to validate the action trigger.
 189 | Description   | Description of validation test to run.
 190 |=======================
 191
 192 You may also create, edit and delete Validators. Just remember that their must be an associated subroutine in the Reactor.pm Perl module.
 193