1 = Notifications / Action Triggers =
7 indexterm:[action triggers, event definitions, notifications]
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.
12 To access the Action Triggers module, select *Administration* -> *Local Administration* -> *Notifications / Action triggers*.
16 You must have Local Administrator permissions to access the Action Triggers module.
19 You will notice four tabs on this page: <<event_definitions, Event Definitions>>, <<hooks, Hooks>>, <<reactors, Reactors>> and <<validators, Validators>>.
24 == Event Definitions ==
26 Event Definitions is the main tab and contains the key fields when working with action triggers. These fields include:
28 === Table 1: Action Trigger Event Definitions ===
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 and return 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 | Message Library Path |Defines the org_unit object for a Patron Message Center message.
47 | 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.
48 | Message Title |The title that will display on a Patron Message Center message.
49 | Message User Path |Defines the user object for a Patron Message Center message.
50 | 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.
51 | 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.
52 | Success Cleanup |After an event is reacted to successfully a cleanup module can be run to clean up after the event.
53 | 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.
54 |==============================================
57 == Creating Action Triggers ==
59 . From the top menu, select *Administration* -> *Local Administration* -> *Notifications / Action triggers*.
60 . Select the _New Event Definition_ button.
62 image::actiontriggers/new_event_def.png[New Event Definition]
64 . Select an _Owning Library_.
65 . Create a unique _Name_ for your new action trigger.
67 . Check the _Enabled_ check box.
68 . 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_.
69 . Set the _Processing Delay Context Field_ and _Processing Group Context Field_.
70 . Select the _Reactor_ and _Validator_.
71 . Set the _Event Repeatability Delay_.
72 . Select the _Failure Cleanup_ and _Granularity_.
74 image::actiontriggers/event_def_details.png[Event Definition Details]
76 . Set the _Max Event Validity Delay_.
77 . 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_.
78 . Select the _Opt-In Setting Type_.
79 . Set the _Opt-In User Field_.
80 . Select the _Success Cleanup_.
81 . 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:
85 [%- user = target.0.usr -%]
86 To: [%- params.recipient_email || user.email %]
87 From: [%- helpers.get_org_setting(target.home_ou.id, 'org.bounced_emails') || lib.email || params.sender_email || default_sender %]
88 Subject: Overdue Items Marked Lost
89 Auto-Submitted: auto-generated
91 Dear [% user.family_name %], [% user.first_given_name %]
92 The following items are 90 days overdue and have been marked LOST.
93 [%- params.recipient_email || user.email %][%- params.sender_email || default_sender %]
94 [% FOR circ IN target %]
95 Title: [% circ.target_copy.call_number.record.simple_record.title %]
96 Barcode: [% circ.target_copy.barcode %]
97 Due: [% date.format(helpers.format_date(circ.due_date), '%Y-%m-%d') %]
98 Item Cost: [% helpers.get_copy_price(circ.target_copy) %]
99 Total Owed For Transaction: [% circ.billable_transaction.summary.total_owed %]
100 Library: [% circ.circ_lib.name %]
103 [% FOR circ IN target %]
104 Title: [% circ.target_copy.call_number.record.simple_record.title %]
105 Barcode: [% circ.target_copy.barcode %]
106 Due: [% date.format(helpers.format_date(circ.due_date), '%Y-%m-%d') %]
107 Item Cost: [% helpers.get_copy_price(circ.target_copy) %]
108 Total Owed For Transaction: [% circ.billable_transaction.summary.total_owed %]
109 Library: [% circ.circ_lib.name %]
112 . Once you are satisfied with your new event trigger, click the _Save_ button located at the bottom of the form.
117 A quick and easy way to create new action triggers is to clone an existing action trigger.
120 [[creating_alternate_message_templates]]
121 ==== Creating Alternate Message Templates ====
122 indexterm:[Localization, Notices, Localized Notices]
124 As of version 3.9 there is the ability to create alternate templates for Action Triggers that will generate locale specific out for Action Triggers. If you send notices in multiple languages, we recommend putting some words to that effect in your notice templates. The template, message and message title can all be localized. To use the feature the following UI elements have been added:
126 * When you double-click on an Event Definition under Notifications / Action Triggers to edit it there will be a tab option for _Edit Alternate Template_ if the reactor is *ProcessTemplate*, *SendEmail*, or *SendSMS*. Note that this feature does not automatically translate existing templates, and an Evergreen administrator must create new alternate templates for each desired locale.
127 * In the Patron Registration and Patron Editor screens staff members may select a locale for a patron and edit it in the _Patron Preferred Language_ field.
128 * Patrons may set their own locale in the My Account interface off the OPAC by going to _Preferences --> Personal Information_ and setting the _Preferred Language_ field.
130 The templates used on the Edit Definition tab are the defaults that are used if there are no alternate templates available that match the preferred language. If alternate templates are available the system will use a locale that is an exact match and then if failing that use one where the language code matches and then fall back to the default one.
132 For example, if a patron has a locale of fr-CA and there are templates for both fr-CA and fr-FR it will use the fr-CA. If the fr-CA template was deleted it would fall back on using the fr-FR for the patron since it at least shares the same base language.
134 Valid locales are the codes defined in the `i18n_locale` table in the config schema.
139 === Cloning Existing Action Triggers ===
141 . Right click on the line of the action trigger you wish to clone, and choose _Clone Selected_.
142 .. You will be asked to confirm whether or not you wish to clone the event definition environment along with the action trigger.
143 . 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.
146 === Editing Action Triggers ===
148 . Double-click on the action trigger you wish to edit or right click on the line of the action trigger you wish to edit, and choose _Edit Event Definition_.
149 . The Edit Definition screen will appear. When you are finished editing, click _Save_ at the bottom of the form. Or click _Back to Notification/Action Triggers_ to exit without saving.
152 === Deleting Action Triggers ===
154 . Right click on the line of the action trigger you wish to delete.
155 . Choose _Delete Selected_ ofrom the action menu.
159 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.
162 === Testing Action Triggers ===
164 . Go to the list of action triggers.
165 . . Double-click on the action trigger you wish to edit or right click on the line of the action trigger you wish to edit, and choose _Edit Event Definition_.
166 . Go to the _Run Tests_ tab.
167 . If there is a test available, fill in the required information and click _Go_.
168 . View the output of the test.
170 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.
176 Hooks define the Fieldmapper class in the core_type column off of which the rest of the field definitions "hang".
179 ==== Table 2. Hooks ====
182 |=======================
183 | *Field* | *Description*
184 | Hook Key | A unique name given to the hook.
185 | Core Type | Used to link the action trigger to the IDL class in `fm_IDL.xml`
186 | Description | Text to describe the purpose of the hook.
187 | Passive | Indicates whether or not an event is created by direct user action or is circumstantial.
188 |=======================
190 You may also create, edit and delete Hooks but the Core Type must refer to an IDL class in the `fm_IDL.xml` file.
197 Reactors link the trigger definition to the action to be carried out.
199 ==== Table 3. Action Trigger Reactors ====
202 |=======================
203 | Field | Description
204 | 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`.
205 | Description | Description of the Action to be carried out.
206 |=======================
208 You may also create, edit and delete Reactors. Just remember that there must be an associated subroutine or module in the Reactor Perl module.
210 ==== CallHTTP Reactor ====
212 This Action/Trigger reactor module allows an Evergreen administrator to
213 create event defintions that use HTTP (or HTTPS) to contact external services
214 and let them know that something has happened in Evergreen.
216 For instance, a discovery layer can be informed when a bib record is updated
217 or when a user's barcode changes.
219 ===== CallHTTP Reactor Template Syntax =====
221 The new reactor module uses a template to define its behavior. While the
222 template is processed by Template Toolkit, as with any A/T templates, its
223 output format is new to Evergreen.
225 The template should output data that can be parsed by the Config::General Perl
226 module. See: https://metacpan.org/pod/Config::General
228 Top level settings should include the HTTP *method* and the *url*.
230 A block called *Headers* can be used to supply arbitrary HTTP headers.
232 A block called *Parameters* can be used to append CGI parameters to the URL,
233 most useful for GET form submission. Repeated parameters are allowed. If
234 this block is used, the URL should /not/ contain any parameters, use one or
237 A HEREDOC called *content* can be used with POST or PUT to send an arbitrary block
238 of content to the remote server.
240 If the requested URL requires Basic or Digest authentication, the template can
241 include top level configuration parameters to supply a *user*, *password*, *realm*,
242 and hostname:port *location*.
244 A default user agent string of "EvergreenReactor/1.0" is used when sending requests.
245 This can be overridden using the top level *agent* setting.
247 Here is an example template that could be used by a definition attached to the
252 method post # Valid values are post, get, put, delete, head
253 url https://example.com/api/incoming-update
254 agent MySpecialAgent/0.1
259 location example.com:443
282 Validators set the validation test to be preformed to determine whether the action trigger is executed.
284 ==== Table 4. Action Trigger Validators ====
287 |=======================
288 | Field | Description
289 | Module Name | The name of the subroutine in `/openils/lib/perl5/OpenILS/Application/Trigger/Reactor.pm` to validate the action trigger.
290 | Description | Description of validation test to run.
291 |=======================
293 You may also create, edit and delete Validators. Just remember that their must be an associated subroutine in the Reactor.pm Perl module.
295 [#processing_action_triggers]
296 == Processing Action Triggers ==
298 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:
301 /openils/bin/action_trigger_runner.pl --process-hooks --run-pending
304 You have several options when running the script:
306 * --run-pending: Run pending events to send emails or take other actions as
307 specified by the reactor in the event definition.
309 * --process-hooks: Create hook events
311 * --osrf-config=[config_file]: OpenSRF core config file. Defaults to:
312 /openils/conf/opensrf_core.xml
314 * --custom-filters=[filter_file]: File containing a JSON Object which describes any hooks
315 that should use a user-defined filter to find their target objects. Defaults to:
316 /openils/conf/action_trigger_filters.json
318 * --max-sleep=[seconds]: When in process-hooks mode, wait up to [seconds] for the lock file to go
319 away. Defaults to 3600 (1 hour).
321 * --hooks=hook1[,hook2,hook3,...]: Define which hooks to create events for. If none are defined, it
322 defaults to the list of hooks defined in the --custom-filters option.
323 Requires --process-hooks.
325 * --granularity=[label]: Limit creating events and running pending events to
326 those only with [label] granularity setting.
328 * --debug-stdout: Print server responses to STDOUT (as JSON) for debugging.
330 * --lock-file=[file_name]: Sets the lock file for the process.
332 * --verbose: Show details of script processing.
334 * --help: Show help information.
338 * Run all pending events that have no granularity set. This is what you tell
339 CRON to run at regular intervals.
342 perl action_trigger_runner.pl --run-pending
345 * Batch create all "checkout.due" events
348 perl action_trigger_runner.pl --hooks=checkout.due --process-hooks
351 * Batch create all events for a specific granularity and to send notices for all
352 pending events with that same granularity.
355 perl action_trigger_runner.pl --run-pending --granularity=Hourly --process-hooks
358 [[configure_opac_email_print]]
359 == Configure OPAC Record Email and Print ==
361 The information displayed in the printout and email is defined and generated by two new Notification/Action Triggers named `biblio.record_entry.print` and `biblio.record_entry.email`.
363 The printout and email will include the following bibliographic information by default:
365 * Bibliographic Record ID
375 If *Full display* is selected by the OPAC user, the following holdings information is included in the printout or email, if relevant:
377 * Circulating Library
379 * Call Number (including prefix and suffix)
384 The bibliographic and item information included in the printout or email can be configured by modifying the respective Action Trigger templates.
386 For the Full display, the maximum number of copies to be displayed per record can also be configured in the Action Trigger Event Parameter field. To set the maximum number of copies for display, go to *Administration -> Local Administration -> Notifications / Action Triggers* and find the print or email notification/action trigger to modify.
388 . Double click on the action trigger you wish to modify
390 image::actiontriggers/ope_event_defs.png[Email and Print Event Definitions]
392 . Select the *Edit Parameters* tab and in the upper left-hand corner, select *New Parameter* to create a new Trigger Event Parameter.
393 . In the _Parameter Name_ field enter holdings_limit.
394 . In the _Parameter Value_ field enter the maximum number of copies to be displayed per record.
395 . Select *Save* to save your changes.
397 image::actiontriggers/ope_event_params.png[Email and Print Event Parameters]