Action Triggers --------------- indexterm:[action triggers, event definitions] 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 *Admin* -> *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: <>, <>, <> and <>. anchor: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 <> and/or <> for processing. | <> |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. | <> |Links the action trigger to the Reactor. | <> |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. | Granularity |Used to group events by how often they should be run. Options are hourly, daily, weekdays, weekly, monthly, yearly, but you may also create new values. |=============================================== Creating Action Triggers ~~~~~~~~~~~~~~~~~~~~~~~~ . From the top menu, select *Admin* -> *Local Administration* -> *Notifications / Action triggers*. . Click on the _New_ button. . 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_, _Validator_, _Failure Cleanup_. . Select the _Granularity_. . Set the _Max Event Validity Delay_. . Select the _Opt-In Setting Type_. . Set the _Opt-In User Field_. . Select the _Success Cleanup_. . 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: [%- params.sender_email || default_sender %] Subject: Overdue Items Marked Lost 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. anchor: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. anchor: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. anchor: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 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 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: ---- /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 ----