--- /dev/null
+Action Triggers
+---------------
+
+indexedterm:[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: <<event_definitions, Event Definitions>>, <<hooks, Hooks>>, <<reactors, Reactors>> and <<validators, Validators>>.
+
+
+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 <<validators, Validators>> and/or <<reactors, Reactors>> for processing.
+| <<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''.
+| 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.
+| <<reactors, Reactor>> |Links the action trigger to the Reactor.
+| <<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_.
+| 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, 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. Eg. _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 the pending events
+
+* --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.
+
+* --debug-stdout: Print server responses to STDOUT (as JSON) for debugging.
+
+* --lock-file=[file_name]: Sets the lock file for the process.
+
+* --help: Show help information.
+
projects / evergreen / masslnc.git / commitdiff