by Andrew Fuerste-Henry on Sep 15, 2021
Koha version 20.11 included an exciting pair of enhancements around the cancellation of holds. Bug 25534 teaches Koha to record why a hold was cancelled and to send an email to your patron to let them know about that cancellation. Bug 12656 adds the ability to use that reason and email when holds are cancelled automatically by the system based on their expiration date.
Record a reason
As part of the 20.11 upgrade, a new authorized value category of "HOLD_CANCELLATION" will be created on your system.
To find these values, go to Administration, then click Authorized Values. Use the search box on this page to find "HOLD_CANCELLATION." There are only two possible reasons by default. To add more, click "New authorized value for HOLD_CANCELLATION."
As with any authorized value, you'll want to put a code value in the "Authorized value" field and a display value in the "Description" field. Your code should be something short, clear, and devoid of special characters. It's a good idea to stick to capital letters and underscores for your code. You don't need to fill out the "Description (OPAC)" field unless you want a different display value for the public catalog than you show on the staff site.
As with any authorized value, you can always delete values you don't use, add new values as needed, and change the descriptions freely.
If the authorized value category "HOLD_CANCELLATION" exists on your system and has at least one option configured, you'll be given the option to select a reason when you cancel a hold. The interface will vary slightly based on where you're performing the cancellation.
The reason you select here will be recorded in the old_reserves table and can be accessed via reports (old_reserves.cancellation_reason). Additionally, the reason will be shown in the patron's Holds History.
Send a notice
When a hold is cancelled and a reason is selected, Koha can send the patron an email. All you need to do to turn this feature on is create a notice with the letter code "HOLD_CANCELLATION." If this notice exists, Koha will generate an email each time a hold is cancelled with a reason. The notice will not be automatically created when your system is upgraded.
To create a new notice, go to Tools and then click Notices & Slips. On that page, click the "New notice" button and pick "Holds" out of the dropdown.
Give your new notice the code "HOLD_CANCELLATION" (just like the authorized value category). The notice name will only be shown to staff here in tools, so it can be whatever you like.
We also need to give this notice a subject line and some content for the Email version. Click the word "Email" to expand the form and add your values. You can check the "HTML message" box if you want to use HTML in your notice.
This notice uses Template Toolkit to pull values from the database (rather than the double angle brackets that other notices use). That complicates our notice content a little bit, but also gives us a lot of nice flexibility. Here's the example from my screenshot:
[% USE AuthorisedValues %] Dear [% borrower.firstname %] [% borrower.surname %], Your hold on [% biblio.title %] has been cancelled with the following reason: [% AuthorisedValues.GetByCode( 'HOLD_CANCELLATION', hold.cancellation_reason, 'IS_OPAC' ) %] [% IF hold.cancellation_reason == "DAMAGED" %] If our selectors choose to order a replacement copy of this title, we will place a new hold for you at that time. [% END %] Thank you, [% branch.branchname %] Staff
The section that starts with "IF" and runs through "END" is a very theoretical example how we can make the email different based on which reason was selected. In this case, I've included a sentence that only goes into the email if the "DAMAGED" reason was selected. For any other reason, those lines are skipped entirely.
There are not patron messaging preferences for this notice. If the notice exists and a reason for cancellation is given, Koha will generate an email. The email will generate even if the patron doesn't have an email address (though it will not be successfully sent in that case). This notice can only be sent via email; it cannot be sent via SMS.
Automatic cancellation
In the process outlined above, holds are being cancelled and a reason is being selected manually. In many cases, holds will actually be cancelled by the cancel_expired_holds cronjob, either because a suitable item was never found to fill the hold or because an item was captured but the patron never came to pick it up. If you're using the cancel_expired_holds cronjob, we can set it to apply one of your cancellation reasons to the holds it cancels. If a reason is applied and you've created a HOLD_CANCELLATION notice, emails will be generated for your patrons.
Disabling these features
After your upgrade, cancellation reasons will be enabled by default. If you don't wish to use cancellation reasons, simply go to authorized values, delete all of the default HOLD_CANCELLATION values, and then delete the HOLD_CANCELLATION category entirely. We're happy to do this for you if you like. We can always add the category back in to reenable this feature if desired.
The upgrade will not create a HOLD_CANCELLATION notice, so those emails won't be generated unless you create that notice manually (or ask us to do so). Should you later wish to disable those emails, we need only delete the notice.
Read more by Andrew Fuerste-Henry