Customising Notices and Slips

== Terminology ==
Substitutions:
The use of << and >> to denote something to be substituted or expanded, e.g.
 <<branches.branchname>> 
Is called a 'substitution'. The content of a substitution (in this case branches.branchname) is called a 'variable'.
Many notices have some way of printing information about several items. This is known as 'detail'. See Notice Specific Markup below for examples.
== Quick Tips for Custom HTML Notices/Slips ==
*Its best to use TABLE instead DIV when making HTML emails 
*Although Koha provides a mechanism to add CSS (using System Preferences) it is highly recommended that you use embedded CSS 
**e.g.
 Formatted Text here! 
*Mozilla Thunderbird works with external style-sheets perfectly (div tags work too) 
*Microsoft Office Outlook does not support many of the functions of DIV (and CSS for that matter) 
*You may need spaces both following and preceeding variables, this includes HTML markup e.g. 
 <<branches.branchname>> 
would not correctly expand <<branches.branchname>>.
== Differences between advance and overdue notices ==
Overdue notices are those that are sent after an item has passed it's due date. Advance notices are sent before or on the day that the item or items are due. Overdue and Advance notices fill similar functions, but are handled quite differently by Koha; confusing the two can give unexpected results.
Here's the way that the notices break down:
=== Advance notices ===
Generated by misc/cronjobs/advance_notices.pl
* Single item per notice
** DUE
** PREDUE
These may use the <<items.content>> notation, or fields may be specified from the items, issues or biblio tables.
I generally suggest using <<items.content>> for consistencey.
* Digest notice
** DUEDGST
** PREDUEDGST
These *must* use <<items.content>> for item detail.
=== Overdue notices ===
Generated by ./misc/cronjobs/overdue_notices.pl
* All overdue notices are in digest form -- there's no concept of a single item overdue notice.
* Overdue notices don't have a fixed letter code. By convention, they use ODUE, ODUE2, ODUE3, but they may use other letter codes, such as your ODUEDGST.
* The notices used for a given branch / patron category are specified in Home › Tools › Notice triggers.
* Overdue notices *may* use the <<items.content>> for item detail, or they can use opening and closing <item> </item> tags, eg.
 <item>
 - <<biblio.title>> (<<items.barcode>>), due <<issues.date_due>>
 </item>
=== Frequent Errors ===
The most frequent error is to try to expand <<items.*>>, <<biblio.*>> and <<issues.*>> inside DUEDGST or PREDUEDGST notices, either inside <item> </item> tags a-la overdue notices, or not, as would be the case with DUE or PREDUE notices.
== Message Transport Type for Slips ==
Most slips are generated based on the contents of the Email transport type rather than Print, even though these slips are not ever emailed. Wording and formatting defined under Print will have no effect on generated slips. To avoid confusion, it's best to avoid putting anything under Print on slips that generate based on Email.
These slips are generated based on the Email transport type:
* HOLD_SLIP
* ISSUEQSLIP
* ISSUESLIP
* TRANSFERSLIP
* SR_SLIP
See Bug 19036: 'email' templates used for printing slips.
These slips are generated based on the Print transport type:
* OVERDUES_SLIP
* AR_SLIP
== Notice Markup ==
=== Syntax available on all notices ===
<<today>> may be used in any notice, and will be replaced by the date when the notice is generated. It follows the dateformat and TimeFormat system preferences.
Adding the dateonly filter, will show the date only, without the time part of your selected column. Example: << biblio.timestamp | dateonly >>
Borrower Attributes will be expanded using
<<borrower-attribute:ATTRIBUTE>>
=== Notice Specific Markup ===
In the table below, Detail syntax specifies the format used to display multiple objects such as items due, for instance <<items.content>> in advance_notices.pl or the <item> </item> tags used for overdue notices.
Letter code 	Used in 	Detail syntax 	Accessible data
DUE 	advance_notices.pl 	<<items.content>> 	<<items.content>> is replaced in is entirety by the fields due date,title, author,barcode. Specified using --itemscontent option to advance_notices.pl Any column from biblios, items and issues tables may be used in --itemscontent. Other information: 
 <count> : number of items due. <branch.*> : rows from the branches table pertaining to the branch sending the notice
DUEDGST 	advance_notices.pl 	<<items.content>> 	Same as DUE
PREDUE 	advance_notices.pl 	<<items.content>> 	Same as DUE
PREDUEDGST 	advance_notices.pl 	<<items.content>> 	Same as DUE
ODUE* 	overdue_notices.pl 	<<items.content>> or <item> </item> 	<<items.content>> Works identically to <<items.content>> in advance_notices.pl. <item> and </item> tags will expand fields from the following tables: 
items 
bibio 
biblioitems 
issues 
<item> items.barcode </item> will show the overdue item's barcode. Multiple fields may be expanded inside a single pair of tags. There is a special tag <<items.fine>> which is only available in within the <item> tag, which expands to the fine on the overdue item.
CHECKOUT 	C4/Circulation.pm 	Notices in C4/Circulation.pm use four dashes before and after the detail section:
 ----
 Detail here
 ----
This is implemented in C4::Message. At this point, only C4/Circulation.pm uses C4::Message, if any other letters are ever enqueued using C4::Message->enqueue(), they will have this syntax available.	
<<items.*>> <<biblio.*>> <<biblioitems.*>> <<borrowers.*>> <<branches.*>>
<<issues.*>> (for CHECKOUT and RENEWAL)
RENEWAL 	C4/Circulation.pm 	See CHECKOUT 	See CHECKOUT
CHECKIN 	C4/Circulation.pm 	See CHECKOUT. 
Include
 ----
 ----
to prevent message from repeating in SMS. Example:
 You have returned items at the library
 ----
 ----
Will send just one SMS message.	See CHECKOUT,
but CHECKIN uses <<old_issues.*>> instead of <<issues.*>>
TRANSFERSLIP 	C4/Circulation.pm 	No Repeating detail/ 	<<branches>>, <<biblio>>, <<items>>
ISSUESLIP 	C4/Members.pm 	<checkedout> </checkedout> 
<overdue> </overdue> 
<news> </news> 	<checkedout> and <overdue> will expand <<biblio.*>>, <<items.*>>, <<issues.*>> . 
<news> will expand <<opac_news.*>>, as populated by C4::NewsChannels::GetNewsToDisplay()
ISSUEQSLIP 	C4/Members.pm 	<checkedout> </checkedout> 	<checkedout> will expand <<biblio.*>>, <<items.*>>, <<issues.*>>
HOLD ** 	C4/Reserves.pm 	No repeating detail. 	<<reserves.*>>, <<branches.*>> (linked by reserves.branchcode), <<borrowers.*>> (linked by reserves.borrowernumber), <<biblio.*>> (linked by reserves.biblionumber) and <<items.*>> (linked by items.itemnumber) are all available.
HOLDPLACED 	C4/Reserves.pm 	No repeating detail 	<<branches.*>> (as populated by C4::Branch::GetBranchDetail($borrower->{branchcode}), <<borrowers.*>>, <<biblio.*>> and <<items.*>> will be expanded for the item placed on hold. Note that <<items.*>> will not be populated for 'next-available' holds.
HOLD_SLIP(AKA RESERVESLIP)	C4/Reserves.pm 	No repeating detail. 	See HOLD
ASKED 	C4/Suggestions.pm 	No repeating detail. 	<<branches>>, <<borrowers>>, <<suggestions>>, <<biblio>>
CHECKED 	C4/Suggestions.pm 	No repeating detail. 	See ASKED
ACCEPTED 	C4/Suggestions.pm 	No repeating detail. 	See ASKED
REJECTED 	C4/Suggestions.pm 	No repeating detail. 	See ASKED
OPAC_REG_VERIFY 	opac/opac-memberentry.pl 	No repeating detail 	<<OPACBaseURL>>, <<borrower_modifications.verification_token>>
SHARE_INVITE 	opac/opac-shareshelf.pl 	No repeating detail 	<<borrowers.*>>, <<listname>>, <<shareurl>>
SHARE_ACCEPT 	opac/opac-shareshelf.pl 	No repeating detail 	<<borrowers.*>>, <<listname>>
? 	C4/Serials.pm 	No repeating detail. 	Implemented via SendAlerts
? 	acqui/lateorders.pl 	No repeating detail. 	Implemented via SendAlerts
ACCTDETAILS 	members/memberentry.pl 	No repeating detail. 	Implemented via SendAlerts
CLAIMSERIAL 	serials/claims.pl 	As far as I can tell, lines containing <<serial.*>>, <<subscription.*>>, <<biblio.*>> or <<aqbooksellers.*>> will be repeated for each selected serialid.	Implemented via SendAlerts. Letter code is chosen via a drop-down on serials/claims.pl, all letters having the module 'claimissues' will show in the selection list. Available tables are <<serial.*>>, <<subscription.*>>, <<branches.*>>, <<aqbooksellers.*>>, <<aqcontacts.*>>.
MEMBERSHIP_EXPIRY 	misc/cronjobs/membership_expiry.pl 	N/A 	<<borrowers.*>> and <<branches.*>> are available in the notice.
ACQ_NOTIF_ON_RECEIV 	C4/Acquisition.pm 	N/A 	
<<branches.*>>
<<borrowers.*>>
<<biblio.*>>
<<aqorders.*>>
OVERDUES_SLIP 	members/print_overdues.pl 	N/A 	Uses the same syntax as ODUE
DISCHARGE 	Koha/Patron/Discharge.pm 	N/A 	<<borrowers.*>>
<<branches.*>>
PASSWORD_RESET 	Koha/Patron/Password/Recovery.pm 	N/A 	<<passwordreseturl>> => $uuidLink
<<user>> => $borrower->userid
AR_SLIP 	circ/article-request-slip.pl 	N/A 	<<article_requests.*>>
<<borrowers.*>>
<<biblio.*>>
<<biblioitems.*>>
<<items.*>>
<<branches.*>>
AR_Processing
AR_Completed
AR_Canceled
AR_Pending	Koha/ArticleRequest.pm 	N/A 	<<article_requests.*>>
<<borrowers.*>>
<<biblio.*>>
<<biblioitems.*>>
<<items.*>>
<<branches.*>>
TO_PROCESS 	misc/cronjobs/notice_unprocessed_suggestions.pl 	N/A 	<<suggestions.*>>
<<branches.*>>
<<borrowers.*>>
OVERDUE
PREOVERDUE
RESERVE	misc/cronjobs/thirdparty/TalkingTech_itiva_outbound.pl	N/A 	<<borrowers.*>>
<<biblio.*>>
<<biblioitems.*>>
* The letter code for overdue notices may change, based on the values set in the Overdue notice triggers.
** The letter code for trapped/filled/available holds defaults to HOLD, however any notice with the name 'Hold_Filled' may fill this role.
=== How to Help ===
If you are comfortable reading Perl, please take a look at the Source code for notices in Koha. C4::Letters::GetPreparedLetter() is the entry point for the definition of a letter. Pay special attention to the hashref keys 'tables' and 'repeat'; these are used to define the 'Detail Syntax' in the chart above. If you see a question mark in the 'Accessible data' column, please take a look at the code, and fill in the 'Detail syntax' and 'Accessible data' colums.
In Koha 3.14, message transport types were added to Koha. I don't know at this point whether all message transport types are available across all letter codes. 
As of 3.16, all notices should be available to all libraries, or may be branch specific. Likewise, all notices should respect the HTML flag. If you find an exception, please file a bug report.
If you are a developer working on notices, be aware that the notices sent by Koha are one of the most publicly visible parts of Koha. Please make sure that all changes to this code are well documented, and that the Koha documentation team has a clear idea of what has changed.
Please use the documentation for ISSUESLIP as a guide for documenting all other notices.
Finally, if you are familiar with editing the wiki, please take the time to make this page work better -- it needs formatting help.
=== Related pages ===
Notices and Slips Library
=== TODO ===
* Fill in '?' fields.
* The table probably needs another column -- how to trigger the notice or slip.
Category:Tips_&_Tricks
Category:Notices and slips