Bug 40255

Summary: Allow custom debit descriptions
Product: Koha Reporter: Andrew Fuerste-Henry <andrew>
Component: Fines and feesAssignee: Lucas Gass (lukeg) <lucas>
Status: Needs Signoff --- QA Contact: Testopia <testopia>
Severity: enhancement    
Priority: P5 - low CC: lucas
Version: Main   
Hardware: All   
OS: All   
See Also: https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=24865
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
Bug 40255: (follow-up) Fix errors in letter.tt
Bug 40255: Unit test
Bug 40255: (follow-up) Fix errors in letter.tt
Bug 40255: Allow for custom debit descriptions
Bug 40255: Unit test
Bug 40255: (follow-up) Fix errors in letter.tt
Bug 40255: Fixes for translations and updated unit tests

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.