Chapter 11. Reports

Table of Contents

1. Custom Reports
1.1. Add Custom Report
1.2. Edit Custom Reports
1.3. Running Custom Reports
2. Statistics Reports
2.1. Acquisitions Statistics
2.2. Patron Statistics
2.3. Catalog Statistics
2.4. Circulation Statistics
2.5. Serials Statistics
2.6. Holds Statistics
2.7. Patrons with the most checkouts
2.8. Most Circulated Items
2.9. Patrons with no checkouts
2.10. Items with no checkouts
2.11. Catalog by Item Type
2.12. Lost Items
2.13. Average Loan Time
3. Report Dictionary

Reports in Koha are a way to gather data. Reports are used to generate statistics, member lists, shelving lists, or any list of data in your database.

Koha's data is stored in a MySQL database which means that librarians can generate nearly any report they would like by either using the Guided Reports Wizard or writing their own SQL query.

The guided report wizard will walk you through a six step process to generate a report.

Step 1: Choose the module you want to report on. This will determine what tables and fields are available for you to query.

'Report is public' should be left to the default of 'No' in most cases. A report can be made public if you intend to allow access to it through the JSON webservice interface. This is a system that can be used by developers to make custom presentations of the data from the report, for example displaying it using a graphing API. To learn more speak to your local developer.

  • A public report is accessible via a URL that looks like this: http://MYOPAC/cgi-bin/koha/svc/report?id=REPORTID

Note

If your system administrator has set up memcache on your server you might see one more option for the Cache expiry. This is related to your public reports. If you make the report public then it's constantly running and will cause a large load on your system. Setting this value prevents that.

Step 2: Choose a report type. For now, Tabular is the only option available.

Step 3: Choose the fields you want in your report. You can select multiple fields and add them all at once by using CTRL+Click on each item you want to add before clicking the Add button.

Step 4: Choose any limits you might want to apply to your report (such as item types or branches). If you don't want to apply any limits, simply click Next instead of making an option.

Step 5: Perform math functions. If you don't want to do any calculations, simply click Next instead of making an option.

Step 6: Choose data order. If you want the data to print out in the order it's found in the database, simply click Finish.

When you are finished you will be presented with the SQL generated by the report wizard. From here you can choose to save the report by clicking 'Save' or copy the SQL and make edits to it by hand.

If you choose to save the report you will be asked to name your report, sort it in to groups and subgroups and enter any notes regarding it.

Once your report is saved it will appear on the 'Use Saved' page with all other saved reports.

From here you can make edits, run the report, or schedule a time to have the report run. To find the report you created you can sort by any of the columns by clicking the on the column header (creation date is the best bet for finding the report you just added). You can also filter your results using the filter menu on the left or use the tabs to find reports based on your custom groups.

In addition to the report wizard, you have the option to write your own queries using SQL. To find reports written by other Koha users, visit the Koha Wiki: http://wiki.koha-community.org/wiki/SQL_Reports_Library. You can also find your database structure in /installer/data/mysql/kohastructure.sql or online at: http://schema.koha-community.org.

To add your query, click the link to 'Create from SQL' on the main reports module or the 'New report' button at the top of the 'Saved reports' page.

Fill in the form presented

  • The 'Name' is what will appear on the Saved Reports page to help you identify the report later. It will also be searchable using the filters found the left of the Saved Reports page.

  • You can use the 'Report group' to organize your reports so that you can easily filter reports by groups. Report groups are set in the REPORT_GROUP authorized value category or can be added on the fly when creating the report by choosing the 'or create' radio button.

    • Note

      If you're adding a report group on the fly, remember that you code should be fewer than 10 characters and should not include special characters or spaces.

  • You can use 'Report subgroup' to further organize your reports so that you can easily filter reports by groups and subgroups. Report subgroups are set in the REPORT_SUBGROUP authorized value category or can be added on the fly when creating the report by choosing the 'or create' radio button.

    • Note

      If you're adding a report subgroup on the fly, remember that you code should be fewer than 10 characters and should not include special characters or spaces.

  • 'Report is public' should be left to the default of 'No' in most cases. A report can be made public if you intend to allow access to it through the JSON webservice interface. This is a system that can be used by developers to make custom presentations of the data from the report, for example displaying it using a graphing API. To learn more speak to your local developer.

    • A public report is accessible via a URL that looks like this: http://MYOPAC/cgi-bin/koha/svc/report?id=REPORTID

  • 'Notes' will also appear on the Saved Reports page, this can be used to provide more details about the report or tips on how to enter values when it runs

  • The type should always be 'Tabular' at this time since the other formats have not been implemented

  • In the 'SQL' box you will type or paste the SQL for the report

  • If you feel that your report might be too resource intensive you might want to consider using runtime parameters to your query. Runtime parameters basically make a filter appear before the report is run to save your system resources.

    There is a specific syntax that Koha will understand as 'ask for values when running the report'. The syntax is <<Question to ask|authorized_value>>.

    • The << and >> are just delimiters. You must put << at the beginning and >> at the end of your parameter

    • The 'Question to ask' will be displayed on the left of the string to enter.

    • The authorized_value can be omitted if not applicable. If it contains an authorized value category, or branches or itemtype or categorycode or biblio_framework, a list with the Koha authorized values will be displayed instead of a free field Note that you can have more than one parameter in a given SQL Note that entering nothing at run time won't probably work as you expect. It will be considered as "value empty" not as "ignore this parameter". For example entering nothing for : "title=<<Enter title>>" will display results with title='' (no title). If you want to have to have something not mandatory, use "title like <<Enter title>>" and enter a % at run time instead of nothing

    Examples:

    • SELECT surname,firstname FROM borrowers WHERE branchcode=<<Enter patrons library|branches>> AND surname like <<Enter filter for patron surname (% if none)>>

    • SELECT * FROM items WHERE homebranch = <<Pick your branch|branches>> and barcode like <<Partial barcode value here>>

    • SELECT title , author FROM biblio WHERE frameworkcode=<<Enter the frameworkcode|biblio_framework>>

    Note

    To generate a date picker calendar to the right of the field when running a report you can use the 'date' keyword like this: <<Enter Date|date>>

    Note

    You have to put "%" in a text box to 'leave it blank'. Otherwise, it literally looks for "" (empty string) as the value for the field.

    Important

    In addition to using any authorized value code to generate a dropdown, you can use the following values as well: Framework codes (biblio_framework), Branches (branches), Item Types (itemtypes) and Patron Categories (categorycode). For example a branch pull down would be generated like this <<Branch|branches>>

Note

There is a limit of 10,000 records put on SQL statements entered in Koha. To get around this you want to add 'LIMIT 100000' to the end of your SQL statement (or any other number above 10,000).

Note

If your system administrator has set up memcache on your server you might see one more option for the Cache expiry. This is related to your public reports. If you make the report public then it's constantly running and will cause a large load on your system. Setting this value prevents that.

Once everything is entered click the 'Save Report' button and you'll be presented with options to run it. Once a report is saved you do not have to recreate it you can simply find it on the Saved Reports page and run or edit it.

Reports can also be added by duplicating an existing report. Visit the 'Saved reports' page to see all of the reports listed on your system already.

To the right of every report there is an 'Actions' pull down. Clickin that and choose 'Duplicate' to use an existing report as the basis for your new report. That will populate the new report form with the existing SQL for easy editing and resaving.

Every report can be edited from the reports lists. To see the list of reports already stored in Koha, click 'Use Saved.'

To find the report you'd like to edit you can sort by any of the columns by clicking the on the column header. You can also filter your results using the filter menu on the left or use the tabs to find reports based on your custom groups.

From this list you can edit any custom report by clicking 'Actions' to the right of the report and choosing 'Edit' from the menu that appears.

The form to edit the report will appear.

Once custom reports are saved to Koha, you can run them by going to the Saved Reports page and clicking the 'Actions' button to the right of the report and choosing 'Run'.

When you report runs you will either be asked for some values

or you will see the results right away

From the results you can choose to rerun the report by clicking 'Run report' at the top, edit the report by clicking the 'Edit' button or starting over and creating a new report by using the 'New' button. You can also download your results by choosing a file type at the bottom of the results next to the 'Download the report' label and clicking 'Download.'

Note

A Comma Separated Text file is a CSV file and it can be opened by any spreadsheet application.