How to Automatically Email Koha Reports Using Cron on Ubuntu

If you work with Koha, you probably have a few reports that you run regularly. These might include daily circulation statistics, currently issued books, overdue items, new members, or other information required for routine library administration.

In my case, I used to generate circulation reports manually every morning. I would log in to the Koha staff interface, run the saved reports, export the results, and download the files.

It was not a difficult task, but it was repetitive. Since Koha was already installed on an Ubuntu server and email notifications were working, I started looking for a way to automate the process.

I wanted Koha to run the saved reports automatically at a scheduled time and send the results to my email as CSV attachments.

I managed to implement this using Koha’s runreport.pl script and Linux Cron, configured through Webmin. The setup now runs automatically, and the reports are waiting in my inbox when I start work.

In this tutorial, I will explain how you can configure the same functionality for your own Koha installation.

What You Will Learn

By the end of this tutorial, you will be able to:

• Execute a saved Koha report from the command line.
• Email the report as a CSV attachment.
• Automate report execution using Linux Cron.
• Configure the job through Webmin.
• Schedule one report or multiple reports.
• Troubleshoot common errors when a report works manually but fails at its scheduled time.

The procedure was tested on Koha 24.11.04.000 running on Ubuntu Linux. The commands may need minor adjustments depending on your Koha version and installation method.

Requirements

Before starting, make sure you have:

1. Koha installed on an Ubuntu or Debian server.
2. At least one saved report in the Koha Reports module.
3. Access to the server through SSH or a terminal.
4. A working email configuration for Koha.
5. Webmin installed, with permission to create scheduled Cron jobs.

You should also have a valid sender address and a recipient email address where the reports will be delivered.

How to Create a Report in Koha

First, create the report you want to automate.

Log in to the Koha staff interface and navigate to:

Reports → Guided reports → Create from SQL

Write your SQL query, run it, check the results, and save the report.

For example, you might create reports for currently issued books, daily circulation transactions, overdue items, or membership statistics.

Once the report is saved, Koha assigns it a numeric Report ID.

For example:

Report ID	Report name
17	Current books issued
18	Daily circulation transactions
21	Overdue items

These are illustrative examples. Use the IDs assigned to your own reports.

Keep the Report ID handy because we will use it to execute the report from the command line.

Important: The SQL query determines what the report contains. If you want transactions from the previous day, make sure the query uses the appropriate date range. Scheduling a report does not automatically change its SQL date conditions.

Locate the Koha Reporting Script

Koha provides a command-line utility called runreport.pl, which can execute saved reports.

On my Ubuntu installation, the script is located at:

/usr/share/koha/bin/cronjobs/runreport.pl

You can locate the script on your server using:

sudo find /usr/share/koha -name runreport.pl 2>/dev/null

If the command returns:

/usr/share/koha/bin/cronjobs/runreport.pl

you can use that path in the following steps.

If your installation returns a different path, use the one found on your server.

Enter the Koha Environment

This step is important, particularly on package-based Ubuntu and Debian installations.

Initially, I tried executing the reporting script directly using Perl. The command failed with the following error:

Can't locate Koha/Script.pm in @INC

The problem was that Perl could not locate Koha’s required modules because the command was being run outside the properly configured Koha environment.

The solution was to enter the Koha instance’s shell before executing the script.

First, identify your Koha instance name:

sudo koha-list

For example, the output might be:

library

Enter the corresponding Koha shell:

sudo koha-shell library

Replace library with the actual instance name returned by your server.

You can now execute Koha’s command-line reporting script from this shell.

This step is essential when testing the report manually. Later, when configuring Cron, we must ensure that the scheduled job also receives the environment variables required by Koha.

Test the Report from the Command Line

Before automating anything, test whether Koha can execute your saved report successfully.

Suppose your Report ID is 17.

From inside the Koha shell, run:

perl /usr/share/koha/bin/cronjobs/runreport.pl \
    --format=csv \
    --csv-header \
    17

Here is what the options mean:

• --format=csv requests the report in CSV format.
• --csv-header includes column headings in the output.
• 17 is the Report ID.

The report should execute and produce CSV output.

If the report does not run, resolve that issue before proceeding. There is little point in scheduling a command that does not work manually.

Configure the Report to Be Sent by Email

Once the report runs successfully, add the email options.

Use the following command as an example:

perl /usr/share/koha/bin/cronjobs/runreport.pl \
    --format=csv \
    --csv-header \
    --email \
    --attachment \
    --to="your-email@example.com" \
    --from="library@example.edu" \
    --subject="Daily Koha Report" \
    17

Replace the example email addresses and Report ID with your own values.

The command uses Koha’s reporting utility to execute the saved report and email the result.

Understanding the email options

--email

Requests that the report result be emailed.

--attachment

Sends the report as an attachment rather than placing all the report data directly in the email body.

--to

Specifies the recipient’s email address.

--from

Specifies the sender’s email address.

--subject

Sets the subject line of the email.

--format=csv and --csv-header

Ensure the report is generated as CSV with column headings.

The final number, 17, identifies the saved report to execute.

Verify the result

After running the command, check the recipient’s inbox.

You should receive an email with your report as a CSV attachment. Open the attachment and verify that the data matches the report in the Koha staff interface.

Do not proceed to scheduling until the email test works successfully.

Automate the Report Using Webmin Cron

Once the report works manually, the next step is to schedule it.

Linux Cron executes commands automatically at specified times. Webmin provides a graphical interface for configuring these jobs, so you do not have to maintain the entire configuration from the terminal.

Log in to Webmin and navigate to:

System → Scheduled Cron Jobs

Create a new Cron job or edit an existing one.

Configure the following fields.

Execute cron job as

Select:

root

This is the user under which the scheduled command will execute. If you use a different account, make sure it has the necessary permissions and access to the configured Koha environment.

Command

Enter your report command, using the correct paths and email addresses.

For example:

/usr/bin/perl /usr/share/koha/bin/cronjobs/runreport.pl --format=csv --csv-header --email --attachment --to="your-email@example.com" --from="library@example.edu" --subject="Daily Koha Report" 17

Using the absolute path to Perl avoids depending on Cron’s default PATH to find the executable.

Description

Give the job a meaningful description, such as:

Automatically email daily Koha report

Configure Koha Environment Variables in Webmin

This was an important part of my setup.

My report command worked when I executed it manually inside the Koha shell, but the scheduled execution did not work correctly at first.

The reason was the difference between the environment available to an interactive shell and the environment available to Cron.

Cron jobs run with a limited environment. They do not automatically inherit every variable available in your terminal or Webmin session.

To resolve this, I explicitly configured the required environment variables in the Cron job’s environment settings in Webmin.

Depending on your installation, these can include:

KOHA_CONF
PERL5LIB
PATH

The values must match your own installation. Do not copy example paths blindly.

To inspect the environment used by your Koha instance, enter its shell and run:

env | grep -E '^(KOHA_CONF|PERL5LIB|PATH)='

Use the appropriate values when configuring the scheduled job.

Make sure you configure the environment associated with the Cron job itself, rather than assuming that variables set in Webmin’s general configuration are automatically available to Cron.

This distinction solved the scheduled execution problem in my setup.

Set the Schedule

Suppose you want the report to run every day at 11:55 PM.

In Webmin, configure the schedule as follows:

Field	Value
Minute	55
Hour	23
Day	All
Month	All
Weekday	All

The equivalent Cron expression is:

55 23 * * *

This means the command will execute at 23:55 every day, according to the server’s configured timezone.

For execution at midnight, use:

0 0 * * *

I prefer running the reports late at night so that the data is ready for review the following morning.

Check the server timezone

Run:

timedatectl

If your server is intended to use Indian Standard Time, verify that the timezone is:

Asia/Kolkata

If appropriate for your server, you can set it using:

sudo timedatectl set-timezone Asia/Kolkata

Always check the current configuration before changing the server timezone, particularly if other applications depend on it.

Test the Scheduled Job

Save your Cron job in Webmin.

Before waiting for the scheduled time, use Webmin’s Run Now option to execute the job immediately.

Check your inbox and confirm that the report arrives as expected.

If the job works using Run Now but fails when the scheduled time arrives, check the Cron environment variables first.

You can also inspect the root user’s installed Cron jobs using:

sudo crontab -l

For Ubuntu systems that log Cron activity to /var/log/syslog, use:

sudo grep CRON /var/log/syslog | tail -30

This helps establish whether Cron actually launched the command.

Can we Schedule Multiple Koha Reports ?

You do not have to create a separate Cron job for every report.

The runreport.pl script accepts multiple Report IDs in the same command.

For example:

perl /usr/share/koha/bin/cronjobs/runreport.pl \
    --format=csv \
    --csv-header \
    --email \
    --attachment \
    --to="your-email@example.com" \
    --from="library@example.edu" \
    --subject="Daily Koha Reports" \
    17 18 21

This command requests the execution of Reports 17, 18 and 21.

In my Koha setup, each report is emailed separately when multiple Report IDs are supplied with these email options. Therefore, if you use this approach, expect separate messages rather than assuming Koha will combine every report into a single email with multiple attachments.

For most routine reporting requirements, this is perfectly workable. You can schedule several reports at the same time without creating a separate Cron job for each one.

If you prefer separate email subjects for different reports, configure separate commands or jobs accordingly.

Common Problems you may face

Error: Can't locate Koha/Script.pm

This indicates that Perl cannot locate Koha’s required modules.

Test the command inside the proper Koha instance shell:

sudo koha-shell YOUR_INSTANCE

Then execute the report from that shell.

For Cron, configure the required environment variables explicitly so that the scheduled execution can find Koha’s modules.

The command works manually but not at the scheduled time

Check the Cron environment, especially KOHA_CONF, PERL5LIB and PATH.

Also verify that the correct command was saved in Webmin and that the job is enabled.

Cron executes the command, but no email arrives

Check whether the report command produced an error. Also inspect the mail delivery logs if your server uses Postfix.

For example:

sudo tail -50 /var/log/mail.log

The log location depends on your mail configuration.

Remember that successful execution of a command does not necessarily guarantee final delivery to the recipient’s inbox.

The report contains unexpected dates

This is usually a question of the saved SQL query rather than Cron itself.

Check the date conditions in your report and consider when the job executes. A report intended to cover the preceding calendar day should explicitly select the appropriate date range.

In the End

Automating Koha reports is a relatively small improvement, but it can save time every working day.

Instead of logging in to Koha every morning to generate the same reports manually, I can let the server execute them at a scheduled time and send the results directly to my inbox.

The solution brings together a few components:

• Koha Reports to define the information required.
• runreport.pl to execute saved reports and email their results.
• Linux Cron to schedule the task.
• Webmin to manage the schedule and the job’s environment variables.
• The configured mail system to deliver the email.

The most important lesson from my experience was that getting the report to work manually is only part of the job. The scheduled command must also have the correct environment and permissions.

Once those are configured correctly, the process is straightforward and can be adapted to almost any saved Koha report.

For libraries that regularly prepare circulation statistics, overdue lists, membership reports or other operational reports, this is a useful way to reduce repetitive manual work and have the information ready when it is needed.