How to email Koha patrons using the patron emailer

Using the Koha patron emailer, your library can now create custom notices for emailing your library patrons. In this blog post, Rōpū kohinga senior developer Alex Buckley covers two patron emailer implementation options and advises how to choose the right one for your library.

What are the benefits of custom notices?

Custom notices keep your patrons and community connected with library activities. By providing custom notices for your library you can:

• showcase exciting changes to your catalogue. For example, a monthly email listing all new resources added in the last 4 weeks.
• share important library news with your patrons Such as, upcoming events.
• provide helpful reminders for patrons. For example, a monthly email reminding patrons whose Koha accounts are about to expire, to return their checkouts and recalls.

How to implement patron emailer using cronjob

In Koha 19.05, the Koha community added the patron_emailer.pl cronjob. A cronjob is an automated script that can be scheduled to run at any specified date and time. This cronjob does the work of automatically generating and sending out custom notices.

The setup process for the patron emailer cronjob is fairly straightforward. It is mostly configurable by librarians in the Koha staff client:

1. Create a SQL report.
2. Create a custom notice.
3. Request your Koha support vendor to schedule the cronjob.

1. Create a SQL report

This SQL report fetches two pieces of information:

• A list of Koha patrons to send the custom notice to.
• Data to populate your custom notice.

At a minimum, this SQL report must query the borrowers database table. That way, a list of Koha patrons is returned. Without it, Koha won’t know who to email.

The following is an example of an SQL report that fetches Staff patron accounts expiring within the next month:

SELECT cardnumber, email, firstname, surname, categorycode, dateexpiry

FROM borrowers

WHERE categorycode = “S”

AND dateexpiry BETWEEN curdate() and date_add(curdate(), interval 1 month)

NOTE: The inclusion of the WHERE clause at the end of the SQL report is important as it limits which patrons are returned by the SQL report. Excluding a WHERE clause from your SQL report means every Koha patron will be returned. Consequently, every Koha patron would be emailed your custom notice. Often that is not a library’s intended outcome!

2. Create a custom notice

Koha comes with many out-of-the-box default notices. They are configurable by librarians in the Notices and Slips tool. You can also use this tool to create entirely new custom notices.

Koha notices can include database field names surrounded by tags as variables, like << cardnumber >>. That is then substituted with an actual patron cardnumber when the notice is generated. In most notices, these data variables are written surrounded by << >> tags (crocodile teeth syntax).

It’s important that any data variables included in your custom notice also exist in your SQL report. The example below has two variables [% firstname %] and [% surname %]. Compare that to the SQL report example from Step 1. You can see we are selecting firstname and surname in the report too. That is good – the SQL report is providing the data used by the custom notice.

Syntax for custom notices

Custom notices do not use the crocodile teeth syntax. Instead, they use a different syntax called template toolkit. The template toolkit surrounds variables with [% %] tags. For example, [% cardnumber %].

Template toolkit is very flexible. Using it you can add different content to be displayed based on different conditions being true. For example, you can choose to include different notice text for different patron categories, like so:

[% IF categorycode == "PG" %]

This text will be displayed to PG patrons only.

[% ELSIF categorycode == "UG" %]

This text will be displayed to UG patrons only.

[% END %]

Below is an example of a custom notice:

Hi [% firstname %] [% surname %],

Your staff account is expiring this month.

Can you please do the following before the end of the month:

1. Return your checked out items to the library
2. Return recalled items

Thanks,

The library team.

3. Schedule the patron emailer cronjob

This step requires a bit of help from your Koha support provider or someone who has access to your Koha server. You must request they schedule the patron emailer cronjob to run at a regular interval of your choosing. The cronjob generates the custom notices. Without this step, no notices will be sent.

Ensure you provide your Koha support vendor or person with the following information. That way they know how you would like the cronjob set up:

• Koha SQL report ID.
• Koha notice code.
• Koha notice module name.
• Date and time you want the patron emailer notices to be sent. For instance, the first day of every month at 6 am.
• What 'from' email address to configure.
  

How to implement the patron emailer with the plugin

A Koha plugin is functionality librarians can install on their Koha instance. Plugins provide functionality not available in out-of-the-box Koha.

Koha plugins, often maintained by fewer developers than core Koha project code, can become outdated quickly. However, if regularly maintained, they can add new functionality without significant development effort.

The Koha patron emailer plugin is currently supported by the National Library of Finland.

This plugin provides a more manual process for sending custom notices than the patron emailer cronjob. A librarian must manually trigger the plugin for notices to be sent.. Whereas using the cronjob, custom notices are sent automatically.

The setup process for the patron emailer cronjob is fairly straightforward and can be mainly done by a librarian via the Koha staff client:

1. Ask your Koha support vendor to enable Koha plugins.
2. Install the Koha patron emailer plugin.
3. Create SQL report.
4. Create notice - the notice that will be sent.
5. Manually trigger the plugin – This sends out the custom email notices.

1. Ask your Koha support vendor to enable Koha plugins

Raise a ticket with your Koha support vendor requesting they enable plugins for your Koha instance.

2. Install the Koha patron emailer plugin

1. Download the plugin .kpz file from GitLab.
2. In the Koha staff client go to: Administration > Plugins > Manage plugins > Upload plugin.
3. Then upload the .kpz file from your computer.

3. Create a SQL report

This SQL report fetches patron accounts expiring at the end of the semester:

SELECT cardnumber, email, firstname, surname, categorycode, dateexpiry

FROM borrowers

WHERE dateexpiry BETWEEN <<Expires between|date>> AND <<and|date>>

NOTE: The last line in the SQL report contains runtime parameters. When running this report you will be asked to select a start and end date from date pickers. Choosing different dates returns different patrons. The alternative approach would be to have a start and end date hard-coded in the SQL report. But then every time you want to query a different date range you have to modify your report. That’s a more time-consuming process than just using runtime parameters.

4. Create a custom notice

The same process as creating a custom notice for the patron emailer cronjob.

5. Manually trigger the plugin

To send the custom notices, you must manually trigger the plugin.

• In the Koha staff client, go to Administration > Plugins > Manage plugins > ‘[KK-fork] Patron emailer’ > Actions > Run tool.
• You must then select the SQL report you want to run (#1 highlighted box in the below screenshot) and the custom notice you want to send (#2 highlighted box).
  
  

• Click ‘Next’ then you’ll be prompted to enter the runtime parameter values from your SQL report.
• Click ‘Next’ once more to trigger the plugin and send your custom notices.

Choosing the right patron emailer option for your library

The choice between the cronjob or plugin depends on the frequency of sending the custom notices.

The cronjob is recommended for regular custom notices as manual triggers would be time-consuming. For example, monthly reminders for expiring staff. The Patron emailer plugin is recommended for irregular custom notices, so libraries can manage triggering multiple custom notices themselves.

How to keep track of which patrons have received custom notices

To see a full list of which patrons have received a custom notice you can run the following SQL report:

SELECT cardnumber, firstname, surname, content, time_queued, status
FROM borrowers
LEFT JOIN message_queue USING (borrowernumber)
WHERE letter_code = <<Enter letter code>>

NOTE: When you run this SQL report you will be prompted to enter the code of a custom notice.

How to copy your library email address into custom notices

Libraries can use the Koha NoticeBcc system preference to send patron notices to a library address. The patron emailer cronjob and plugin should also send the custom notices to the same address.

Where can I get Koha support?

Rōpū kohinga at Catalyst cares for collections through technology. The dedicated team has hosted and maintained Koha for organisations globally for more than a decade. Additionally, they also provide support for DSpace, VuFind, and other collections technologies.

If you need expert support to improve, manage, or secure your Koha, contact our team today at [email protected].

Keep up to date with the latest events, releases, and other helpful resources from Rōpū kohinga at Catalyst by subscribing to our newsletter.