Customising Notices and Slips

From Koha Wiki
Jump to navigation Jump to search

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.
 <p style='font-family:Arial,Helvetica,Serif; color:white;'> Formatted Text here!</p>
  • 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. 
 <br /><<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.
Retrieved from "https://wiki.koha-community.org/w/index.php?title=Customising_Notices_and_Slips&oldid=33275"