Email checkout slips RFC

RFC: Email checkout slips

A LibLime customer wants to be able to send emails or SMS messages to a patron whenever the patron checks out or returns an item.

The proposed feature would include the following elements

• A patron will be able to control when and how to receive checkout and return alerts via the OPAC patron profile interface.
• The library will be able to specify which patron categories and items are eligible for these notices.
• Emailed notices will try to group together all of the items loaned or returned during a single session.

This will build upon the existing C4::Letters infrastructure.

Details for the Email checkout slips RFC

Initial author: Daniel Sweeney (daniel dot sweeney at liblime dot com)

Overview

This specification adds a new feature to Koha that sends a list of items to patrons when several events take place:

1. When a patron borrows an item from the library.
2. When a patron returns an item to the library.

Patrons will be able to choose how the alerts are delivered, and to opt out of the checkout and return notices individually as part of maintaining their patron record.

Administrators will be able to define which patrons are alerted by patron category, and which item types will be allowed in the alert. Each branch will be able to set its own policies for notifications.

The concept is that these notices are sent electronically—by email or SMS. It will likely be overkill to send a notice by postal mail for every checkout and return.

Koha will attempt to group together multiple items into a single message if a patron charges or returns multiple items during a single session, while still trying to deliver the message relatively quickly.

Pre-Existing Functionality

Koha includes a configurable notice system in the “Tools” area, so it’s possible for the library to add a new notice type that will be sent to patrons at any time. The notice can include a variety of information about a patron’s charged items, as well as message text. Each notice form is identified by a code that can be up to 10 letters long. The actual notice templates are stored in the ‘letters’ table.

Koha includes notice and status triggers—these are established branch-by-branch, with and are driven by overdue status on items. The queued notifications are stored in the ‘notifys’ table. These are not really relevant to this project.

Koha also includes letters and alerts, stored in the ‘letters’ and ‘alerts’ tables. Alerts are used for things like serial issue and virtual shelf alerts. We could extend this system with new alerts for item checkout and return.

Requirements / Description

New types of alert

Koha will have the following new types of alert:

1. Items Borrowed Alert. This alert will indicate that items are newly borrowed.
2. Items Returned Alert. This alert will indicate that items were returned to the library.

System Administration of alerts

1. Administrators will have to configure the system’s delivery mechanisms.
   1. This will take place in the Administration area, under a new workspace called “Delivery Mechanisms.”
   2. Administrators will be able to set up different delivery mechanisms for each branch. This may be necessary if branches must use different mail or SMS gateways.
   3. Administrators will be able to set up system-wide default delivery mechanisms for organizations that do not want to set up multiple delivery mechanisms per branch.
   4. Typically postal mail, email and possibly SMS will be available. For the two types of alert, item borrowed alert and item returned alert, administrators must determine which of the available delivery mechanisms are available. The main reason to do this is to ensure that postal mail is not one of the possibilities, but some libraries might want to guarantee that the notices are sent by email only, regardless of whether SMS is available. Also, if new delivery mechanisms are added in the future, some may be appropriate for this feature and some may not.
2. At the branch/patron category/item type level, whether to send item borrowed alerts.
3. At the branch/patron category/item type level, whether to send item returned alerts.
4. Administrators will have to create templates for each alert and for each delivery method. (In particular, the SMS template should be very brief.)

Patron alert choices in the public catalog

1. The patron record available in the public catalog will have two new choices. For both of these, only the delivery mechanisms that are permitted by administrators for the given alert will be available:
   1. “Items borrowed alert” followed by a list of the possible delivery mechanisms.
   2. “Items returned alert” followed by a list of the possible delivery mechanisms.
2. Since different branches may have different sets of delivery mechanisms available, the union of the available delivery mechanisms will appear here. This may be a little confusing if the branches are inconsistent in the mechanisms they support.
3. These choices will only be available if the patron’s patron category allows for items borrowed and items returned alerts for any item type.
4. The possible delivery mechanisms will include an option to not send the alerts at all (so even if there is only a single valid delivery mechanism, there will be two options—one of which will be to opt-out.)
5. Delivery mechanisms should not be available if the patron does not have the appropriate addressing to use them (for instance, email should not be available if the patron does not have an email address.) This may turn off notices completely for some patrons.
6. The delivery mechanisms will be chosen using checkboxes, rather than a drop-down menu. This will allow patrons to receive the same message using multiple delivery mechanisms at once. This may not be very convenient for both email and SMS, but it makes sense for some delivery mechanisms to be redundant. (In particular if we add RSS to the system in the future, it makes sense to provide an RSS feed alongside the other mechanisms.)
7. In a multi-branch environment, the patron’s choices will apply across all branches. It’s possible that a patron may choose a delivery method that a particular branch does not support—in this case the messages will not be sent.

Patron alert choices in the staff modules.

1. Circulation staff will be able to set the delivery mechanisms for patrons just as patrons can. This will be part of a new panel in the patron edit form, under “Patron Account Flags.” The alert delivery choices will display on the patron display screen under the “Library Use” area.

Generating and delivering alerts

1. Alerts will be generated and delivered using a batch job running on the server either interactively or scheduled. This job will be scheduled to run fairly frequently—probably once an hour while the library is open.
2. For both kinds of alert, the alert will be queued to send if:
   1. The effective branch, the item type and the patron category are configured to send the alert,
   2. The effective branch is one of the patron’s home branch, the item’s home branch, or the circulation desk’s branch, depending on the global setting of the HomeOrHoldingsBranch parameter.
   3. The patron has the appropriate kind of address for the notice.
   4. The patron has decided to receive the notice.
3. The item borrowed alert will be triggered when a patron borrows an item.
4. The item borrowed alert will include bibliographic information for the item borrowed and the date the item is due.
5. The item returned alert will be triggered when the patron returns an item.
6. The item returned alert will contain bibliographic information for the returned item, whether or not the item was returned late, and any fines associated with the return.
7. If a patron charges or returns multiple items in one session, they should receive a consolidated alert message listing all items borrowed or returned. Since the job that sends the notices will run as a batch job, it should be able to read multiple entries out of a queue and process them together.
8. The job will use the appropriate template for the patron’s delivery method for the given alert.
9. Note that SMS messages are very limited in size—but the job will not be concerned with segmenting the messages. It is the responsibility of the SMS gateway or provider to segment the SMS messages appropriately. (The actual maximum size seems to vary by provider and according to other factors like the character set in the message.)
10. The messages will be generated and sent using UTF-8. This is the native character set in Koha.

Unsubscribe link

1. The templates will contain a link that points back to the patron’s account page, allowing the patron to unsubscribe from the email notices. This link will also have explanatory text indicating that patrons may use the link to unsubscribe or control their subscription options.
2. Since this link is part of the template, administrators may choose to remove it.

Security and Privileges

Since the actual messages are processed and sent using a batch job running on the server, and interacting directly with the database, there are no Koha-side privileges to add or check.

The “Delivery Mechanisms” area in Administration will be controlled using a single yes/no privilege—if administrators lack this privilege they will be unable to enter this area. That being said, since Delivery Mechanisms are branch-specific, administrator’s branch affiliations will also allow or prevent them from editing Delivery Mechanisms for specific branches.

Circulation staff may edit patron’s delivery mechanisms if they have sufficient privileges to edit the patron itself—there is no specific permission controlling the alert delivery mechanisms.

Open Questions and notes

Alerts and notices may be sent in several different ways—not just email. In particular libraries want to be able to add SMS messaging and RSS feeds.

This project adds a fair amount of infrastructure for delivery mechanisms—other alerts and notices should really be back-patched into this infrastructure. The big difference comes with RSS feeds—they work a little bit differently than emails or SMS because the client pulls them from the server, rather than the server pushing them out. RSS is such a key future feature that we need to be sure the infrastructure is set up to support them, possibly alongside a push-based messaging system.

There are really two approaches to the implementation of this feature—one is to store messages in a queue as they are generated and then process the queue; the other is to have a process that analyzes the contents of the transaction tables and generates a messages based on changes since a certain point. The first approach is simple, but does not lend itself well to pull-based reports like RSS feeds. Also, once the queue is processed, the information is lost—it’s not possible to run the job again if necessary. The second approach is more complicated but allows for recovery. Either or both approaches may be used in practice or for different jobs.

Alerts on returns may be gold-plating. It may be a good feature to remind patrons that they’ve got overdues, and also if they drop books in a book drop while the library is closed—the alert would tell them that someone actually checked the book in.

This project does not include a feature that sends a list of charged items to a patron on a schedule. This is a desirable enhancement, but doesn’t really mesh with this project because it is triggered on a schedule by the library, not by an event like a loan or return.

Running batch jobs on the server, or using cron, is straightforward for system administrators that control the server, but for installations that have limited access, for instance sites that are hosted at commercial web hosting providers, this may be a problem.

It’s a good idea to let patrons decide what types of alerts they receive at a more granular level than the yes/no flag above. For instance, patrons should really be able to decide whether they want alerts for items with particular item types. The problem is that patrons are unaware of the actual item types in the system, so it’s hard to present this information to them. One possible approach would be to map item types to “transaction types” based on the circulation policies in effect—any item types that have circ policies less than a day would be treated as “hourly loans” and any item types that have circ policies more than a day would be treated as “long-term loans.” Alternately, we could list out the possible circulation periods for all item types in the system and let patrons choose.

A more robust unsubscribe link might be a good idea—it’s a little tricky because there are actually several options the patron might want to edit, so it makes some sense to just direct them to the patron page.

In a multi-branch library, it’s easy to wind up with a lot of policy permutations. It’s unreasonable to expect patrons to manage their settings for each branch, so we proved a simple set of delivery mechanisms that apply to all branches.

It may be desirable to provide email verification, to ensure that a patron’s email address works and is valid before sending messages—patrons can supply email addresses to the system that may be incorrect or malicious.

Future functionality

For now, providing RSS feeds as a delivery mechanism is future functionality. It’s possible that delivery mechanisms could be implemented using a plug-in system, but this is also future