Phase 2: Birthday Wish - Email
Sending a friendly birthday greeting is a highly effective, modern approach to Library Customer Relationship Management (CRM). By default, Koha does not have a built-in setup to send birthday wishes via email. We can easily fix this by setting up an automatic background system to email a friendly birthday wish to every active member on their special day.
- Things to Check First
Before deploying this module, make sure your Koha instance has its built-in SMTP email configuration fully activated and verified. If your library cannot currently send standard automated emails (like Welcome Emails or checkout receipts), you must ensure your mail routing settings are working properly first. This script relies entirely on an active, working email setup to dispatch messages to the internet.
Note on Instance Names: Throughout this tutorial, we use the default Koha instance name library in all commands and log paths; if your server uses a different name, simply swap it out with your actual instance name when executing the steps.
- Setting Up the Source Files
Because pasting extensive programming text blocks can clutter blog layout, the complete deployment assets have been packaged into a dedicated folder. You will need to pull down two specific files:
notice_template.html – Contains the fully responsive, mobile-friendly HTML layout for the birthday graphic card.
patron_birthday_emailer.pl – The Perl script that scans the database while automatically excluding expired or inactive patron accounts using the dateexpiry field.
📁 [Click Here to Download the Tutorial Code Bundle Folder]
Step-by-Step File Placement:
Open the code page with a text editor and copy the code inside notice_template.html. Log into your Koha Staff Client, navigate to Tools ➔ Notices & Slips, and create a new notice under the Patrons module using the exact capital letter code BIR. Check the HTML message checkbox and paste the code into your Email Message Body with Name and Subject.
Open your terminal and create the system automation file using your favorite text editor:
sudo nano /usr/share/koha/bin/cronjobs/patron_birthday_emailer.plCopy the entire contents of the downloaded `patron_birthday_emailer.pl` file, paste it directly into your terminal window, save your changes, and exit (`Ctrl+O`, `Enter`, `Ctrl+X`).
Grant the script execute permissions so the operating system can run it automatically:
sudo chmod +x /usr/share/koha/bin/cronjobs/patron_birthday_emailer.pl
- Setting Up the Schedule (Cron Job)
To make this completely automatic, we need to tell the server to run our birthday script every single morning. Because many libraries switch off their local servers overnight, make sure to set the execution time to an hour when your library server is guaranteed to be switched on and running.
⚠️ Important Update Note: Never add custom cron lines directly into the official, default Koha cron files. If you do, your changes will be completely erased and overwritten the next time you update Koha to a newer version. To prevent this, we always place our custom rules in a separate, brand-new file.
Open your server's custom cron configuration file:
sudo nano /etc/cron.d/koha-user-custom
Paste this single line at the very bottom of the file (adjust the 0 8 if your server switches on later in the morning):
0 8 * * * root /usr/sbin/koha-shell library -c "perl /usr/share/koha/bin/cronjobs/patron_birthday_emailer.pl -c -v" >> /var/log/koha/library/birthday_cron.log 2>&1
Save and close the file. Your server's internal automation engine will automatically pick up the script and safely handle everything moving forward, even after future Koha software updates!
Patron Data Requirement: Please keep in mind that this script relies strictly on valid communication profiles. Only patrons with a recorded Date of Birth (DOB) and an active and functional email address stored in their patron account will be processed to receive birthday greetings.
- Troubleshooting Your Automation Setup
If your automated morning greetings aren't arriving as expected, use these quick terminal diagnostic steps to identify the bottleneck:
Check the Script Output Logs: Review the runtime logs generated by your custom execution schedule to view errors, warnings, or missing dependencies:
cat /var/log/koha/library/birthday_cron.log
Verify the System Automation Engine: Make sure your Linux background scheduler is active, enabled, and successfully processing system configuration paths:
sudo systemctl status cron