docs/admin/actiontriggers.adoc

   1 Notifications / Action Triggers
   2 -------------------------------
   3
   4 indexterm:[action triggers, event definitions, notifications]
   5
   6 Action Triggers give administrators the ability to set up actions for
   7 specific events. They are useful for notification events such as hold notifications.
   8
   9 To access the Action Triggers module, select *Admin* -> *Local Administration* -> *Notifications / Action triggers*.
  10
  11 [NOTE]
  12 ==========
  13 You must have Local Administrator permissions to access the Action Triggers module.
  14 ==========
  15
  16 You will notice four tabs on this page: <<event_definitions, Event Definitions>>, <<hooks, Hooks>>, <<reactors, Reactors>> and <<validators, Validators>>.
  17
  18
  19 anchor:event_definitions[]
  20
  21 Event Definitions
  22 ~~~~~~~~~~~~~~~~~
  23
  24 Event Definitions is the main tab and contains the key fields when working with action triggers. These fields include:
  25
  26 Table 1: Action Trigger Event Definitions
  27 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  28 |==============================================
  29 |*Field*                         |*Description*
  30 | Owning Library                 |The shortname of the library for which the action / trigger / hook is defined.
  31 | 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.
  32 | <<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''.
  33 | Enabled                        |Sets the given trigger as enabled or disabled. This must be set to enabled for the Action trigger to run.
  34 | Processing Delay               |Defines how long after a given trigger / hook event has occurred before the associated action (``Reactor'') will be taken.
  35 | 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_.
  36 | Processing Group Context Field |Used to batch actions based on its associated group.
  37 | <<reactors, Reactor>>          |Links the action trigger to the Reactor.
  38 | <<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_.
  39 | Event Repeatability Delay      |Allows events to be repeated after this delay interval.
  40 | 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.
  41 | 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.
  42 | 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.
  43 | 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.
  44 | 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.
  45 | Success Cleanup                |After an event is reacted to successfully a cleanup module can be run to clean up after the event.
  46 | 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.
  47 |===============================================
  48
  49
  50 Creating Action Triggers
  51 ~~~~~~~~~~~~~~~~~~~~~~~~
  52 . From the top menu, select *Admin* -> *Local Administration* -> *Notifications / Action triggers*.
  53 . Click on the _New_ button.
  54 . Select an _Owning Library_.
  55 . Create a unique _Name_ for your new action trigger.
  56 . Select the _Hook_.
  57 . Check the _Enabled_ check box.
  58 . 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_.
  59 . Set the _Processing Delay Context Field_ and _Processing Group Context Field_.
  60 . Select the _Reactor_, _Validator_, _Failure Cleanup_.
  61 . Select the _Granularity_.
  62
  63 . Set the _Max Event Validity Delay_.
  64
  65 . Select the _Opt-In Setting Type_.
  66
  67 . Set the _Opt-In User Field_.
  68
  69 . Select the _Success Cleanup_.
  70
  71 . 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:
  72
  73
  74   [%- USE date -%]
  75   [%- user = target.0.usr -%]
  76   To: [%- params.recipient_email || user.email %]
  77   From: [%- helpers.get_org_setting(target.home_ou.id, 'org.bounced_emails') || lib.email || params.sender_email || default_sender %]
  78   Subject: Overdue Items Marked Lost
  79   Auto-Submitted: auto-generated
  80
  81   Dear [% user.family_name %], [% user.first_given_name %]
  82   The following items are 90 days overdue and have been marked LOST.
  83   [%- params.recipient_email || user.email %][%- params.sender_email || default_sender %]
  84   [% FOR circ IN target %]
  85     Title: [% circ.target_copy.call_number.record.simple_record.title %]
  86     Barcode: [% circ.target_copy.barcode %]
  87     Due: [% date.format(helpers.format_date(circ.due_date), '%Y-%m-%d') %]
  88     Item Cost: [% helpers.get_copy_price(circ.target_copy) %]
  89     Total Owed For Transaction: [% circ.billable_transaction.summary.total_owed %]
  90     Library: [% circ.circ_lib.name %]
  91   [% END %]
  92
  93   [% FOR circ IN target %]
  94     Title: [% circ.target_copy.call_number.record.simple_record.title %]
  95     Barcode: [% circ.target_copy.barcode %]
  96     Due: [% date.format(helpers.format_date(circ.due_date), '%Y-%m-%d') %]
  97     Item Cost: [% helpers.get_copy_price(circ.target_copy) %]
  98     Total Owed For Transaction: [% circ.billable_transaction.summary.total_owed %]
  99     Library: [% circ.circ_lib.name %]
 100   [% END %]
 101
 102 . Once you are satisfied with your new event trigger, click the _Save_ button located at the bottom of the form.
 103
 104 [TIP]
 105 =========
 106 A quick and easy way to create new action triggers is to clone an existing action trigger.
 107 =========
 108
 109 Cloning Existing Action Triggers
 110 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 111
 112 . Check the check box next to the action trigger you wish to clone.
 113 . Click _Clone Selected_ on the top left of the page.
 114 . 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.
 115 . Click _Save_.
 116
 117 Editing Action Triggers
 118 ^^^^^^^^^^^^^^^^^^^^^^^
 119
 120 . Double-click on the action trigger you wish to edit.
 121 . 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.
 122
 123 [NOTE]
 124 ============
 125 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.
 126 ============
 127
 128 Deleting Action Triggers
 129 ^^^^^^^^^^^^^^^^^^^^^^^^
 130
 131 . Check the check box next to the action trigger you wish to delete
 132 . Click _Delete Selected_ on the top-right of the page.
 133
 134
 135 anchor:hooks[]
 136
 137 Hooks
 138 ^^^^^
 139 Hooks define the Fieldmapper class in the core_type column off of which the rest of the field definitions ``hang''.
 140
 141 Table 2. Hooks
 142 ++++++++++++++
 143 |=======================
 144 | *Field*        | *Description*
 145 | Hook Key       | A unique name given to the hook.
 146 | Core Type      | Used to link the action trigger to the IDL class in fm_IDL.xml
 147 | Description    | Text to describe the purpose of the hook.
 148 | Passive        | Indicates whether or not an event is created by direct user action or is circumstantial.
 149 |=======================
 150
 151 You may also create, edit and delete Hooks but the Core Type must refer to an IDL class in the fm_IDL.xml file.
 152
 153
 154 anchor:reactors[]
 155
 156 Reactors
 157 ^^^^^^^^
 158
 159 Reactors link the trigger definition to the action to be carried out.
 160
 161 Table 3. Action Trigger Reactors
 162 ++++++++++++++++++++++++++++++++
 163
 164 |=======================
 165 | Field        | Description
 166 | 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`.
 167 | Description  | Description of the Action to be carried out.
 168 |=======================
 169
 170 You may also create, edit and delete Reactors. Just remember that there must be an associated subroutine or module in the Reactor Perl module.
 171
 172
 173 anchor:validators[]
 174
 175 Validators
 176 ^^^^^^^^^^
 177
 178 Validators set the validation test to be preformed to determine whether the action trigger is executed.
 179
 180 Table 4. Action Trigger Validators
 181 ++++++++++++++++++++++++++++++++++
 182
 183 |=======================
 184 | Field         | Description
 185 | Module Name   | The name of the subroutine in `/openils/lib/perl5/OpenILS/Application/Trigger/Reactor.pm` to validate the action trigger.
 186 | Description   | Description of validation test to run.
 187 |=======================
 188
 189 You may also create, edit and delete Validators. Just remember that their must be an associated subroutine in the Reactor.pm Perl module.
 190
 191 Processing Action Triggers
 192 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 193
 194 To run the 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:
 195
 196 ----
 197 /openils/bin/action_trigger_runner.pl --process-hooks --run-pending
 198 ----
 199
 200 You have several options when running the script:
 201
 202 * --run-pending: Run pending events to send emails or take other actions as
 203 specified by the reactor in the event definition.
 204
 205 * --process-hooks: Create hook events
 206
 207 * --osrf-config=[config_file]: OpenSRF core config file. Defaults to:
 208 /openils/conf/opensrf_core.xml
 209
 210 * --custom-filters=[filter_file]: File containing a JSON Object which describes any hooks
 211 that should use a user-defined filter to find their target objects. Defaults to:
 212 /openils/conf/action_trigger_filters.json
 213
 214 * --max-sleep=[seconds]: When in process-hooks mode, wait up to [seconds] for the lock file to go
 215 away. Defaults to 3600 (1 hour).
 216
 217 * --hooks=hook1[,hook2,hook3,...]: Define which hooks to create events for. If none are defined, it
 218 defaults to the list of hooks defined in the --custom-filters option.
 219 Requires --process-hooks.
 220
 221 * --granularity=[label]: Limit creating events and running pending events to
 222 those only with [label] granularity setting.
 223
 224 * --debug-stdout: Print server responses to STDOUT (as JSON) for debugging.
 225
 226 * --lock-file=[file_name]: Sets the lock file for the process.
 227
 228 * --verbose: Show details of script processing.
 229
 230 * --help: Show help information.
 231
 232 Examples:
 233
 234 * Run all pending events that have no granularity set. This is what you tell
 235 CRON to run at regular intervals.
 236 +
 237 ----
 238 perl action_trigger_runner.pl --run-pending
 239 ----
 240
 241 * Batch create all "checkout.due" events
 242 +
 243 ----
 244 perl action_trigger_runner.pl --hooks=checkout.due --process-hooks
 245 ----
 246
 247 * Batch create all events for a specific granularity and to send notices for all
 248 pending events with that same granularity.
 249 +
 250 ----
 251 perl action_trigger_runner.pl --run-pending --granularity=Hourly --process-hooks
 252 ----