Notices in Koha
Notices are a powerful way to communicate with patrons about their checked-out materials, holds, renewals, etc. Koha has many options for customizing the notices and customizing how they are delivered, both through settings configuration and through the powerful tool of Template Toolkit to enable libraries to design dynamic, flexible notice templates for different situations.
Customizing Overdue Notice Delivery
Many libraries seek a fair amount of flexibility in how their various notices are delivered. Some patrons like an email, some prefer a text message, and sometimes we need to send an actual piece of paper through the mail. With the enhanced messaging notices (notice of hold filled, advanced notice of item due, and so on -- what I like to call "the nice notices"), we can pick a delivery method per patron, allowing us to pick whether to email or text.
But overdue notices are a lot less flexible. We define timing and delivery method for an entire patron category and they all get notices the same way. On the one hand, this makes sense. We don't want to give anyone the ability to opt out of overdue notice -- we want our overdue items back! But this inflexibility can certainly lead to frustrations.
One thing that often comes up when talking to new libraries is the behavior described in Bug 20475: if we set a patron category to receive both email and SMS overdue notices, they will receive both. There's no way within the Overdue Notice & Status Triggers to say "Send a text, but if they don't have a text number send an email instead." Furthermore, both the email and SMS notices will generate a print notice if they fail. So if I have my patron category set to receive their overdue notice through both email and SMS and my patron has an email address but no SMS number they'll get an email and a print notice. Generally, libraries end up having to strike a compromise here, and that's never my first choice.
But here's the good news about working with new libraries: they ask new questions about issues I've become accustomed to dealing with! On a recent call, I explained this situation to a couple of librarians and they asked "Could we check to see whether the patron has an email address or an SMS number and only make a print notice is they don't have either?" We can do that, with the magic of Template Toolkit!
Template Toolkit
Template Toolkit (or TT) is a relatively new thing in Koha notices, though it's been around long enough that you've probably heard it mentioned here and there. It exists in a sort of hazy space between a markup language and a programming language and I can't pretend to fully understand it (that's what we have developers for). In Koha's notices, the community is moving toward using TT to replace the old "hungry alligator" tags for marking where item and patron data should be inserted into a notice. We've got a lot of ground to cover about Template Toolkit in future posts, but for now I'm going to keep things focused. If you want to read more, you might check out the Koha wiki pages on Notices With Template Toolkit, Template Toolkit Plugins, and Template Toolkit Translation Tools. Or you could dive right into the official Template Toolkit documentation.
As I mentioned, TT is still relatively new to notices and we're still finding interesting new ways to use it. Here's one possibility.
Establishing a Delivery Method Priority
As I mentioned, telling Koha we want overdue notice to go out via email and SMS means our patrons will get both and Koha doesn't have a way to say "Only send an email if the patron doesn't have an SMS number." But with TT we can insert that logic right into the notice!
Assume an SMS notice is our first choice, if that fails we want to send an email, and if we can't send an email we want a print notice. First, we set up our triggers as they are in the screenshot above, checking the boxes for both SMS and Email. We don't need to check the Print box. From there, we need to head over to the Notices page and edit the scripts of our various notices.
We don't need to do anything to the SMS notice. It will send if the patron has an SMS number entered. If they don't have an SMS number, Koha will try to generate a print notice.
At the same time Koha tries to generate an SMS notice, it will try to generate an email notice. This is the first place we need to deploy some template toolkit. The following would go into your email notice:
[% IF borrower.smsalertnumber == NULL || borrower.smsalertnumber == "" %]**CONTENT OF NOTICE**[% ELSE %][% END %]
This code says "If this borrower doesn't have an SMS number, make this notice. Otherwise, the notice is blank." So if our patron has an SMS number and therefore received an SMS number, their email notice is blank and Koha is smart enough to just not make a notice at all if it would be blank. Here's that code in context of the full notice:
So, at this point the SMS notice will send if the patron has an SMS number and the email notice will send if the patron has an email address but does not have an SMS number. If either SMS or email does not generate, Koha will generate a print notice. We want to change that behavior to only generate a print notice if both the SMS and email do not generate. For that, we need some TT language in the print notice:
[% IF (borrower.email == NULL && borrower.smsalertnumber == NULL) || (borrower.email == "" && borrower.smsalertnumber == "") || (borrower.email == "" && borrower.smsalertnumber == NULL) || (borrower.email == NULL && borrower.smsalertnumber == "") %]**CONTENT OF NOTICE**[% ELSE %][% END %]
This code looks a bit more complicated than what we put in the email message, but is essentially the same time. It says "If this borrower doesn't have an SMS number or an email address, make this notice. Otherwise, the notice is blank." Just as with the email notice, if our code results in a blank notice, Koha won't make the notice at all and the patron won't end up with a print notice.
Here's that code combined with a full notice:
And that completes our delivery method hierarchy! Koha will send an SMS notice if possible, an email notice if the SMS fails, or a print notice if the email and SMS both fail.
Should you prefer to try email first SMS second, just ignore the code I posted above for the email notice and add something comparable to the SMS notice:
[% IF borrower.email == NULL || borrower.email == "" %]
**CONTENT OF NOTICE**
[% ELSE %][% END %]
This says "If this borrower doesn't have an email addres, make this notice. Otherwise, the notice is blank." The print notice uses the same code I posted above.
I'm very excited about this work! It's a clean and easy solution for a problem that's come up for many of the libraries I've trained. It's also something many librarians will be more comfortable submitting a ticket for rather than tackling themselves, and that's great, we're happy to help!
Overdue Notice Cron Job Options
The Overdue Notice cron uses the Overdue Notice Status and Triggers set up (found in the Tools Module) to determine which patron categories, how many days overdue and which notice to prepare to be sent to the patron. The cron job also allows some preferences to be set separately from this tool if necessary. Some of the options found below will be useful if the Overdue Notice Status and Trigger tool is not used, such as the patron category and number of days.
Overdue Notice Cron using Triggers
By default, the Overdue Notice cron will be run without any conditions except for ‘-t,’ which tells the cron to use the triggers set up in tools. That will look like this:
$KOHA_CRON_PATH/overdue_notices.pl -t
This will process all libraries individually looking at the Overdue Notice Status and Triggers. Notices are prepared for all the patrons with overdue items for whom have email addresses. If a patron does not have an email address, the overdue notices will be sent in a single attachment to the library’s administrator email or to the address in the KohaAdminEmailAddress system preference.
In the case where patrons don’t have emails and Koha is emailing the overdue notices to the library, the library can choose what type of file they receive from the cron. The default is HTML, however, this attachment of notices can also be sent in a .txt or .csv format.
As with most areas in Koha, this can be changed and customized per the needs of the library. The cron as explained above is just one method and like most of Koha’s crons, there are different options that can be applied.
Overdue Notice Cron Options
These options include:
Choosing a specific branchcode or multiple branchcodes to process the overdue, which means a library can leave out other branches if necessary. For example to run the cron for only the East and West branches (branch codes “E” and “W”, your cron file would say:
$KOHA_CRON_PATH/overdue_notices.pl -t -library E -library W
Choosing to prepare or not prepare overdues for a specific patron category. This cron can be run outside of the Overdue Notice Status and Triggers and therefore this option would be used in that context. For example, to run the cron and exclude a specific category code such as ILL, your cron file would say:
$KOHA_CRON_PATH/overdue_notices.pl -t -borcatout ILL
Choosing what item information is included in the overdue notice. A library can choose to use the standard <<items.content>> in the notice, however, may want to alter what is included in the statement. By default, <<items.content>> includes due date, barcode, title, author. For example, if your library wanted to alter the <<items.content>> to only include duedate and title, your cron file would say:
$KOHA_CRON_PATH/overdue_notices.pl -t -itemscontent duedate, title
Koha can prepare the overdue notices by what is triggered by the Overdue Notice Status and Triggers OR it can prepare overdue notices looking for items with a max number of days in the statement instead. If a library wanted to run overdue notices not using the Triggers set up but instead wanted to run and capture all overdues for the last 90 days. This cron file would say:
$KOHA_CRON_PATH/overdue_notice.pl -max 90
Choosing which email to use in the borrowers schema. Libraries can have stored multiple email addresses for a patron, and this portion of the cron can tell Koha which email to use.
$KOHA_CRON_PATH/overdue_notice.pl -email emailpro
Crons in Koha can be run without really sending the emails; there are two options in the cron that this can happen. The cron can be run in test mode (adding - test to the cron line), which will make no changes to the database and/ or it can be run without actually sending the emails. Running it without sending emails (but still applying restrictions if specified in your triggers):
$KOHA_CRON_PATH/Overdue_notices.pl -n
Send notices using Multiple email addresses
Koha allows staff to send notices using several email addresses with system preference EmailFieldSelection. This system preference allows libraries to select a list of email address fields to use when sending notices to patrons. The system preference, EmailFieldSelection provides a checklist of address fields that are then used for the notices when the system preference EmailFieldPrimary is set to selected addresses.
System Preferences
The first system preference you will need to set is EmailFieldPrimary.
This preference will ask: Use the patron’s ___ for sending out email notices. You have the following options to select.
- alternate email
- cardnumber
- primary email
- secondary email
- selected addresses
- first valid email address
When selected addresses is selected, staff can define the email address fields in EmailFieldSelection.
The second system preference is EmailFieldSelection.
This system preference allows sending notices to multiple email addresses at once, rather than having to choose one field. You can select or multi select the values below.
- [Select all]
- alternate email
- primary email
- secondary email
Translating Notices
Notices in Koha can be translated into different languages. There is a 'preferred language' setting available in the patron user account, that controls which template will be used when generating notices.
System Preferences
StaffInterfaceLanguages: Enable the following languages on the staff interface (make sure you have installed the language packs you want to have available).
OPACLanguages: Enable the following languages on the OPAC (make sure you have installed the language packs you want to have available).
opaclanguagesdisplay: This allows patrons to select their preferred language.
TranslateNotices: when set to allow, notices to be translated. If set, notices will be translatable from the “Notices and Slips” interface. The language used to send a notice to a patron will be the one defined for the patron.
Notices and Slips
Go to Tools > Notices and Slips
Select the notice you want to edit. Now you will see multiple tabs after Default. The system preference TranslateNotices (listed above) will add tabs for each installed language to the notices editor.
The notice defined in the ‘Default’ tab will be used if there is no preferred language set for a patron.
Patron Account
A patron account will have a dropdown menu under Library Management for Preferred language for notices. This will allow you to set the preferred language for your patron.
Patrons can also adjust their preferred language in the OPAC once this is set.
Creating Customizable Notices with Reports
The first step is to go to Tools > Notices. From there, create a new notice and select "Report" for the module. Create the notice in the Print tab.
Reports
The report that is created will feed the information into the notice that has been created. So a report would be an information gathering tool to assist the notice in what will be presented. Once the notice has been created - there will be a new option within the Report choices, allowing a library to choose to run this report using the Template (the notice). In addition, a new option has been added to the download button allowing this report notice combo to be downloaded. This download option will only appear once the Report has been run using the template.
- Create the Notice (using the Reports option)
- Create the Report
- Run the report
- Run using the Template (title will be what was used in the notice)
- Download "Rendered Template.
Overdue Example
Lucas shared some examples during the MM video. The first one was an ability to run Overdues and print them out directly from this report.
Here is the notice he created:
Here is the report he created to work with this notice:
Lucas's overdue example was not the Koha default ODUE which altered the way it looked during our tutorial! The attached PDF has the ODUE notice template.
Order Slip Example
Lucas added some JQuery to the system preference: intranetuserJS. This will display a button that staff can print the report directly from the basket. This code is also included in the PDF document attached at the bottom of the page.
Here is the notice he created:
Here is the report he created to put it all together!
Messaging Preferences in the OPAC
Every library can and probably does send emails, text messages and possibly snail mail to their users! Have you ever received an email telling you that a book you placed on hold was ready to pick up? Or that an item you checked out was due in a few days? Libraries know that patrons get a lot of emails, snail mail and even too many text messages these days so they can give their library patrons the opportunity to add and remove specific messages that they are receiving from the library.
Changing the Messaging Preferences
For a patron to change their messaging preferences, they will need to log into their Public Catalog. Once they are logged in, on the far left of the screen, there is a tab called Your Messaging. Clicking this tab, will present the patron the ability to see the messages that the library sends and also the ability to adjust these messages.
Messaging Options
Item Due - this is a message that will be sent the day the item/s are due.
Advance Due - this is a message that will be sent x number of days before the item/s are due. The patron may choose the number of days in advance they would like to receive this message.
Holds - this is a message that will be sent when an item that was placed on hold by the patron is ready to be picked up at the library.
Item Checkin - this is a message that will be sent to show everything that was checked in.
Item Checkout - this is a message that will be sent to show everything that was checked out.
There are check-mark boxes that can used to determine which messages the patron would / would not like to receive. A do not notify box is listed on each message option that can also be checked if the patron would like no notifications.
SMS Messaging
At the bottom of this page, there may also be the ability to add your cell phone number and cell carrier to also receive SMS messages. This is a column option on the messaging chart also and will only be seen if the library is using this feature.
If your library does have this feature, please choose which carrier you are using in addition to your cell phone number -- without the carrier information, the message will not be sent.
Video Tutorial
Can Notice Timing Be Adjusted?
Yes! Many libraries schedule their notices to go out during particular hours. Many of the daily automated functions, like automatic renewal or sending overdue notices and other courtesy reminders, happen overnight in the early hours, so libraries that send SMS notices in particular do not want messages going out as soon as automated actions have triggered notices.
Why Have Email to SMS Notices Become Unreliable?
Koha's built-in option to send SMS notices via email gateway has become less reliable over time as providers like T-Mobile and Verizon have started removing access to the ability for anyone to send email to SMS numbers for free. Most libraries are moving towards using a 3rd party service for this functionality, and in our experience, it has been much more reliable to utilize a product intended for that purpose. Libraries are generally happier with the outcomes, with the small increase in cost more than made up for by more reliable SMS messaging.
We are recommending that partners look into a dedicated SMS messaging service like Twilio, RedOxygen, Shoutbomb, or Patron Point, to name a few, rather than using Koha’s built-in SMS feature. As always, feel free to reach out to our partner mailing list or ByWater partner Slack community to trade recommendations with other partner libraries.
In order to provide a quote, third-party services like this will often ask how many messages a library currently sends out, so here is a report to help identify that:
select count(*), status
from message_queue
where message_transport_type='sms' and date(time_queued) between
<<Between|date>> and <<and|date>>
group by status
Suppressing SMS Transport of Specific Notices in Koha
One area in which notice customizability is more limited is the lack of granular control over which essential notices can be sent by SMS. SMS can be disabled entirely, and the SMS templates for nonessential notices can simply be deleted, but Koha does not currently offer a way to enable SMS messaging for some essential notices but not others.
This is where Template Toolkit can come to the rescue! With Template Toolkit, we can edit specific notice templates as a workaround to suppress SMS messaging on those notices, even if the notice template can’t be deleted. To do this, simply edit the SMS notice template for the notice you want to suppress, and enclose all of the notice text between the following pair of Template Toolkit tags:
[% IF 0 %]
[% END %]
For example, the SMS Check-in message:
The following items have been checked in:
----
[% biblio.title %]
----
Thank you.
Would become this:
[% IF 0 %]
The following items have been checked in:
----
[% biblio.title %]
----
Thank you.
[% END %]
If adding these tags causes the notice to exceed the 160 character limit, you may need to delete some text from the notice body. Make sure you save a copy of the original notice in case you ever want to enable that notice again in the future!
This would work for suppressing email delivery of a certain notice, too, if you add these tags to the Email notice template instead of the SMS notice template.
Why does this work? It’s all because of the way the IF tag behaves. Normally, the IF tag would tell Koha to include certain information in the notice, but only if a certain condition is true. For example, you could use [% IF borrower.categorycode == STAFF %] to add extra information to a notice, but only if it is being sent to a staff account. In Template Toolkit, 0 is the same as “false”, so [% IF 0 %] will never be true, and the enclosed text will never be included. This leaves a blank notice, so Koha won’t attempt to send it at all.
The downside with this method is that library patrons won’t necessarily know that a certain notice type is disabled. If the library allows patrons to customize their own notification settings, Koha won’t prevent or warn patrons if they sign up for a notice that has been suppressed in this way, so it will be up to the library to communicate to patrons that this type of notice will not be sent. In the long term, it would be even better if Koha could add configuration features to control the enabled messaging types for different notices at the library or system level. But in the meantime, this workaround can give libraries one more option for customizing their notices in a way they couldn’t do otherwise!
Related Articles
Twilio Integration with Koha
Some of our partners subscribe to Twilio for SMS messages and phone notifications from Koha. If you are a ByWater Solutions partner and have a Twilio account, we can help you set up the connection. Twilio SMS Twilio sends the SMS notices that Koha ...Patron Point and Koha - Library Setup
How does it work? Patron Point can send email, SMS, and/or phone messages. Similar to SIP users, an API patron/user allows third party integrations such as Patron Point to connect to Koha. The API patron will have permissions that allow it to ...Koha Glossary of Terms
Find the basics of Koha's vocabulary here This glossary is in alphabetical order. Use control+F to quickly search this page for specific terms. Authority Record: allows your library to control and search fields in your MARC records such as subject ...Add Cost Savings to the Patron's Slip
A library can add a note to a patron checkout receipt that tells them how much they saved by using their library. Editing a Notice Go to the Staff Interface >Tools > Notices & Slips. Locate the ISSUESLIP or ISSUEQSLIP (or both). Although these ...Koha Marketing Resources
Is your library getting ready to go live with Koha's OPAC? Here you will find templates and logos to get the process started. Logos Download Koha logos to customize your branding and messages for your community of library users! Koha Logo Files - ...