Part V. Local Administration

Notifications / Action Triggers

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 AdminLocal AdministrationNotifications / 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, Hooks, Reactors and Validators.

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 and/or Reactors for processing.

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.

Reactor

Links the action trigger to the Reactor.

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.

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

  1. From the top menu, select AdminLocal AdministrationNotifications / Action triggers.
  2. Click on the New button.
  3. Select an Owning Library.
  4. Create a unique Name for your new action trigger.
  5. Select the Hook.
  6. Check the Enabled check box.
  7. 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.
  8. Set the Processing Delay Context Field and Processing Group Context Field.
  9. Select the Reactor, Validator, Failure Cleanup.
  10. Select the Granularity.
  11. Set the Max Event Validity Delay.
  12. Select the Opt-In Setting Type.
  13. Set the Opt-In User Field.
  14. Select the Success Cleanup.
  15. 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 %]
  16. 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

  1. Check the check box next to the action trigger you wish to clone.
  2. Click Clone Selected on the top left of the page.
  3. 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.
  4. Click Save.

Editing Action Triggers

  1. Double-click on the action trigger you wish to edit.
  2. 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

  1. Check the check box next to the action trigger you wish to delete
  2. Click Delete Selected on the top-right of the page.

Hooks

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

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 link the trigger definition to the action to be carried out.

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 set the validation test to be preformed to determine whether the action trigger is executed.

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