1.6/admin/actiontriggers.xml

   1 <?xml version="1.0" encoding="utf-8"?>\r
   2 <chapter xml:id="actiontriggers" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
   3     xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
   4     <info>\r
   5         <title>Action Triggers</title>\r
   6         <indexterm><primary>action triggers</primary></indexterm>    \r
   7         </info>\r
   8         <para>Action Triggers were introduced to Evergreen in 1.6. They allow administrators the ability to set up actions for specific events. They are useful for notification events such as \r
   9         hold notifications.</para>\r
  10         \r
  11                         \r
  12         <para>To access the Action Triggers module, select\r
  13                 <menuchoice>\r
  14                         <guimenu>Admin</guimenu>  \r
  15                         <guisubmenu>Local Administration</guisubmenu>\r
  16                         <guisubmenu>Notifications / Action triggers</guisubmenu>\r
  17                 </menuchoice>\r
  18         </para>\r
  19         <note><para>You must have Local Administrator permissions to access the Action Triggers module.</para></note>\r
  20         <para>You will notice four tabs on this page: <guilabel><link linkend="eventdefinitions">Event Definitions</link></guilabel>, <guilabel><link linkend="Hooks">Hooks</link></guilabel>, \r
  21         <guilabel><link linkend="Reactors">Reactors</link></guilabel> and <guilabel><link linkend="Validators">Validators</link></guilabel>.</para>\r
  22                 \r
  23         <section xml:id="eventdefinitions">\r
  24                 <title>Event Definitions</title>\r
  25                 <indexterm><primary>action triggers</primary><secondary>event definitions</secondary></indexterm>   \r
  26                 <para><guilabel>Event Definitions</guilabel> is the main tab and contains the key fields when working with action triggers. These fields include:</para>\r
  27                         <table xml:id="eventdefinitionstable">\r
  28                                 <title>Action Trigger Event Definitions</title>\r
  29                                 <tgroup cols="2">\r
  30                                         <colspec colnum="1" colname="col1" colwidth="1.0*"/>\r
  31                                         <colspec colnum="2" colname="col2" colwidth="3.0*"/>\r
  32                                         <thead>\r
  33                                                 <row>\r
  34                                                         <entry>Field</entry>\r
  35                                                         <entry>Description</entry>\r
  36                                                 </row>\r
  37                                         </thead>\r
  38                                         <tbody>\r
  39                                                 <row>\r
  40                                                         <entry><guilabel>Owning library</guilabel></entry>\r
  41                                                         <entry>The shortname of the library for which the action / trigger / hook is defined.</entry>\r
  42                                                 </row>\r
  43                                                 <row>\r
  44                                                         <entry><guilabel>Name</guilabel></entry>\r
  45                                                         <entry>The name of the trigger event, that links to a trigger event environment containing a set of fields  \r
  46                                                         that will be returned to the <link linkend="Validators">Validators</link> / <link linkend="Reactors">Reactors</link> for processing.</entry>\r
  47                                                 </row>\r
  48                                                 <row>\r
  49                                                         <entry><guilabel><link linkend="Hooks">Hooks</link></guilabel></entry>\r
  50                                                         <entry>The name of the trigger for the trigger event. The underlying action_trigger.hook table defines the Fieldmapper \r
  51                                                         class in the core_type column off of which the rest of the field definitions <quote>hang</quote>. </entry>\r
  52                                                 </row>\r
  53                                                 <row>\r
  54                                                         <entry><guilabel>Enabled</guilabel></entry>\r
  55                                                         <entry>Sets the given trigger as enabled or disabled. This must be set to enabled for the Action trigger to run.</entry>\r
  56                                                 </row>\r
  57                                                 <row>\r
  58                                                         <entry><guilabel>Processing Delay</guilabel></entry>\r
  59                                                         <entry>Defines how long after a given trigger / hook event has occurred before the associated action (<quote>Reactor</quote>) \r
  60                                                         will be taken.</entry>\r
  61                                                 </row>\r
  62                                                 <row>\r
  63                                                         <entry><guilabel>Processing Delay Field</guilabel></entry>\r
  64                                                         <entry>Defines the field associated with the event on which the processing delay is calculated. For example, the processing delay \r
  65                                                         context field on the hold.capture hook (which has a core_type of ahr) is <emphasis>capture_time</emphasis>.</entry>\r
  66                                                 </row>\r
  67                                                 <row>\r
  68                                                         <entry><guilabel>Processing Group Context Field</guilabel></entry>\r
  69                                                         <entry>Used to batch actions based on its associated group.</entry>\r
  70                                                 </row>\r
  71                                                 <row>\r
  72                                                         <entry><guilabel><link linkend="Validators">Validators</link></guilabel></entry>\r
  73                                                         <entry>The subroutines receive the trigger environment as an argument (see the linked <emphasis>Name</emphasis> for \r
  74                                                         the environment definition) and returns either <emphasis>1</emphasis> if the validator is <emphasis>true</emphasis> or <emphasis>0</emphasis> \r
  75                                                         if the validator returns <emphasis>false</emphasis>.</entry>\r
  76                                                 </row>\r
  77                                                 <row>\r
  78                                                         <entry><guilabel><link linkend="Reactors">Reactors</link></guilabel></entry>\r
  79                                                         <entry>Links the action trigger to the Reactor.</entry>\r
  80                                                 </row>\r
  81                                                 <row>\r
  82                                                         <entry><guilabel>Max Event Validity Delay</guilabel></entry>\r
  83                                                         <entry>Define the threshold for how far back the action_trigger_runner.pl script should reach to generate \r
  84                                                         a batch of events.</entry>\r
  85                                                 </row>\r
  86                                         </tbody>        \r
  87                                 </tgroup>\r
  88                         </table>\r
  89                 \r
  90                 <procedure>\r
  91                 <title>Creating Action Triggers</title>\r
  92                 <indexterm><primary>action triggers</primary><secondary>creating</secondary></indexterm>  \r
  93                         <step>\r
  94                                 <para>From the top menu, select\r
  95                                         <menuchoice>\r
  96                                                 <guimenu>Admin</guimenu>  \r
  97                                                 <guisubmenu>Local Administration</guisubmenu>\r
  98                                                 <guisubmenu>Notifications / Action triggers</guisubmenu>\r
  99                                         </menuchoice>\r
 100                                 </para>\r
 101                         </step>\r
 102                         <step><para>Click on the <guibutton>New</guibutton> button.</para></step>\r
 103                         <step><para>Select an <guilabel>Owning Library</guilabel>.</para></step>\r
 104                         <step><para>Create a unique <guilabel>Name</guilabel> for your new action trigger.</para></step>                                \r
 105                         <step><para>Select the <guilabel>Hook</guilabel>.</para></step>\r
 106                         <step><para>Check the <guilabel>Enabled</guilabel> check box.</para></step>\r
 107                 \r
 108                         <step><para>Create a unique <guilabel>Name</guilabel> for your new action trigger.</para></step>\r
 109                         <step><para>Set the <guilabel>Processing Delay</guilabel> in the appropriate format. Eg. <emphasis class="bold">7 days</emphasis> to run 7 days from the trigger event \r
 110                         or <emphasis class="bold">00:01:00</emphasis> to run 1 hour after the <guilabel>Processing Delay Context Field</guilabel>.</para></step>\r
 111                         <step><para>Set the <guilabel>Processing Delay Context Field</guilabel> and <guilabel>Processing Group Context Field</guilabel>.</para></step>  \r
 112                         <step><para>Select the <guilabel>Validator</guilabel>, <guilabel>Reactor</guilabel>, <guilabel>Failure Cleanup</guilabel> and <guilabel>Success Cleanup</guilabel>.\r
 113                         </para></step>  \r
 114                         <step><para>Set the <guilabel>Processing Delay Context Field</guilabel> and <guilabel>Processing Group Context Field</guilabel>.</para></step>  \r
 115                         <step preformance="optional"><para>Enter text in the <guilabel>Template</guilabel> text box if required. These are for email messages. Here is an sample \r
 116                         template for sending 90 day overdue notices:</para>\r
 117 <programlisting><![CDATA[\r
 118 \r
 119 [%- USE date -%]\r
 120 [%- user = target.0.usr -%]\r
 121 To: [%- params.recipient_email || user.email %]\r
 122 From: [%- params.sender_email || default_sender %]\r
 123 Subject: Overdue Items Marked Lost\r
 124 \r
 125 Dear [% user.family_name %], [% user.first_given_name %]\r
 126 The following items are 90 days overdue and have been marked LOST.\r
 127 [%- params.recipient_email || user.email %][%- params.sender_email || default_sender %]\r
 128 [% FOR circ IN target %]\r
 129     Title: [% circ.target_copy.call_number.record.simple_record.title %] \r
 130     Barcode: [% circ.target_copy.barcode %] \r
 131     Due: [% date.format(helpers.format_date(circ.due_date), '%Y-%m-%d') %]\r
 132     Item Cost: [% helpers.get_copy_price(circ.target_copy) %]\r
 133     Total Owed For Transaction: [% circ.billable_transaction.summary.total_owed %]\r
 134     Library: [% circ.circ_lib.name %]\r
 135 [% END %]\r
 136 \r
 137 \r
 138 [% FOR circ IN target %]\r
 139     Title: [% circ.target_copy.call_number.record.simple_record.title %] \r
 140     Barcode: [% circ.target_copy.barcode %] \r
 141     Due: [% date.format(helpers.format_date(circ.due_date), '%Y-%m-%d') %]\r
 142     Item Cost: [% helpers.get_copy_price(circ.target_copy) %]\r
 143     Total Owed For Transaction: [% circ.billable_transaction.summary.total_owed %]\r
 144     Library: [% circ.circ_lib.name %]\r
 145 [% END %]\r
 146 ]]>\r
 147 </programlisting>       \r
 148                         </step> \r
 149                         <step><para>Once you are satisfied with your new event trigger , click the <guibutton>Save</guibutton> button located at the bottom of the \r
 150                         form</para></step>\r
 151                 </procedure>\r
 152                 <tip><para>A quick and easy way to create new action triggers is to clone an existing action trigger.</para></tip>\r
 153                 <procedure>\r
 154                         <title>Cloning Existing Action Triggers</title>\r
 155                         <step>\r
 156                                 <para>Check the check box next to the action trigger you wish to clone</para>\r
 157                         </step>\r
 158                         <step>\r
 159                                 <para>Click the <guibutton>Clone Selected</guibutton> on the top left of the page.</para>\r
 160                         </step>\r
 161                         <step>\r
 162                                 <para>An editing window with open. Notice that the fields will be populated with content from the cloned action trigger. Edit as necessary and \r
 163                         give the new action trigger a unique <guilabel>Name</guilabel>.</para>\r
 164                         </step>\r
 165                         <step>\r
 166                                 <para>Click <guilabel>Save</guilabel>.</para>\r
 167                         </step>\r
 168                 </procedure>\r
 169                 <procedure>\r
 170                         <title>Editing Action Triggers</title>\r
 171                         <step>\r
 172                                 <para>Check the check box next to the action trigger you wish to delete</para>\r
 173                         </step>\r
 174                         <step>\r
 175                                 <para>Click the <guibutton>Delete Selected</guibutton> on the top left of the page.</para>\r
 176                         </step>\r
 177                 </procedure>\r
 178                 \r
 179                 <note><para>Before deleting an action trigger, you should consider disabling it through the editing form. This way you can simply enable it if you decide that you would like to use \r
 180                 the action trigger in the future.</para></note>\r
 181                 <procedure>\r
 182                         <title>Deleting Action Triggers</title>\r
 183                         <step>\r
 184                                 <para>Check the check box next to the action trigger you wish to delete</para>\r
 185                         </step>\r
 186                         <step>\r
 187                                 <para>Click the <guibutton>Delete Selected</guibutton> on the top left of the page.</para>\r
 188                         </step>\r
 189                 </procedure>\r
 190         </section>\r
 191         <section xml:id="Hooks">\r
 192                 <title>Hooks</title>\r
 193                 <indexterm><primary>action triggers</primary><secondary>hooks</secondary></indexterm>\r
 194                 <para><guilabel>Hooks</guilabel> define the Fieldmapper class in the core_type column off of which the rest of the field definitions <quote>hang</quote>.</para>\r
 195                 <table xml:id="Hookstable">\r
 196                         <title>Hooks</title>\r
 197                         <tgroup cols="2">\r
 198                                 <colspec colnum="1" colname="col1" colwidth="1.0*"/>\r
 199                                 <colspec colnum="2" colname="col2" colwidth="3.0*"/>\r
 200                                 <thead>\r
 201                                         <row>\r
 202                                                 <entry>Field</entry>\r
 203                                                 <entry>Description</entry>\r
 204                                         </row>\r
 205                                 </thead>\r
 206                                 <tbody>\r
 207                                         <row>\r
 208                                                 <entry><guilabel>Hook Key</guilabel></entry>\r
 209                                                 <entry>A unique name given to the hook.</entry>\r
 210                                         </row>\r
 211                                         <row>\r
 212                                                 <entry><guilabel>Core Type</guilabel></entry>\r
 213                                                 <entry>Used to link the action trigger to the IDL class in fm_IDL.xml</entry>\r
 214                                         </row>\r
 215                                         <row>\r
 216                                                 <entry><guilabel>Description</guilabel></entry>\r
 217                                                 <entry>Text to describe the purpose of the hook. </entry>\r
 218                                         </row>\r
 219                                         <row>\r
 220                                                 <entry><guilabel>Passive</guilabel></entry>\r
 221                                                 <entry>Indicates whether or not an event is created by direct user action or is circumstantial.</entry>\r
 222                                         </row>\r
 223                                 </tbody>        \r
 224                         </tgroup>\r
 225                 </table>\r
 226                 <para>You may also create, edit and delete Hooks but the <guilabel>Core Type</guilabel> must refer to an IDL class in the fm_IDL.xml file.</para>\r
 227         </section>      \r
 228         <section xml:id="Reactors">\r
 229                 <title>Reactors</title>\r
 230                 <indexterm><primary>action triggers</primary><secondary>reactors</secondary></indexterm>\r
 231                 <para><guilabel>Reactors</guilabel> link the trigger definition to the action to be carried out.</para>\r
 232                 <table xml:id="Reactorstable">\r
 233                         <title>Action Trigger Reactors</title>\r
 234                         <tgroup cols="2">\r
 235                                 <colspec colnum="1" colname="col1" colwidth="1.0*"/>\r
 236                                 <colspec colnum="2" colname="col2" colwidth="3.0*"/>\r
 237                                 <thead>\r
 238                                         <row>\r
 239                                                 <entry>Field</entry>\r
 240                                                 <entry>Description</entry>\r
 241                                         </row>\r
 242                                 </thead>\r
 243                                 <tbody>\r
 244                                         <row>\r
 245                                                 <entry><guilabel>Module Name</guilabel></entry>\r
 246                                                 <entry>The name of the Module to run if the action trigger is validated. It must be defined as a subroutine in \r
 247                                                 <filename>/openils/lib/perl5/OpenILS/Application/Trigger/Reactor.pm</filename> or as a module\r
 248                                                  in <filename>/openils/lib/perl5/OpenILS/Application/Trigger/Reactor/*.pm</filename>.</entry>\r
 249                                         </row>\r
 250                                         <row>\r
 251                                                 <entry><guilabel>Description</guilabel></entry>\r
 252                                                 <entry>Description of the Action to be carried out.</entry>\r
 253                                         </row>\r
 254                                 </tbody>        \r
 255                         </tgroup>\r
 256                 </table>\r
 257                 <para>You may also create, edit and delete Reactors. Just remember that their must be an associated subroutine or module in the Reactor Perl module.</para>\r
 258         </section>      \r
 259         <section xml:id="Validators">\r
 260                 <title>Validators</title>\r
 261                 <indexterm><primary>action triggers</primary><secondary>validators</secondary></indexterm>\r
 262                 <para><guilabel>Validators</guilabel> set the validation test to be preformed to determine whether the action trigger is executed.</para>\r
 263                 <table xml:id="Validatorstable">\r
 264                         <title>Action Trigger Validators</title>\r
 265                         \r
 266                         <tgroup cols="2">\r
 267                                 <colspec colnum="1" colname="col1" colwidth="1.0*"/>\r
 268                                 <colspec colnum="2" colname="col2" colwidth="3.0*"/>\r
 269                                 <thead>\r
 270                                         <row>\r
 271                                                 <entry>Field</entry>\r
 272                                                 <entry>Description</entry>\r
 273                                         </row>\r
 274                                 </thead>\r
 275                                 <tbody>\r
 276                                         <row>\r
 277                                                 <entry><guilabel>Module Name</guilabel></entry>\r
 278                                                 <entry>The name of the subroutine in \r
 279                                                 <filename>/openils/lib/perl5/OpenILS/Application/Trigger/Reactor.pm</filename> to validate the action trigger.</entry>\r
 280                                         </row>\r
 281                                         <row>\r
 282                                                 <entry><guilabel>Description</guilabel></entry>\r
 283                                                 <entry>Description of validation test to run.</entry>\r
 284                                         </row>\r
 285                                 </tbody>        \r
 286                         </tgroup>\r
 287                 </table>\r
 288                 <para>You may also create, edit and delete Validators. Just remember that their must be an associated subroutine in the <filename>Reactor.pm</filename> Perl module.</para>\r
 289         </section>      \r
 290         <section xml:id="ProcessingActionTriggers">     \r
 291                 <title>Processing Action Triggers</title>\r
 292                 <indexterm><primary>action triggers</primary><secondary>processing</secondary></indexterm>\r
 293                 <para>To run the action triggers, an Evergreen administrator will need to run the trigger processing script <command>/openils/bin/action_trigger_runner.pl \r
 294                 <option>--process-hooks</option> <option>--run-pending</option></command>. This should be set up as a cron job to run \r
 295                 periodically.</para> \r
 296                 <para>You have several options when running the script:</para>\r
 297                 <itemizedlist>\r
 298                         <listitem><option>--run-pending</option>: Run the pending events.</listitem>\r
 299                         <listitem><option>--process-hooks</option>: Create hook events</listitem>\r
 300                         <listitem><option>--osrf-config=[<varname>config_file</varname>]</option>: OpenSRF core config file.  Defaults to: \r
 301                         <filename>/openils/conf/opensrf_core.xml</filename>.</listitem>\r
 302                         <listitem><option>--custom-filters=[<varname>filter_file</varname>]</option>: File containing a JSON Object which describes any hooks that should\r
 303                         use a user-defined filter to find their target objects.  Defaults to: <filename>/openils/conf/action_trigger_filters.json</filename></listitem>\r
 304                         <listitem><option>--max-sleep=[<varname>seconds</varname>]</option>: When in process-hooks mode, wait up to [<varname>seconds</varname>] for the lock file to go away.  \r
 305                         Defaults to 3600 (1 hour).</listitem>\r
 306                         <listitem><option>--hooks=hook1[,hook2,hook3,...]</option>: Define which hooks to create events for.  If none are defined, it defaults to the list of hooks defined \r
 307                         in the <option>--custom-filters</option> option.</listitem>\r
 308                         <listitem><option>--debug-stdout</option>: Print server responses to stdout (as JSON) for debugging.</listitem>\r
 309                         <listitem><option>--lock-file=[<varname>file_name</varname>]</option>: Sets the lock file for the process.</listitem>\r
 310                         <listitem><option>--help</option>: Show help information.</listitem>\r
 311                 </itemizedlist>\r
 312         </section>                                                                                                                                      \r
 313 </chapter>\r
 314 \r