Koha: 21.05 Upgrade Notes

The Koha Community, home of the world's first free and open-source library system, announced last month that the Koha 21.05 release is available. This major release includes 6 new features, 248 enhancements, 449 bugfixes. This blog post will cover Features and Enhancements, for the complete look, see the Koha Community page: https://koha-community.org/koha-21-05-released/.

21.05 Resources

Koha 21.05.00 Manual can be found at:

Koha 21.05.00 schema can be found at:

Significant Changes


Work has continued on refactoring the accounting code this cycle. The ‘Point of sale’ and ‘Cash management’ features have been further enhanced to better expose cash-up functionality to the user interface and aid in auditing processes and effort has been made to ensure all accountline actions are properly recording using double entry accounting methods with offsets to link income to debts.


A significant amount of work has gone into refactoring the transfers system to enable future enhancements and improve maintainability. Transfers can now be queued and a priority system exists for the various mechanisms that can trigger a transfer. Additionally, an audit trail is now left in place to allow future debugging to take place. This has helped us to resolve a number of long standing bugs and edge cases in the transfers process.


Work has continued to make Koha more accessible:

  • Title elements on the OPAC and staff client now start with the most unique information first

  • The structure of headings on the OPAC has improved and headings are now more descriptive

  • Breadcrumbs on the staff interface now show the most unique information first

  • The OPAC has improved labeling to make it more accessible to people using screen readers

PayPal Support

Paypal support has been dropped from Koha core and moved to a plugin [23215]

Blog Post with more information about this change can be found here:

Paypal Update



  • [20212] Improve performance of acquisitions receive page
  • [22773] Bulk close invoices and filter invoice view (open/closed)


  • [11299] Add a button to automatically link authority records in cataloguing (AJAX)

Marc Bibliographic Data Support

  • [8976] Default sequence of subfields in cataloguing and item editor

Staff Client

  • [22569] Add a ‘Transfers to send’ report

System Administration

  • [26633] Add advanced editor for transfer limits



  • [23971] Add logging for basket related actions
  • [26630] Allow custom text for each library on the purchase suggestion page
  • [27023] Add class names in the suggestions column in suggestions management
  • [27240] Export basket: remove spaces and don’t export links
  • [27606] Breadcrumbs on parcel.pl should include a link to the vendor
  • [27646] Allow export of acquisitions home and funds table
  • [27793] Store Contents of FTX segment of EDI quotes for inclusion in orders
  • [27794] Add link to biblio in lateorders page

Architecture, Internals, and Plumbing

  • [22824] Replace YAML::Syck with YAML::XS
  • [23271] Koha::Patron::Category should use Koha::Object::Limit::Library
  • [23583] Handle OpacHiddenItems with yaml_preference
  • [23830] Koha::AuthorisedValues should use Koha::Objects::Limit::Library
  • [24254] Add Koha::Items->filter_by_visible_in_opac
  • [25026] RaiseError must be set for the UI
  • [25670] Add useful methods to Koha::Acquisition::Orders
  • [25755] Add a Koha::Item->request_transfer method
  • [25757] Add a Koha::Item::Transfer->transit method
  • [25767] Add Koha::Item::Transfer->receive method

  • [25802] Koha::Calendar->addDate should be renamed addDuration to better reflect it’s purpose

  • [26057] Add Koha::Item::Transfer->cancel method

  • [26481] Add Koha::Item::Transfer->in_transit method

  • [26618] C4/RotatingCollections.pm should not use C4::Circulation::transferbook

  • [26950] Checkin failure messages are unclear or too specific

  • [27069] Change holdallowed values from numbers to strings

  • [27131] Move code from circ/pendingreserves.pl to modules

  • [27246] Remove apache only code from C4::Context BEGIN

  • [27268] Move C4::Biblio::GetMarcNotes to Koha namespace

  • [27281] Replace call to C4::Circulation::DeleteTransfer with Koha::Item::Transfer->cancel({ comment => $comment }) in C4::Circulation::LostItem

  • [27485] Rename system preference gist to TaxRates

  • [27486] Rename system preference delimiter to CSVDelimiter

  • [27487] Rename system preference reviewson to OPACComments

  • [27491] Rename system preference opaclanguages to OPACLanguages

  • [27636] Replace Koha::Account::pay with a simpler method

  • [27673] Replace YAML with YAML::XS
    Replaces uses of YAML module with more widely supported YAML::XS module.

  • [27756] background_jobs_worker.pl is memory inefficient

  • [27833] Koha::Exceptions::Patron::Attribute::* should have parameters

  • [27851] Add Koha::Old::Checkouts->filter_by_todays_checkins method

  • [27896] Remove C4::Circulation::DeleteTransfer
  • [27930] Move escape* functions from acq/parcel.tt to be re-usable

  • [27995] Koha::Account::Line->apply should return the update Koha::Account::Line object

  • [28056] Add Koha::Exceptions::Patron::MissingMandatoryExtendedAttribute

  • [28210] C4::Circulation::LostItem should pass through skip_record_index to MarkIssueReturned

  • [28278] Improve $KOHA_CONF parsing speed by using XML::LibXML

  • [28386] Replace dev_map.yaml from release_tools with .mailmap


  • [18506] SSO – Shibboleth Only Mode


  • [23302] Less clicks on Z3950 search results
  • [24108] Configure if biblionumber or control number is used for saved files from detail page or advanced cataloguing editor
  • [26943] Show not for loan descriptions in cataloging search (addbooks.pl)
  • [27422] HTML5Media is http by default but Youtube is https only
  • [27545] NewItemsDefaultLocation is only used from additem.pl
  • [27980] Replace obsolete title-string sorting: Catalog templates
  • [28035] Improve breadcrumbs of cataloging search page
  • [28179] Use a lightbox gallery to display the images – detail page, staff interface


  • [12224] Allow easy printing of patron check-in slip
  • [18532] Messaging preferences for auto renewals
  • [18912] Show more item information when using itemBarcodeFallbackSearch
  • [21883] Show authorized value description for withdrawn in check-in
  • [23207] Allow automatic checkin/return at end of circulation period
  • [26937] Add an optional delay to the CheckPrevCheckout system preference
  • [27306] Add subtitle to return claims table
  • [27924] Display number of holds awaiting pickup on check out screens
  • [28034] Add DataTables to lists of clubs in “Clubs” tabs on patron account

Command Line Utilities

  • [15986] Add a script for sending hold waiting reminder notices
  • [24272] Add a command line script to compare the syspref cache to the database
  • [24541] Database clean-up: purge messages
  • [26459] Allow sip_cli_emulator to handle cancelling holds
  • [27048] Add timestamps to verbose output of rebuild_zebra.pl
  • [27049] Add a script to bulk writeoff debts
  • [27050] Allow multiple category_codes in delete_patrons.pl
  • [27839] koha-worker missing tab-completion in bash

Fines and Fees

  • [16486] Display the TIME a fine was collected/written off
  • [23215] Remove PayPal logic from Koha
  • [24300] Add a ‘payout amount’ option to accounts
  • [26272] Allow cashup summaries to be displayed from the library summary page
  • [26273] Expose cashup summary history for a cash register
  • [27967] Modals on the borrower account page don’t validate minimum values
  • [27971] The VOID method should be updated to respect double-entry accounting
  • [28127] POS register details tables should have a transaction date

Hold Requests

  • [24359] Remove items from Holds Queue when checked in
  • [26498] Add option to set a default expire date for holds at reservation time
  • [27016] Make the pickup locations dropdowns use Select2
  • [27790] Possibility to filter Holds to pull list using pickup place
  • [27864] Visual feedback on overridden pickup locations when placing biblio-level hold
  • [27894] Add visual feedback on overridden pickup locations
  • [28092] Holds to pull needs to include reserve notes

Label/Patron Card Printing

  • [15563] Add option to regularly delete patroncard and label batches to cleanup_database.pl cronjob
  • [26875] Allow printing of just one barcode
  • [26962] Koha notice/slips/receipts should print in true black (#000000) of just one barcode
  • [28041] Improve breadcrumbs and headings on label creator pages
  • [28119] Use full description in layout type selection

Marc Bibliographic Data Support

  • [12966] Edition statement missing from card view in Z39.50 result list (acq+cataloguing)
  • [27022] Add publisher number (MARC21 028) to OPAC and staff detail pages
  • [27852] Link YES_NO authorized value category to 942$n in Default framework
Marc Bibliographic Record Staging/Import
  • [26199] Record matching rule match check should include Leader/LDR


  • [11257] Document “items.content” for DUEDGST and PREDUEDGST and update sample notices
  • [14233] Add logging support to notices and slips management
  • [14723] Additional delivery notes to messages
  • [21886] Add option to send notices from owning library instead of issuing library
  • [26734] Convert accounts (monetary) notices to use GetPreparedLetter


  • [12260] Printing a page from bootstrap shows unnecessary links

  • [18989] Allow displaying biblios with all items hidden by OpacHiddenItems
  • [20410] Remove OpacGroupResults system preference and feature
  • [22752] Show item-level hold details for patrons when logged into their account
  • [25775] Add DataTables controls to user’s checkouts table in OPAC
  • [26123] Show info about existing OPAC note/Patron message on patron’s dashboard
  • [26847] Make borrower category code accessible in all pages of the OPAC
  • [27005] Adding a filter in the datatable of opac-readingrecord page
  • [27029] Detail page missing Javascript accessible biblionumber value
  • [27098] Rename ‘Relatives fines’ to ‘Relatives charges’ in OPAC
  • [27440] Improve structure and style of result toolbars in the OPAC[27493] Improve structure and style of checkbox columns in tables
  • [27610] Accessibility: OPAC – h1 on each page is Logo but should be page description/title
  • [27618] Don’t show dropdown if PatronSelfRegistrationLibraryList only has one library
  • [27681] Style OPAC self-registration CAPTCHA as uppercase
  • [27728] Add a search box on OPAC search history
  • [27740] Accessibility: OPAC – Headings should have correct tags and hierarchy
  • [27742] Accessibility: OPAC – Page titles should have unique information first

  • [27814] Improve responsive behavior of the user page in the OPAC

  • [27876] Accessibility: OPAC – Reduce heading redundancy

  • [27991] Message field for checkout notes should have a maxlength set

  • [28018] Replace obsolete title-string sorting: OPAC templates


  • [8326] Allow patron attributes to be made repeatable after initial creation
  • [21549] Lock expired patron accounts after x days
  • [22150] Make it easier to unselect one member permission after selecting all

  • [27607] Add the ability to compare patron records during merge process

  • [27990] Replace obsolete title-string sorting: Patrons

Plugin Architecture

  • [25245] Add a plugin hook to allow running code on a nightly basis

Rest API

  • [23666] Add routes for extended patron attributes

  • [26274] Expose cash register cashup summaries via an API route.

  • [26636] Add objects.find Mojolicious helper

  • [27015] Add filtering options to the pickup_locations routes

  • [27352] Add GET /biblios/:biblio_id/items

  • [27353] Return the number of total records

  • [27366] Add GET /patrons/:patron_id/holds

  • [27544] Simplify /checkouts implementation

  • [27587] Use Basic auth on API tests

  • [27760] Add handling for x-koha-override

  • [27797] Make POST /holds use the stashed koha.overrides

  • [27854] Clean GET /patrons controller

  • [27855] Allow embedding extended_attributes on /patrons routes

  • [27898] Make PUT /holds/:hold_id handle x-koha-override for pickup locations

  • [27932] Add GET /biblios/:biblio_id/pickup_locations

  • [28002] Add optional extended_attributes param to POST /patrons

  • [28157] Add the ability to set a library from which an API request pretends to come from

  • [28189] Move the base swagger file to YAML

  • [28463] Change spec for better looking in the docs


  • [22152] Hide printing the tools navigation when printing reports

  • [24695] Improve SQL report validation

  • [26708] Add option to preview SQL from list of saved reports

  • [26713] Add pagination to bottom of saved SQL reports table

  • [27380] Add option for taking a list parameter in reports

  • [27643] Add CodeMirror custom syntax highlighting for SQL runtime parameters

  • [27644] Add button to SQL report editor for inserting runtime parameters

  • [27994] Replace obsolete title-string sorting: Reports templates


  • [14300] siplogs do not record process IDs

  • [26591] Add a choice to prevent the checkout or warn the user if CheckPrevCheckout is used via SIP2


  • [21249] Syspref to choose whether to search homebranch, holding branch or both for library groups in advanced search
  • [23763] Move pagination calculations to a subroutine


  • [24863] QueryFuzzy syspref says it requires Zebra but Elasticsearch has some support

  • [25054] Display search field aliases in search engine configuration

  • [26991] Add action logs to search engine administration

  • [27682] Add a floating table header for Search engine configuration


  • [23243] Allow filtering out of historic subscription expirations in the check expiration of serials page

  • [27998] Replace obsolete title-string sorting: Serials templates

  • [28036] Improve breadcrumbs of serial claims page

Staff Client

  • [14004] Add ability to temporarily disable added CSS and Javascript in OPAC and interface

  • [25462] Shelving location should be on a new line in holdings table

  • [26703] Modify the “title” elements to contain unique information first

  • [26707] Split cart and lists button on bibliographic detail pages

  • [27404] Update intranet-tmpl/prog/en/modules/labels/label-edit-range.tt for ACC2

  • [27405] Update intranet-tmpl/prog/en/modules/pos/register.tt for ACC2

  • [27406] Update admin/searchengine/elasticsearch/mappings.tt to adhere to ACC2

  • [27407] Update intranet-tmpl/prog/en/modules/reserve/request.tt for ACC2

  • [27409] Update members/boraccount.tt for ACC2

  • [27411] Update tools/automatic_item_modification_by_age.tt to reflect ACC2

  • [27412] Update intranet-tmpl/prog/en/modules/tools/overduerules.tt to adhere to ACC2

  • [27582] Breadcrumb incorrect for POS: Library details page

  • [27846] Accessibility: Staff Client – Breadcrumbs should be more accessible

  • [27982] Replace obsolete title-string sorting: Acquisitions templates part 1

  • [27983] Replace obsolete title-string sorting: Acquisitions templates part 2

  • [28091] Add meta tag with Koha version number to staff interface pages

System Administration

  • [27251] Rewrite the QOTD editor using the Koha REST API

  • [27263] Link to preferences mentioned in system preference descriptions

  • [27395] Add warning to PatronSelfRegistrationDefaultCategory to avoid accidental patron deletion

  • [27415] Add note to ILLHiddenRequestStatuses preference to the ILLSTATUS authorized value category

  • [27598] Add UPLOAD as a built-in system authorized value category

  • [27652] Offer selections for preferences which ask for patron categories
  • [27805] Use input type “email” for email preferences

  • [27975] Replace obsolete title-string sorting: Administration templates


  • [21851] Improve style of sidebar forms

  • [24623] Phase out jquery.cookie.js: Advanced MARC editor

  • [24624] Phase out jquery.cookie.js: Receipt summary

  • [25846] Improve handling of multiple covers on catalog search results in the staff client
  • [26755] Make the guarantor search popup taller

  • [26958] Move Elasticsearch mapping template JS to the footer

  • [26959] Reindent batch item modification template

  • [26960] Move batch item modification template JavaScript to the footer

  • [26970] Add row highlight on drag in Elasticsearch mapping template

  • [26982] Typo in system preference UsageStats: statisics

  • [26985] Remove code for “Upcoming events” from codebase as not implemented

  • [27192] Set focus for cursor to item type input box when creating new item types

  • [27210] Typo in patron-attr-types.tt

  • [27289] Template tweaks for point of sale page

  • [27402] Add column filtering to the Datatables REST API wrapper

  • [27403] Enable fixedHeader for Datatables

  • [27437] Improve hint labels on library creation form

  • [27439] Improve hint labels on patron attribute type entry form

  • [27455] Add focus to branch code when a new library is added

  • [27465] Add column visibility to the admin/cities.pl

  • [27469] Improve link text when returning to vendor page

  • [27471] Improve link text when successfully merging authorities and remove JS redirect

  • [27472] Improve link text when successfully merging bibliographic records

  • [27473] Improve link text in the installer

  • [27474] Improve link text to define a label printer profile if none defined and fix conditional

  • [27475] Improve link text to define a patron card printer profile if none are defined

  • [27476] Improve link text for logging in on OPAC

  • [27477] Improve link text when a record has too many items on the OPAC

  • [27478] Improve link text when viewing an ILL requested item

  • [27479] Improve link text after successfully resetting password in OPAC

  • [27592] Link audio alerts to corresponding preference and back

  • [27605] Add floating toolbar to patron search page

  • [27699] Add cash register information to responsive staff interface header menu

  • [27749] Phase out jquery.cookie.js: Search to hold

  • [27751] Phase out jquery.cookie.js: Batch item modifications

  • [27792] Improve jEditable configuration for point of sale fields

  • [27974] Replace obsolete title-string sorting: Circulation templates

  • [28006] Restore “Additional fields” link on serials navigation menu

  • [28016] Replace obsolete title-string sorting: Assorted templates

  • [28046] Add “Additional fields” link on acquisition navigation menu

  • [28047] Standardize: Call number, callnumber, Call no. etc.

  • [28055] Convert DataTables option names to current version

  • [28066] Remove select tag’s size attribute where it is 1

  • [28081] Make card number a label in patron search results

  • [28132] Remove “this” from button descriptions on basket and basket group pages

  • [28134] Replace use of input type number in onboarding templates

Test Suite
  • [18146] C4::Circulation CanBookBeRenewed lacks full test coverage
  • [4037] Inventory tool missing item type filter

  • [24446] Stockrotation: Update to use daterequested in branchtransfers

  • [25476] Uploaded files can’t be easily browsed via upload.pl

  • [27594] Add access to public download link for publicly-accessible uploads

  • [27766] Hide expired news items by default

  • [27773] Hide unique holidays and exceptions which have passed

  • [28007] Replace obsolete title-string sorting: Tools templates

  • [28014] Add table settings to batch patron modification

  • [28037] Improve breadcrumbs of CSV profiles page
  • [28108] Move action logs ‘SERIAL CLAIM’ and ‘ACQUISITION CLAIM’ to a new ‘CLAIMS’ module

Web Services

  • [27584] Improve OAI-PMH provider performance