Bug 40255 - Allow custom debit descriptions
Summary: Allow custom debit descriptions
Status: Signed Off
Alias: None
Product: Koha
Classification: Unclassified
Component: Fines and fees (show other bugs)
Version: Main
Hardware: All All
: P5 - low enhancement
Assignee: Lucas Gass (lukeg)
QA Contact: Lisette Scheer
URL:
Keywords: release-notes-needed
Depends on:
Blocks:
 
Reported: 2025-06-26 19:25 UTC by Andrew Fuerste-Henry
Modified: 2026-02-23 19:34 UTC (History)
2 users (show)

See Also:
GIT URL:
Initiative type: ---
Sponsorship status: ---
Comma delimited list of Sponsors:
Crowdfunding goal: 0
Patch complexity: Medium patch
Documentation contact:
Documentation submission:
Text to go in the release notes:
Version(s) released in:
Circulation function:


Attachments
Bug 40255: Allow for custom debit descriptions (3.67 KB, patch)
2025-10-20 19:52 UTC, Lucas Gass (lukeg)
Details | Diff | Splinter Review
Bug 40255: (follow-up) Fix errors in letter.tt (1.48 KB, patch)
2025-10-20 20:53 UTC, Lucas Gass (lukeg)
Details | Diff | Splinter Review
Bug 40255: Unit test (3.99 KB, patch)
2025-10-20 20:53 UTC, Lucas Gass (lukeg)
Details | Diff | Splinter Review
Bug 40255: (follow-up) Fix errors in letter.tt (1.48 KB, patch)
2025-10-20 20:53 UTC, Lucas Gass (lukeg)
Details | Diff | Splinter Review
Bug 40255: Allow for custom debit descriptions (4.62 KB, patch)
2025-10-20 20:55 UTC, Lucas Gass (lukeg)
Details | Diff | Splinter Review
Bug 40255: Unit test (3.99 KB, patch)
2025-10-20 20:55 UTC, Lucas Gass (lukeg)
Details | Diff | Splinter Review
Bug 40255: (follow-up) Fix errors in letter.tt (1.48 KB, patch)
2025-10-20 20:55 UTC, Lucas Gass (lukeg)
Details | Diff | Splinter Review
Bug 40255: Fixes for translations and updated unit tests (4.00 KB, patch)
2025-11-17 17:55 UTC, Lucas Gass (lukeg)
Details | Diff | Splinter Review
Bug 40255: Allow for custom debit descriptions (4.67 KB, patch)
2025-11-20 21:10 UTC, Andrew Fuerste-Henry
Details | Diff | Splinter Review
Bug 40255: Unit test (4.05 KB, patch)
2025-11-20 21:10 UTC, Andrew Fuerste-Henry
Details | Diff | Splinter Review
Bug 40255: (follow-up) Fix errors in letter.tt (1.54 KB, patch)
2025-11-20 21:11 UTC, Andrew Fuerste-Henry
Details | Diff | Splinter Review
Bug 40255: Fixes for translations and updated unit tests (4.06 KB, patch)
2025-11-20 21:11 UTC, Andrew Fuerste-Henry
Details | Diff | Splinter Review
Bug 40255: Alphabetize dropdown list (4.28 KB, patch)
2026-02-23 16:58 UTC, Lucas Gass (lukeg)
Details | Diff | Splinter Review
Bug 40255: Allow scrubbed HTML to be used (2.93 KB, patch)
2026-02-23 17:54 UTC, Lucas Gass (lukeg)
Details | Diff | Splinter Review

Note You need to log in before you can comment on or make changes to this bug.
Description Andrew Fuerste-Henry 2025-06-26 19:25:52 UTC
Bug 24865 made it possible to use a notice to replace the default wording of the description for overdue fines. It would be helpful to expand that functionality to all debit types, both system-defined and local.

It might make more sense to put this within the Debit Type setup than to continue using notices, though.

These custom descriptions would allow Template Toolkit as notices do, however, for formatting, logic, and value transformation -- for example, one library wants the description to tell what portion of the fee goes to local tax.
Comment 1 Andrew Fuerste-Henry 2025-09-17 21:04:15 UTC
Weird clarifying note here: this suggestion is to allow customization of what goes into the accountlines.description field when a debit is recorded in the patron's account.

This suggestion is *not* to change the value in account_debit_types.description, which is the display value used when selecting a debit type to be used when creating a debit on a patron's account.
Comment 2 Lucas Gass (lukeg) 2025-10-20 19:52:13 UTC
Created attachment 188174 [details] [review]
Bug 40255: Allow for custom debit descriptions
Comment 3 Lucas Gass (lukeg) 2025-10-20 20:53:04 UTC
Created attachment 188176 [details] [review]
Bug 40255: (follow-up) Fix errors in letter.tt
Comment 4 Lucas Gass (lukeg) 2025-10-20 20:53:52 UTC
Created attachment 188177 [details] [review]
Bug 40255: Unit test
Comment 5 Lucas Gass (lukeg) 2025-10-20 20:53:55 UTC
Created attachment 188178 [details] [review]
Bug 40255: (follow-up) Fix errors in letter.tt
Comment 6 Lucas Gass (lukeg) 2025-10-20 20:55:47 UTC
Created attachment 188179 [details] [review]
Bug 40255: Allow for custom debit descriptions

To test:

1. Apply patch, restart all
2. Go to debit types and click "Show all debit types" and pick a system defined debit type to test with. I worked mainly with ACCOUNT ( Account creation fee ) but we should test with as many debit types as possible
3. Note the account_debit_types.code you are working with
4. Now go to Tools > Notices and Slips and create a new notice
5. Choose the "Debit description (custom)" module as your module.
6. Use the code from step 2 and 3.
7. In the "email" part of the noctice add something like:
    $[% accountline.amount %] (includes $[% accountline.amount * 0.1 %] tax)

8. Now go to  Administration > Patron categories and configure a patron category to have a "Enrollment fee". ( I set mine to 100 )
9. Now create a patron in that category.
10. Once created, visit the accounting tab for that patron.
11. You should see a description like "$100.00 (includes $10.00 tax)"
12. Try with other debit types to ensure this works with all.
Comment 7 Lucas Gass (lukeg) 2025-10-20 20:55:50 UTC
Created attachment 188180 [details] [review]
Bug 40255: Unit test
Comment 8 Lucas Gass (lukeg) 2025-10-20 20:55:53 UTC
Created attachment 188181 [details] [review]
Bug 40255: (follow-up) Fix errors in letter.tt
Comment 9 Lucas Gass (lukeg) 2025-10-20 23:09:01 UTC
the tests revealed a problem, setting back to ASSIGNED
Comment 10 Katrin Fischer 2025-10-25 11:23:45 UTC
How will this work with TranslateNotices? Would it be an option to make the language used follow the patron's preferred language? And do we want that or would it be a burden to staff having to deal with descriptions in multiple languages?

My feeling here would be that customization is nice, but I am wondering if we are going the wrong way by saving strings into the database for this purpose. Maybe if we could have a more flexible system that translates on the fly using templates and variables pulled from the db, it would be much better down the road.
Comment 11 Andrew Fuerste-Henry 2025-11-17 17:22:00 UTC
(In reply to Katrin Fischer from comment #10)
> How will this work with TranslateNotices? Would it be an option to make the
> language used follow the patron's preferred language? And do we want that or
> would it be a burden to staff having to deal with descriptions in multiple
> languages?

The existing patches here already work this way. If TranslateNotices is on and the patron has set a preferred language and the library has a translation of their description for that language, we will record the description in the patron's preferred language. Just as Koha will currently record the text of a patron's notices in their preferred language (or use the default if no translation exists).

> My feeling here would be that customization is nice, but I am wondering if
> we are going the wrong way by saving strings into the database for this
> purpose. Maybe if we could have a more flexible system that translates on
> the fly using templates and variables pulled from the db, it would be much
> better down the road.

This seems like a good idea, but also a large idea that needs more fleshing out and should be handled in its own bug and apply to notices more broadly. I'd rather not have this accountlines description functionality stuck behind a project that's not really underway yet.
Comment 12 Lucas Gass (lukeg) 2025-11-17 17:55:47 UTC
Created attachment 189641 [details] [review]
Bug 40255: Fixes for translations and updated unit tests
Comment 13 Lucas Gass (lukeg) 2025-11-17 17:59:14 UTC
Update test plan to include the testing on translated notices:

To test:

1. Apply patch, restart all
2. Go to debit types and click "Show all debit types" and pick a system defined debit type to test with. I worked mainly with ACCOUNT ( Account creation fee ) but we should test with as many debit types as possible
3. Note the account_debit_types.code you are working with
4. Now go to Tools > Notices and Slips and create a new notice
5. Choose the "Debit description (custom)" module as your module.
6. Use the code from step 2 and 3.
7. In the "email" part of the noctice add something like:
    $[% accountline.amount %] (includes $[% accountline.amount * 0.1 %] tax)

8. Now go to  Administration > Patron categories and configure a patron category to have a "Enrollment fee". ( I set mine to 100 )
9. Now create a patron in that category.
10. Once created, visit the accounting tab for that patron.
11. You should see a description like "$100.00 (includes $10.00 tax)"
12. Try with other debit types to ensure this works with all.

Test translatability

13. Turn on "Translate notices"
14. Install at least 1 additional language pack
15. Make a similar ACCOUNT notice similar to the one above, in your choosen language.
16. If using the ACCOUNT notice make sure you set the patron's preffered language when setting up the patron 
17. Make sure the patron gets a custom accountline description in the preffered language.
Comment 14 Andrew Fuerste-Henry 2025-11-20 21:10:55 UTC
Created attachment 189807 [details] [review]
Bug 40255: Allow for custom debit descriptions

To test:

1. Apply patch, restart all
2. Go to debit types and click "Show all debit types" and pick a system defined debit type to test with. I worked mainly with ACCOUNT ( Account creation fee ) but we should test with as many debit types as possible
3. Note the account_debit_types.code you are working with
4. Now go to Tools > Notices and Slips and create a new notice
5. Choose the "Debit description (custom)" module as your module.
6. Use the code from step 2 and 3.
7. In the "email" part of the noctice add something like:
    $[% accountline.amount %] (includes $[% accountline.amount * 0.1 %] tax)

8. Now go to  Administration > Patron categories and configure a patron category to have a "Enrollment fee". ( I set mine to 100 )
9. Now create a patron in that category.
10. Once created, visit the accounting tab for that patron.
11. You should see a description like "$100.00 (includes $10.00 tax)"
12. Try with other debit types to ensure this works with all.

Signed-off-by: Scott Aylett <saylett@spanishfork.gov>
Comment 15 Andrew Fuerste-Henry 2025-11-20 21:10:57 UTC
Created attachment 189808 [details] [review]
Bug 40255: Unit test

Signed-off-by: Scott Aylett <saylett@spanishfork.gov>
Comment 16 Andrew Fuerste-Henry 2025-11-20 21:11:00 UTC
Created attachment 189809 [details] [review]
Bug 40255: (follow-up) Fix errors in letter.tt

Signed-off-by: Scott Aylett <saylett@spanishfork.gov>
Comment 17 Andrew Fuerste-Henry 2025-11-20 21:11:02 UTC
Created attachment 189810 [details] [review]
Bug 40255: Fixes for translations and updated unit tests

Signed-off-by: Scott Aylett <saylett@spanishfork.gov>
Comment 18 Lisette Scheer 2026-02-13 16:52:44 UTC
When creating a manual invoice, description is still shown but doesn't save (example LOST) 

Ideally it would either 
- be hidden if all libraries/your library has a letter code and still show if that's not the case and work as expected
- Show the TT? and allow for changes if needed?

I think removing it entirely would not work for some libraries, although notes could be used, but I think if it doesn't work when something's defined we need a change. 

Additionally for LOST, the title shows even if it's not in the description template. 

This may be a problem for libraries that want to fully customize.

I think that Debit code in the dropdown for adding a notice should be in alphabetical order. I'll file a bug to put Booking in alphabetical order as well since it's the only one that's not. 

Also noting that the HTML checkbox doesn't work (correct but should maybe be in the release notes) 

For reference the following objects are available/populate  when I use the template here (as of posting the template doesn't include accountlines but I'm updating the article today)

https://help.bywatersolutions.com/portal/en/kb/articles/data-availability-via-template-toolkit-per-notice-slip

accountline
borrower
branch
Comment 19 Lucas Gass (lukeg) 2026-02-13 19:52:17 UTC
Thanks Lisette,


> Ideally it would either 
> - be hidden if all libraries/your library has a letter code and still show
> if that's not the case and work as expected
> - Show the TT? and allow for changes if needed?
> 
> I think removing it entirely would not work for some libraries, although
> notes could be used, but I think if it doesn't work when something's defined
> we need a change. 

Maybe, if you want to write a new description when creating a manual invoice it should overwrite the debit description template?


> Additionally for LOST, the title shows even if it's not in the description
> template. 
This must be fixed, I will look into it. 



> This may be a problem for libraries that want to fully customize.
> 
> I think that Debit code in the dropdown for adding a notice should be in
> alphabetical order. I'll file a bug to put Booking in alphabetical order as
> well since it's the only one that's not. 
Yes, it should.


> Also noting that the HTML checkbox doesn't work (correct but should maybe be
> in the release notes) 
IMO, this must be fixed. One should be able to use HTML,
Comment 20 Lucas Gass (lukeg) 2026-02-23 16:58:28 UTC
Created attachment 193655 [details] [review]
Bug 40255: Alphabetize dropdown list
Comment 21 Lucas Gass (lukeg) 2026-02-23 17:16:35 UTC
(In reply to Lucas Gass (lukeg) from comment #19)
> Thanks Lisette,
> 
> 
> > Ideally it would either 
> > - be hidden if all libraries/your library has a letter code and still show
> > if that's not the case and work as expected
> > - Show the TT? and allow for changes if needed?
> > 
> > I think removing it entirely would not work for some libraries, although
> > notes could be used, but I think if it doesn't work when something's defined
> > we need a change. 
> 
> Maybe, if you want to write a new description when creating a manual invoice
> it should overwrite the debit description template?

Actually not sure if that is correct either. I think maybe a hint/tooltip to let the user know if they have a description defined in notices/slips it will be used.
Comment 22 Lucas Gass (lukeg) 2026-02-23 17:19:00 UTC
> > Additionally for LOST, the title shows even if it's not in the description
> > template. 
> This must be fixed, I will look into it.

In the template there is:

                             >[% IF ( account.itemnumber ) %]
                                     <a href="/cgi-bin/koha/catalogue/moredetail.pl?itemnumber=[% account.itemnumber | uri %]&amp;biblionumber=[% account.item.biblionumber | uri %]#item[%     account.itemnumber | uri %]"
                                         >[% account.item.barcode | html %]</a
                                     >
                                 [% END %]</td
                             >


 


I don't think we should change this behavior.
Comment 23 Lucas Gass (lukeg) 2026-02-23 17:54:44 UTC
Created attachment 193666 [details] [review]
Bug 40255: Allow scrubbed HTML to be used
Comment 24 Katrin Fischer 2026-02-23 19:08:45 UTC
(In reply to Lucas Gass (lukeg) from comment #20)
> Created attachment 193655 [details] [review] [review]
> Bug 40255: Alphabetize dropdown list

Please don't do it like this. It only makes sense in English, in every other langauge it will still be very messy. We need to sort by description using code or maybe could have a "function" based sorting.
Comment 25 Lucas Gass (lukeg) 2026-02-23 19:27:16 UTC
(In reply to Katrin Fischer from comment #24)
> (In reply to Lucas Gass (lukeg) from comment #20)
> > Created attachment 193655 [details] [review] [review] [review]
> > Bug 40255: Alphabetize dropdown list
> 
> Please don't do it like this. It only makes sense in English, in every other
> langauge it will still be very messy. We need to sort by description using
> code or maybe could have a "function" based sorting.

We can drop this patch that alphabetizes but what your describing here is a seperate bug.
Comment 26 Lucas Gass (lukeg) 2026-02-23 19:34:11 UTC
(In reply to Katrin Fischer from comment #24)
> (In reply to Lucas Gass (lukeg) from comment #20)
> > Created attachment 193655 [details] [review] [review] [review]
> > Bug 40255: Alphabetize dropdown list
> 
> Please don't do it like this. It only makes sense in English, in every other
> langauge it will still be very messy. We need to sort by description using
> code or maybe could have a "function" based sorting.

I have filed a bug:

https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=41910