Koha Solutions

Configuration & operations

How to edit notices and slips in Koha (templates and variables)

Every email, SMS and printed slip Koha sends comes from a template in Tools → Notices and slips. Here is how to edit one, add the patron’s name or the due date with a variable, give one library its own wording, and test it before it reaches a patron.

By Babar Junaid

Published 2026-11-06 · Updated 2026-11-08 · Tested against Koha 26.05

What changed : Added step 5: brand every email notice with one header file (logo, institution name), one footer file (library name, address, social links) and EmailNoticeCSS for colours and the font, per library.

To edit a notice in Koha, go to Tools → Notices and slips, click Edit on the notice (for example ODUE or CHECKOUT), open the Email, Print or SMS panel, change the Message subject and Message body, and click Save. Variables such as <<borrowers.firstname>> are added from the field list with Insert, so they are never misspelled.

StepScreen
Find and edit a noticeTools → Notices and slips
/cgi-bin/koha/tools/letter.pl
Edit one notice directly/cgi-bin/koha/tools/letter.pl?op=add_form&branchcode=&module=circulation&code=CHECKOUT
Decide when overdue notices go outTools → Overdue notice/status triggers
/cgi-bin/koha/tools/overduerules.pl
Make sure the email actually leavesAdministration → SMTP servers, then the SMTP setup

Step 1: Find the notice you want to change

  1. 1Go to Tools, and under Patrons and circulation click Notices and slips.
  2. 2Leave Select a library on All libraries to see the defaults every library uses.
  3. 3Type the code or name in Search above the table, for example ODUE, HOLD or ISSUESLIP.
  4. 4Click Edit on that row. The screen title changes to Modify notice.
Koha Tools, Notices and slips: the Select a library menu (1), Edit on a notice row (2) and New notice (3) marked above the notice table
Tools → Notices and slips: pick the library (1), then Edit a notice (2) or make a New notice (3).

A fresh Koha has about ninety notices. The ones libraries change first:

CodeWhat it is
ODUEThe overdue notice. Koha ships one; for a second and third reminder, create your own notices (New notice → Circulation) and pick each in the First, Second and Third tabs of Overdue notice/status triggers.
PREDUE, DUEAdvance notice before the due date, and the notice on the due date
CHECKOUT, CHECKINEmail receipt after a checkout or a return
HOLDHold waiting for pickup (see the holds workflow)
ISSUESLIP, ISSUEQSLIPThe slip printed at the desk after a checkout (full and quick)
HOLD_SLIP, TRANSFERSLIPThe slip printed when a returned item fills a hold, or must travel to another library
WELCOMEWelcome email to a new patron (sent when AutoEmailNewUser is on)

Step 2: Change the wording and add variables

Each notice has one panel per way it can be sent: Email, Print, SMS, and on some installs Phone or Feed. A patron who gets email reads the Email panel; a printed notice uses the Print panel. The desk slips ISSUESLIP, ISSUEQSLIP, HOLD_SLIP and TRANSFERSLIP are the exception: Koha prints them from the Email panel (see printing slips on a receipt or A4 printer). Edit the one that is actually used, or both.

  1. 1Click the Email panel to open it.
  2. 2Change the Message subject. It becomes the email subject line.
  3. 3In the Message body, click where the value should go.
  4. 4In the field list on the left, click a field, for example borrowers.firstname, then click Insert. Koha writes <<borrowers.firstname>> at the cursor.
  5. 5Tick HTML message only if the body is HTML (links, bold text, a table). Leave it off for plain text.
  6. 6Click Save, or open the arrow beside it and choose Save and continue editing to stay on the screen.
Koha notice editor, Email panel: HTML message box, Message subject, the field list with an Insert button beside the Message body, and Preview and View default buttons
The Email panel of CHECKOUT: field list, Insert, the body, and the Preview and View default buttons.

View default shows the wording Koha shipped with, and Copy to template in that window puts it back. Use it when an edit has gone wrong and nobody kept the original.

The variables you can use

A variable is a database column written as <<table.column>>. The field list only offers the tables that notice actually receives, which is why an overdue notice has item fields and a patron notice does not. The ones asked for most:

VariablePrints
<<borrowers.firstname>> <<borrowers.surname>>The patron’s first name and surname
<<borrowers.cardnumber>>The library card number
<<biblio.title>> <<biblio.author>>Title and author of the book
<<items.barcode>> <<items.itemcallnumber>>Barcode and call number of the copy
<<issues.date_due>>Due date and time; add | dateonly inside the brackets (<<issues.date_due | dateonly>>) for the date alone
<<branches.branchname>> <<branches.branchphone>>Name and phone of the library
<<items.content>>Overdue notices only: the overdue items, one line each (see below)
<<today>>Today’s date
<<OPACBaseURL>>The address of your public catalog, for a “renew online” link
<<borrower-attribute:CODE>>A patron attribute, by its code (for example a student ID)

Dates print in the format set by the dateformat preference, so changing that preference changes every notice (see Koha date format).

Two ways of writing variables

Most of Koha’s own notices now use Template Toolkit, which looks like [% biblio.title %] and names objects in the singular: [% borrower.firstname %], [% item.barcode %], [% branch.branchname %]. The older <<borrowers.firstname>> form still works, and both can sit in the same notice. Template Toolkit also allows conditions and loops ([% IF %], [% FOREACH checkout IN checkouts %]). Copy the style of the notice you are editing.

Listing the overdue items

An overdue notice is about several items at once, so it needs a line that repeats. The ODUE Koha ships does it with a Template Toolkit loop; change the middle line to change what each item shows:

ODUE, Email panel (the shipped item loop, fine line left out)
[% FOREACH overdue IN overdues %][%- SET item = overdue.item -%]"[% item.biblio.title %]" by [% item.biblio.author %], [% item.itemcallnumber %], Barcode: [% item.barcode %][% END %]

Older notices use one of two other forms, and both still work. A line wrapped in <item>…</item> is repeated once per overdue item, with <<biblio.title>>, <<items.barcode>> and the like filled in for each. <<items.content>> prints one ready-made line per item: due date, title, barcode, author and item number. Those columns are set by the overdue job, not the notice: add --itemscontent date_due,title,itemcallnumber (any column of the biblio, items or issues tables) to the overdue_notices.pl line in cron to change them. By default the list holds only the items that reached this trigger; --list-all lists every overdue item the patron has.

Step 3: Give one library its own wording

A notice under All libraries is the default. A copy saved for one library replaces it for that library only, and the others keep the default. This is how a branch gets its own opening hours or phone number in the text.

  1. 1On the All libraries row of the notice, choose the library in the Copy notice list, for example Copy to Centerville.
  2. 2Click Copy. Koha opens New notice with Library set to that library and the default text already in it.
  3. 3Change the text and click Save. The table now shows a second row for the same code, with the library’s name in the Library column.

To go back to the default for that library, delete its row. Do not delete the All libraries row: libraries without their own copy would then have no template for that notice.

Step 4: Test the notice before a patron sees it

Preview exists for three notices only: CHECKOUT, CHECKIN and HOLD_SLIP. On those, fill Data for preview with what it asks for (a barcode, or barcode|borrowernumber, or biblionumber|borrowernumber) and click Preview in the panel. Koha renders the notice with real data and also shows it converted to Template Toolkit. Every other notice has neither the Data for preview box nor the Preview button.

Koha Preview notice template window: the misspelled placeholder borrowers.firstnme renders as Dear followed by a blank, in both the original and the converted Template Toolkit version
Our run on Koha 26.05: a variable spelled borrowers.firstnme renders as “Dear ,” with no error anywhere.

For every other notice, test with a patron record of your own: give a staff test patron your email address, check out an item to them (or place a hold), and read what arrives. For overdue notices, back-date a checkout on the test patron and wait for the overdue job, which a package install runs once a day (see Koha cron jobs).

What Koha can say

MessageMeaning
Do not forget that the item has not been checked out yet.Normal on a CHECKOUT preview: it renders with the item you named, without checking it out
The generated notices are exactly the same!Your notice and its Template Toolkit conversion print the same text
The item or the patron does not exist.The barcode or borrowernumber in Data for preview is wrong
You did not specify data for preview.Fill Data for preview before clicking Preview
You should enable the SMSSendDriver preference to use the SMS templates.The SMS panel is read-only until an SMS driver is set

Step 5: Brand every email notice: logo, header, footer, colours and font

Koha has no setting that puts your logo or a footer on every notice. You build it once from three parts, and every notice follows it: the look (colours and font) in one preference, a header file with the library's logo and your institution's name, and a footer file with the library's name, address and social links. Each notice keeps its own message in between, edited as before. The files read the library from the notice itself, so a Midway patron gets Midway's logo and address from the same two files.

Branded Koha welcome email for a Centerville patron: blue header with the Centerville Library logo and Example University, the notice text, and a footer with Centerville's name and address, Facebook, Instagram and YouTube icons and a catalogue link
The WELCOME notice as a Centerville patron received it, sent by Koha 26.05 with the files below. The logo and icons are sample images.
  • Before you start: shell access to the Koha server with sudo (the two files live there), the Tools → Notices and slips permission, and your logo and icons at public https:// addresses. Tools → Upload with Allow public downloads gives one (see changing the Koha OPAC logo); a relative address does not work in an email.
  • Branding needs an HTML notice. A new Koha ships 81 email notices and 54 of them are plain text, including CHECKOUT, CHECKIN, ODUE, PREDUE, DUE, HOLD, RENEWAL, AUTO_RENEWALS and MEMBERSHIP_EXPIRY. Converting those is covered below.

The look and the font, once for every notice

Go to Administration → System preferences, search EmailNoticeCSS, paste this, and save. Koha puts it in the <head> of every HTML email it sends, so the font, the header colour and the footer style are set in one place:

EmailNoticeCSS
body { font-family: "Noto Sans", Arial, Helvetica, sans-serif; color: #1f2937; font-size: 15px; }.notice-header { background: #0b3d91; color: #ffffff; padding: 12px 16px; margin-bottom: 16px; }.notice-header .institute { font-size: 18px; font-weight: bold; margin: 6px 0 0; }.notice-footer { border-top: 1px solid #d1d5db; margin-top: 24px; padding-top: 8px; font-size: 13px; color: #4b5563; }

Response from a live run on Koha 26.05

The font is font-family: name your font first and end with fallbacks (Arial, Helvetica, sans-serif), because a patron's mail app shows the first font their device has. For Urdu or Arabic, put a font such as "Noto Nastaliq Urdu" or "Noto Naskh Arabic" first and add dir="rtl" to the notice's outer element. PrintNoticeCSS does the same for printed notices, and AllNoticeCSS for both. The notice editor shows all three in its Global HTML notice styles panels. The OPAC's own font is a different setting: changing the font in the Koha OPAC.

Email notice CSS panel on the Koha notice editor page, showing the font, the header colours and the footer style that every HTML email notice gets
Tools → Notices and slips → Edit: the Email notice CSS panel shows the shared look while you edit any notice.

The header and footer files

Notices are Template Toolkit, and Koha lets a notice pull in a file from the staff theme's includes folder. On a package install that is /usr/share/koha/intranet/htdocs/intranet-tmpl/prog/en/includes. Create the header there (sudo nano notice-header.inc) with your institution's name and one logo per library, chosen by its library code:

/usr/share/koha/intranet/htdocs/intranet-tmpl/prog/en/includes/notice-header.inc
[% SWITCH branch.branchcode %][%   CASE 'CPL' %][% logo = 'https://www.example.org/logos/centerville.png' %][%   CASE 'MPL' %][% logo = 'https://www.example.org/logos/midway.png' %][%   CASE %][% logo = 'https://www.example.org/logos/library.png' %][% END %]<div class="notice-header">  <img src="[% logo %]" alt="[% branch.branchname || 'Example University Library' %]" width="180" height="60">  <p class="institute">Example University</p></div>

Response from a live run on Koha 26.05

Replace CPL and MPL with your library codes (Administration → Libraries) and the addresses with your logos. One library only? Keep just the last CASE. Then the footer (sudo nano notice-footer.inc): the name and address come from Administration → Libraries, so each library's own details appear without a second file. Put your own social pages and icon addresses in:

/usr/share/koha/intranet/htdocs/intranet-tmpl/prog/en/includes/notice-footer.inc
[% USE Koha %]<div class="notice-footer">  [% IF branch %]    <p><strong>[% branch.branchname %]</strong>[% IF branch.branchaddress1 %], [% branch.branchaddress1 %][% END %][% IF branch.branchcity %], [% branch.branchcity %][% END %]</p>    [% IF branch.branchphone %]<p>Phone: [% branch.branchphone %]</p>[% END %]  [% ELSE %]    <p><strong>Example University Library</strong></p>  [% END %]  <p>    <a href="https://www.facebook.com/examplelibrary"><img src="https://www.example.org/icons/facebook.png" alt="Facebook" width="24" height="24"></a>    <a href="https://www.instagram.com/examplelibrary"><img src="https://www.example.org/icons/instagram.png" alt="Instagram" width="24" height="24"></a>    <a href="https://www.youtube.com/@examplelibrary"><img src="https://www.example.org/icons/youtube.png" alt="YouTube" width="24" height="24"></a>  </p>  <p><a href="[% Koha.Preference('OPACBaseURL') %]">Search our catalogue</a></p></div>

Response from a live run on Koha 26.05

The [% IF branch %] part matters: a notice that Koha prepares without a library printed Example University Library and the default logo instead of an empty name. Use PNG or JPG icons with a width, height and alt. A change to either file shows in the very next email of every notice: no notice to edit, no restart.

Add the two lines to the notices

  1. 1Open Tools → Notices and slips, click Edit on a notice and open its Email panel.
  2. 2Tick HTML message.
  3. 3Put [% INCLUDE 'notice-header.inc' %] as the first line of the Message body and [% INCLUDE 'notice-footer.inc' %] as the last. Leave the notice's own text in between.
  4. 4Click Save, then test it with Preview (step 4) or a real checkout.
Koha notice editor, Email panel of the WELCOME notice: HTML message ticked (1) and the message body starting with the notice-header.inc INCLUDE line and ending with the notice-footer.inc INCLUDE line (2)
WELCOME with HTML message ticked (1) and the two INCLUDE lines around its own text (2).

To add the lines to every notice that is already HTML in one go, take a copy of the notices first, then run the update in sudo koha-mysql library (your instance name from sudo koha-list). On a new Koha it changes 27 notices and answers ROW_COUNT() 27; run twice, it changes nothing the second time.

MySQL
CREATE TABLE letter_before_branding AS SELECT * FROM letter;UPDATE letter SET content = CONCAT("[% INCLUDE 'notice-header.inc' %]\n", content, "\n[% INCLUDE 'notice-footer.inc' %]") WHERE message_transport_type = 'email' AND is_html = 1 AND content NOT LIKE '%notice-footer.inc%'; SELECT ROW_COUNT();

Response from a live run on Koha 26.05

To undo it, run UPDATE letter l JOIN letter_before_branding b ON b.id = l.id SET l.content = b.content; and then DROP TABLE letter_before_branding;. In our run that put every notice back exactly.

Turn a plain-text notice into a branded one

Ticking HTML message on a plain-text notice such as CHECKOUT makes its lines run together (…checked out: ---- …), because HTML ignores line breaks. Keep them by wrapping the notice's own text in one div, between the two INCLUDE lines:

Message body (CHECKOUT, email)
[% INCLUDE 'notice-header.inc' %]<div style="white-space: pre-line">…the notice's own text, unchanged…</div>[% INCLUDE 'notice-footer.inc' %]

Response from a live run on Koha 26.05

Different branding for each library

  • Name, address and phone change by themselves: the footer reads them from the library the notice is for.
  • A different logo: one CASE line per library code in notice-header.inc, as above.
  • Different wording for one library: copy the notice to that library (step 3) and keep the two INCLUDE lines in the copy, so its branding still comes from the same files.

When the branding goes wrong

What you seeWhy, and the fix
The patron sees <div class="notice-footer"> and other tags as textHTML message is not ticked on that notice, so Koha sent it as plain text. Tick it
The notice is not created; the log says ERROR PROCESSING TEMPLATE: file error - notice-footr.inc: not foundThe file name in the INCLUDE line is misspelt, or the file is not in the includes folder. Koha stops that notice
No colours, just plain text with the logoSome mail apps drop styles. Check in the apps your patrons use; the content and links still arrive
No logo, a broken imageThe address is not public or not https://, or the mail app blocks images until the reader allows them
The library name is emptyThe notice was prepared without a library; the [% IF branch %] fallback in the footer covers it

Upgrades: the two files belong to no package, so a Koha upgrade leaves them where they are (dpkg -S on notice-footer.inc answers dpkg-query: no path found matching pattern, while Koha's own slip-print.inc next to it belongs to koha-common). Keep a copy of both with your backups, because a reinstall of the server does not bring them back.

Notice settings worth knowing

PreferenceWhat it does
TranslateNoticesWhen set to Allow, each notice gets a tab per installed language and a patron receives the one in their own language (see installing a language)
NoticeBccSends a blind copy of every notice to one address, useful for a week after changing notices
EmailFieldPrimaryWhich of the patron’s email fields notices go to: primary, secondary, alternate, or the first valid one
AllNoticeCSS, EmailNoticeCSS, PrintNoticeCSSStyling for HTML notices and printed slips, in one place instead of in every notice
AutoEmailNewUserSends the WELCOME notice to every new patron

Why a variable comes out blank

Koha replaces each <<table.column>> it recognises and then deletes every variable it did not recognise, without a warning. A typo (borrowers.firstnme), a table the notice does not receive (items.barcode in a patron notice), or a column that is empty for that patron all print as nothing. That is why inserting from the field list matters more than it seems, and why the preview above showed “Dear ,”.

The other surprise is the library copy. Koha looks for a notice belonging to the patron’s or item’s library first and falls back to All libraries only when there is none. An edit made to the default does not reach a library that has its own copy, which is the usual reason “we changed the notice and one branch still sends the old text”.

The notice is right but nobody receives it

SymptomWhere to look
No email notices go out at allThe mail setup, not the template: SMTP server, test email and koha-email-enable
Overdue notices never go to some patronsOverdue notice required is off on their patron category, or no trigger is set for it in Overdue notice/status triggers
A patron gets no checkout receiptTheir messaging preferences: Item checkout (or Item checkout and renewal) must be ticked for email on the patron
One library still sends the old wordingIt has its own copy of the notice; edit or delete that row
Variables print as nothingMisspelled, empty, or not available in this notice: insert from the field list

Tested on live Koha 26.05.02

Passed all 42 checks · Read the run log

Koha release
26.05.02
System
Debian 13 (trixie)
Setup
Official Koha test container (koha-common commands). A command that needs systemd or a firewall says where it ran.
Source read at
Koha commit d3fc229
Earlier live checks (1)
  • , Koha 26.05.02 (commit d3fc229): all 17 claims held. Read the run log
Verified against the Koha source (16 files)

The label under each command says where its response came from; a command with no label was not run live. How we test and which standards we follow.

Share this article

Want your notices rewritten, branded and tested for every library and language? We set them up on your own Koha so patrons get clear messages.

Want your staff trained on this? We teach it hands on with a live Koha, online or at your library. Ask about staff training