Add notifications section to server administration chapter.

Action trigger edits.

diff --git a/1.6/admin/actiontriggers.xml b/1.6/admin/actiontriggers.xml
index ff2ad72..82c6a47 100644 (file)
--- a/1.6/admin/actiontriggers.xml
+++ b/1.6/admin/actiontriggers.xml
@@ -295,27 +295,22 @@ The following items are 90 days overdue and have been marked LOST.
                <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
                <option>--process-hooks</option> <option>--run-pending</option></command>. This should be set up as a cron job to run \r
                periodically.</para> \r
-               <para>You will need to add some Hooks to the /openils/conf/action_trigger_filters.json file. Below is an example to add the <emphasis>password.reset_request</emphasis>, \r
-               <emphasis>hold.available</emphasis> and <emphasis>checkout.due</emphasis> hooks so that they will be processed by <command>action_trigger_runner.pl</command>.</para> \r
-                       \r
-<programlisting><![CDATA[\r
-{\r
-       "password.reset_request" : { },\r
-\r
-        "hold.available": {},\r
-\r
-       "checkout.due" :\r
-           { "context_org" : "circ_lib", "filter"      :\r
-                   { "checkin_time"  : null,\r
-                     "-or"           :\r
-                           [ { "stop_fines"  : ["MAXFINES", "LONGOVERDUE"] },\r
-                             { "stop_fines"  : null }\r
-                           ]\r
-                   }\r
-           }\r
-}\r
-]]>\r
-</programlisting>\r
+               <para>You have several options when running the script:</para>\r
+               <itemizedlist>\r
+                       <listitem><option>--run-pending</option>: Run the pending events.</listitem>\r
+                       <listitem><option>--process-hooks</option>: Create hook events</listitem>\r
+                       <listitem><option>--osrf-config=[<varname>config_file</varname>]</option>: OpenSRF core config file.  Defaults to: \r
+                       <filename>/openils/conf/opensrf_core.xml</filename>.</listitem>\r
+                       <listitem><option>--custom-filters=[<varname>filter_file</varname>]</option>: File containing a JSON Object which describes any hooks that should\r
+                       use a user-defined filter to find their target objects.  Defaults to: <filename>/openils/conf/action_trigger_filters.json</filename></listitem>\r
+                       <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
+                       Defaults to 3600 (1 hour).</listitem>\r
+                       <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
+                       in the <option>--custom-filters</option> option.</listitem>\r
+                       <listitem><option>--debug-stdout</option>: Print server responses to stdout (as JSON) for debugging.</listitem>\r
+                       <listitem><option>--lock-file=[<varname>file_name</varname>]</option>: Sets the lock file for the process.</listitem>\r
+                       <listitem><option>--help</option>: Show help information.</listitem>\r
+               </itemizedlist>\r
        </section>                                                                                                                                      \r
 </chapter>\r
 \r

diff --git a/1.6/admin/serveradministration.xml b/1.6/admin/serveradministration.xml
index cf27a50..5bd6e4c 100644 (file)
--- a/1.6/admin/serveradministration.xml
+++ b/1.6/admin/serveradministration.xml
@@ -2048,6 +2048,200 @@ WHERE id = 17;
                </simplesect> \r
        </section>\r
        <section xml:id="notifications">\r
-               <title>Notifications</title>\r
+               <title>Email Notifications</title>\r
+               <para>Email notifications can be set up for Holds, Overdue items and Predue items. There are two ways to configure notifications for each of these type of notifications.</para>\r
+               <section xml:id="Holdnotifications">\r
+                       <title>Hold Notifications</title>\r
+                       <para>Hold notifications can be used that that library users are sent an email when their items are available for pickup. This notification is triggered when the item being held \r
+                       is <emphasis>captured</emphasis> by a library staff member and the item is in the <emphasis>on holds shelf</emphasis> status. </para>\r
+                       <simplesect>                    \r
+                               <title>Hold Notifications using the Action Trigger</title> \r
+                               <para>The easiest way to set up hold notifications is to use the <link linkend="actiontriggers">Action Trigger</link> mechanism introduced in Evergreen 1.6.</para>                     \r
+                               <procedure>\r
+                               <step>\r
+                               <para>From the staff client menu, Click on\r
+                                       <menuchoice>\r
+                                               <guimenu>Admin</guimenu>  \r
+                                               <guisubmenu>Local Administration</guisubmenu>\r
+                                               <guisubmenu>Notifications / Action triggers</guisubmenu>\r
+                                       </menuchoice>\r
+                               </para>\r
+                               </step>\r
+\r
+                               <step>\r
+                                       <para>Locate the Action Trigger Definition with the <guilabel>Name</guilabel> <guilabel>Hold Ready for Pickup Email Notification</guilabel>.</para>\r
+                               </step>\r
+                               <step>\r
+                                       <para>Double click on the item row to open the editing page, but <emphasis role="bold">not</emphasis> on the hyperlinked <guilabel>Name</guilabel></para>\r
+                               </step>\r
+                               <step>\r
+                                       <para>Double click on the item row to open the editing page, but <emphasis role="bold">not</emphasis> on the hyperlinked <guilabel>Name</guilabel></para>\r
+                               </step>\r
+                               <step>\r
+                                       <para>Check the <guilabel>Enabled</guilabel> check box to enable it.</para>\r
+                               </step>\r
+                               <step>\r
+                                       <para>Edit the <guilabel>Template</guilabel> text box to customize the body of the email as needed. Note that text between <quote>[% %]</quote> are variables to be \r
+                                       generated by the system. For example, <varname>[% user.family_name %]</varname> with be replaced by the family name of the user receiving a notice.</para>\r
+                               </step>\r
+                               <step>\r
+                                       <para>Click <guibutton>Save</guibutton> to save your changes.</para>\r
+                               </step>\r
+                               <step>\r
+                                       <para>Hold notices are now activated and will be processed the next time action triggers are processed. See <xref linkend="ProcessingActionTriggers" /> for \r
+                                       more details on processing action triggers.</para>\r
+                               </step>\r
+                               </procedure>\r
+                       </simplesect>   \r
+                       <simplesect>                    \r
+                               <title>Hold Notifications using the Evergreen Configuration File</title> \r
+                               <para>An older method for Setting up hold notifications is through the Configuration file <filename>/openils/conf/opensrf.xml</filename>. </para>                       \r
+                               <procedure>\r
+                                       <step>\r
+                                               <para>Open the file <filename>/openils/conf/opensrf.xml</filename> with your favorite text editor</para>\r
+                                               <para>Locate this section of the configuration file:</para>\r
+\r
+<programlisting><![CDATA[\r
+<notify_hold>\r
+<email>true</email> <!-- set to true for hold notice emails -->\r
+</notify_hold>\r
+]]>\r
+</programlisting>              \r
+               \r
+\r
+                                               <para>Ensure that &lt;email&gt; is set to <emphasis role="bold">true</emphasis>.</para>\r
+                                       </step>\r
+                                       <step>\r
+                                               <para>Locate the following section of the configuration file:</para>\r
+<programlisting> <![CDATA[\r
+...\r
+<email_notify> \r
+            <!-- global email notification settings -->\r
+            <template>/openils/var/data/hold_notification_template.example</template>\r
+...\r
+]]>\r
+</programlisting>\r
+                                               <para>Point the &lt;template&gt; variable to the hold notification template you will be using for hold notifications.</para>\r
+                                       </step>\r
+                                       <step>\r
+                                               <para>Locate the template and edit as desired. Use the example template provided as a guide.</para>\r
+                                       </step>\r
+                               </procedure>\r
+                       </simplesect>   \r
+               </section> \r
+               <section xml:id="overedueandpreduenotifications">\r
+                       <title>Overdue and Predue Notifications</title> \r
+                       <para>Overdue and Predue email notifications can be used to inform users that they have materials which are overdue or to warn them that materials are almost overdue.</para>  \r
+                       <simplesect>                    \r
+                               <title>Activating Overdue Existing Overdue Action Triggers</title> \r
+                               <para>The easiest way to set up overdue notifications is to use the <link linkend="actiontriggers">Action Trigger</link> mechanism introduced in Evergreen 1.6.</para>                  \r
+                               <procedure>\r
+                               <step>\r
+                               <para>From the staff client menu, Click on\r
+                                       <menuchoice>\r
+                                               <guimenu>Admin</guimenu>  \r
+                                               <guisubmenu>Local Administration</guisubmenu>\r
+                                               <guisubmenu>Notifications / Action triggers</guisubmenu>\r
+                                       </menuchoice>\r
+                               </para>\r
+                               </step>\r
+\r
+                               <step>\r
+                                       <para>Locate the Action Trigger Definition you wish to activate. There are several overdue notices preloaded wit Evergreen 1.6.</para>\r
+                               </step>\r
+                               <step>\r
+                                       <para>Double click on the item row to open the editing page, but <emphasis role="bold">not</emphasis> on the hyperlinked <guilabel>Name</guilabel></para>\r
+                               </step>\r
+                               <step>\r
+                                       <para>Double click on the item row to open the editing page, but <emphasis role="bold">not</emphasis> on the hyperlinked <guilabel>Name</guilabel></para>\r
+                               </step>\r
+                               <step>\r
+                                       <para>Check the <guilabel>Enabled</guilabel> check box to enable it.</para>\r
+                               </step>\r
+                               <step>\r
+                                       <para>Edit the <guilabel>Template</guilabel> text box to customize the body of the email as needed. Note that text between <quote>[% %]</quote> are variables to be \r
+                                       generated by the system. For example, <varname>[% user.family_name %]</varname> with be replaced by the family name of the user receiving a notice.</para>\r
+                               </step>\r
+                               <step>\r
+                                       <para>Click <guibutton>Save</guibutton> to save your changes.</para>\r
+                               </step>\r
+                               <step>\r
+                                       <para>Overdue notices are now activated and will be processed the next time action triggers are processed. See <xref linkend="ProcessingActionTriggers" /> for \r
+                                       more details on processing action triggers.</para>\r
+                               </step>\r
+                               </procedure>\r
+                       </simplesect>   \r
+                       <simplesect>                    \r
+                               <title>Creating Overdue and Predue Notifications by Cloning Existing Action Triggers</title> \r
+                               <para>If you wish to add overdue notices for different periods of time or wish to create a predue notice simply clone an existing overdue note, give it a \r
+                               unique <guilabel>Name</guilabel>, customize as needed. and save.</para>\r
+                               <para>There are no pre-existing predue notices so they will need to be created by cloning an existing overdue notice. \r
+                               To make them predue notices, use a negative value in the <guilabel>Processing Delay Context Field</guilabel>. For example, to create a predue notice the day before the \r
+                               due date, use the value <emphasis>-1 days</emphasis>.</para>                    \r
+                       </simplesect>\r
+                       <simplesect>                    \r
+                               <title>Creating Overdue and Predue Notices using the Evergreen Configuration File</title> \r
+                               <para>It is also possible to create overdue and predue notices using the Evergreen configuration file <filename>/openils/conf/opensrf.xml</filename></para>     \r
+                               <procedure>\r
+                               <step>\r
+                                       <para>Open <filename>/openils/conf/opensrf.xml</filename> with your favorite text editor.</para>\r
+                                       <para>Locate this section of the configuration file:</para>\r
+\r
+<programlisting><![CDATA[\r
+<overdue>\r
+...\r
+            <notice>\r
+                <!-- Notify at 7 days overdue -->\r
+                <notify_interval>7 days</notify_interval>\r
+                <!-- Options include always, noemail, and never.  'noemail' means a notice\r
+                     will be appended to the notice file only if the patron has no valid email address.  -->\r
+                <file_append>noemail</file_append>\r
+                <!-- do we attempt email notification? -->\r
+                <email_notify>true</email_notify>\r
+                <!-- notice template file -->\r
+                <email_template>/openils/var/data/templates/overdue_7day.example</email_template>\r
+            </notice>\r
+        </overdue>\r
+<!-- Courtesy notices -->\r
+        <predue>\r
+            <notice>\r
+                <!-- All circulations that circulate between 5 and 13 days -->\r
+                <circ_duration_range>\r
+                    <from>3 days</from>\r
+                    <to>13 days</to>\r
+                </circ_duration_range>\r
+                <!-- notify at 1 day before the due date -->\r
+                <notify_interval>1 day</notify_interval>\r
+                <file_append>false</file_append>\r
+                <email_notify>true</email_notify>\r
+                <email_template>/openils/var/data/templates/predue_1day.example</email_template>\r
+            </notice>\r
+        </predue>\r
+...\r
+]]>\r
+</programlisting>                              \r
+                                       </step>\r
+                                       <step>\r
+                                               <para>From this section of the configuration file, you may:</para>\r
+                                               <itemizedlist>\r
+                                                       <listitem>Point to the template file for the specific notice: &lt;email_template&gt;</listitem>\r
+                                                       <listitem>Set the interval time for the specific notice: &lt;notify_interval&gt;</listitem>\r
+                                                       <listitem>Indicate whether to attempt email notification for the notice: &lt;email_notify&gt;</listitem>\r
+                                                       <listitem>For predue notices, you may also specify on which circulation ranges to activate the courtesy notice: \r
+                                                       &lt;circ_duration_range&gt;</listitem>\r
+                                               </itemizedlist>\r
+                                       </step>\r
+                                       <step>\r
+                                               <para>Locate the templates and edit as desired. Use the example templates provided as guides.</para>\r
+                                       </step>\r
+                                       <step>\r
+                                               <para>From the configuration file you may also set the default email sender address. however, this is just the default and the email sender \r
+                                               address for specific organizational units can be specified in the <link linkend="lsa-library-settings">library settings editor</link> \r
+                                               from the staff client.</para>\r
+                                       </step>\r
+                               </procedure>\r
+                               <note><para>You also need to set the email server from the configuration file. By default, it uses the <systemitem class="domainname">localhost</systemitem>.</para></note> \r
+                       </simplesect>\r
+               </section>\r
        </section>\r
 </chapter>\r