From 473563cefdb56f6686b03b1a6470c99330213f8a Mon Sep 17 00:00:00 2001 From: Barton Chittenden Date: Sun, 18 Nov 2018 20:44:38 -0500 Subject: [PATCH] Bug 21858: RFC: Notices and slips documentation Koha/Notices.pod documents the following for each notice in the Letter table: * Letter Code * Source file where the notice is populated * Logic that triggers the notice * Detail syntax (if any) * Available data (tables and substitutions) * Message transport restrictions Test plan: Run perldoc Koha/Notices.pod, make sure that the documentation is accurate. --- Koha/Notices.pod | 366 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 366 insertions(+) create mode 100644 Koha/Notices.pod diff --git a/Koha/Notices.pod b/Koha/Notices.pod new file mode 100644 index 0000000..2de781e --- /dev/null +++ b/Koha/Notices.pod @@ -0,0 +1,366 @@ +=head1 NAME + +Koha notices + +=head1 DESCRIPTION + +Koha notices are stored in the 'letter' table, and contain templates +used to populate the 'message_queue' table. Data from the letter +table is read in via C4::Letters::GetPreparedLetter(), which is +called throughout the Koha code base wherever notices are used. + +Notices are added to the message queue via C4::Letters::EnqueueLetter(). +How the template from the letter template is parsed and populated +varies widely from notice to notice; this is where all notices are +documented. For each notice. + + * Module + * Letter Code + * Source file where the notice is populated + * Logic that triggers the notice + * Detail syntax (if any) + * Available data (tables and substitutions). + This should include information about the + relationships between data elements + * Message transport restrictions (if applicable) + +=head1 NOTICE MODULES + +=head2 Circulation + +=over + +=item DUE + + * Source file : advance_notices.pl + * Trigger : Sent the day that a patron has items due. + * Detail syntax : There is no detail -- one notice is sent per item due. + * Available data : <>, <>, <>, <> + +=item PREDUE + +Uses the same fields and syntax ase DUE, except + + * Trigger : Sent X days before item is due, as specified by the patron's messaging + preferences. + +=item DUEDGST + + * Source file : advance_notices.pl + * Trigger : Sent the day that a patron has items due. + * Detail syntax : <> + * Available data : <> (number of items due), <> (patron's home branch) + +<> is replaced in is entirety by the fields 'due date', 'title', 'author' ,'barcode', unless +other fields are specified using the --itemscontent option to advance_notices.pl. +Any column from biblios, items and issues tables may be used in --itemscontent. + +=item PREDUEDGST + +Uses the same fields and syntax ase DUEDGST, except + + * Trigger : Sent X days before items are due, as specified by the patron's + messaging preferences. + +=item Overdue Notices (ODUE*) + + * Source file : overdue_notices.pl + * Trigger : Notices sent X days after items are due, as specified in overdue triggers. + * Detail syntax : <> or ... + * Available data : + +<> Works identically to <> in advance_notices.pl. + + and tags will expand fields from the following tables: + + items + bibio + biblioitems + issues + + items.barcode will show the overdue item's barcode. + +Multiple fields may be expanded inside a single pair of tags. +There is a special tag <> which is only available in within the + tag, which expands to the fine on the overdue item. + +The letter code for overdue notices may change, based on the values set in the Overdue notice triggers. + +=item OVERDUES_SLIP + + * Source file : members/print_overdues.pl + * Detail syntax : Uses the same syntax as ODUE + * Message transports : Print only. + +=item CHECKOUT + + * Source file : C4/Circulation.pm + * Trigger : Data is added to the message in the message queue on every checkout + (see below). + * Detail syntax : See below. + * Available data : <> <> <> <> + <> <> (for CHECKOUT and RENEWAL) + +Notices in C4/Circulation.pm use four dashes before and after the detail section: + + ---- + Detail here + ---- + +This is implemented in C4::Message. + +Data is added to message_queue.metadata; each checkout will print a line of detail between the dashes. +Metadata accumulates until process_message_queue.pl runs. The first subsequent message generates a new +record in message_queue. + +=item RENEWAL + +Uses the same syntax and data as CHECKOUT, except + + * Trigger : Data is added to the message in the message queue on every renewal. + + +=item CHECKIN + +Uses the same syntax and data as CHECKOUT, except + + * Trigger : Data is added to the message in the message queue on every checkin. + * Available data : <> (replaces <> as used in CHECKOUT and RENEWAL) + +=item TRANSFERSLIP + + * Source file : C4/Circulation.pm + * Trigger : Prints when transfer is sent, except if hold captured. + * Detail syntax : No repeating detail. + * Available data : <>, <>, <> + * Message transports : Set as 'email'. + +=item ISSUESLIP + + * Source file : C4/Members.pm + * Trigger : Printed from circulation screen. + * Detail syntax : + + + * Message transports : Set as 'email'. + + and will expand <>, <>, <> + will expand <>, as populated by C4::NewsChannels::GetNewsToDisplay() + +=item ISSUEQSLIP + + * Source file : C4/Members.pm + * Trigger : Printed from circulation screen. + * Detail syntax : + + * Message transports : Set as 'email'. + + will expand <>, <>, <> + +=item AR_SLIP + + * Source file : circ/article-request-slip.pl + * Trigger : ? + * Detail syntax : No repeating detail. + * Available data : <>, <>, <>, <>, + <>, <> + +=item AR_Processing + + * Source file : Koha/ArticleRequest.pm + * Trigger : ? + * Detail syntax : No repeating detail. + * Available data : <>, <>, <>, <>, + <>, <> +=item AR_Completed + +Same as AR_Processing + +=item AR_Canceled + +Same as AR_Processing + +=item AR_Pending + +Same as AR_Processing + +=item OVERDUE + + * Source file : misc/cronjobs/thirdparty/TalkingTech_itiva_outbound.pl + * Trigger : Uses overdue trigger + * Detail syntax : No repeating detail. + * Available data : <>, <>, <> + * Message transports : Phone only + +=item PREOVERDUE + +Same as OVERDUE + +=item RESERVE + +Same as OVERDUE + +=back + +=head2 Holds + +=over + +=item HOLD + + * Source file : C4/Reserves.pm + * Trigger : Triggered by filled hold + * Detail syntax : No repeating detail. + * Available data : <>, <> (linked by reserves.branchcode), + <> (linked by reserves.borrowernumber), + <> (linked by reserves.biblionumber) and + <> (linked by items.itemnumber) + +The letter code for trapped/filled/available holds defaults to HOLD, however any notice with the name +'Hold_Filled' may fill this role. + +=item HOLDPLACED + + * Source file : C4/Reserves.pm + * Trigger : Triggered by placed hold + * Detail syntax : No repeating detail + * Available data : <> + (as populated by C4::Branch::GetBranchDetail($borrower->{branchcode}), + <>, <> and <> will be expanded for the + item placed on hold. Note that <> will not be populated for + 'next-available' (i.e. bib-level) holds. + +=item HOLD_SLIP + + * Source file : C4/Reserves.pm + * Trigger : Triggered by placed hold + * Detail syntax : No repeating detail. + * Available data : See HOLD + * Message transports : Set as 'email'. + + +=back + +=head2 Suggestions + +=over + +=item ASKED + + * Source file : C4/Suggestions.pm + * Trigger : ? + * Detail syntax : No repeating detail. + * Available data : <>, <>, <>, <> + +=item CHECKED + + + * Source file : C4/Suggestions.pm + * Trigger : ? + * Detail syntax : No repeating detail. + * Available data : <>, <>, <>, <> + +=item ACCEPTED + + * Source file : C4/Suggestions.pm + * Trigger : ? + * Detail syntax : No repeating detail. + * Available data : <>, <>, <>, <> + +=item REJECTED + + * Source file : C4/Suggestions.pm + * Trigger : ? + * Detail syntax : No repeating detail. + * Available data : <>, <>, <>, <> + +=item TO_PROCESS + + * Source file : misc/cronjobs/notice_unprocessed_suggestions.pl + * Trigger : ? + * Detail syntax : No repeating detail. + * Available data : <>, <>, <> + +=back + +=head2 Patrons + +=over + +=item OPAC_REG_VERIFY + + * Source file : opac/opac-memberentry.pl + * Trigger : Triggered by patron self registration + * Detail syntax : No repeating detail + * Available data : <>, <> + +=item SHARE_INVITE + + * Source file : opac/opac-shareshelf.pl + * Trigger : Triggered by list share + * Detail syntax : No repeating detail + * Available data : <>, <>, <> + +=item SHARE_ACCEPT + + * Source file : opac/opac-shareshelf.pl + * Trigger : Triggered by patron accepting list. + * Detail syntax : No repeating detail + * Available data : <>, <> + +=item ACCTDETAILS + + * Source file : members/memberentry.pl + * Trigger : Triggered by account creation. + * Detail syntax : No repeating detail. + * Available data : ? + + +=item MEMBERSHIP_EXPIRY + + * Source file : misc/cronjobs/membership_expiry.pl + * Trigger : Triggered by account expiration. + * Detail syntax : No repeating detail. + * Available data : <> and <> are available in the notice. + +=item DISCHARGE + + * Source file : Koha/Patron/Discharge.pm + * Trigger : ? + * Detail syntax : No repeating detail. + * Available data : <>, <> + +=item PASSWORD_RESET + + * Source file : Koha/Patron/Password/Recovery.pm + * Trigger : ? + * Detail syntax : No repeating detail. + * Available data : <> => $uuidLink, <> => $borrower->userid + +=back + +=head2 Other modules + +=over + +=item ACQ_NOTIF_ON_RECEIV + + * Source file : C4/Acquisition.pm + * Trigger : Triggered by acquisitions receipt of watched item. + * Detail syntax : No repeating detail. + * Available data : <>, <>, <>, <> + +=item CLAIMSERIAL + + * Source file : serials/claims.pl + * Trigger : ? + * Detail syntax : As far as I can tell, lines containing <>, <>, + <> or <> will be repeated for + each selected serialid. + * Available data : <>, <>, <>, <>, + <>. + +Letter code is chosen via a drop-down on serials/claims.pl, all letters having the module +'claimissues' will show in the selection list. + +=back -- 2.1.4