Koha How-To

When Two Notices Is Too Many

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:

[% 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 == "" %]
[% 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!