Fine batch forgiveness and thresholds RFC

RFC: Fine thresholds and automatic forgiving of fines

A LibLime customer would like the ability to periodically forgive patron fines if the patron's balance is less than a threshold set by the library. To meet this requirement, we propose to implement a batch job or tool.

The job would take the following parameters:

1. branches, patron categories, and item types, and fine account types to identify fines to forgive
2. an amount establishing the maximum threshold to forgive

For each patron, if the total balances of the fees of the specified type are below the threshold, the job would forgive all of those fines.

The job would have a dry-run mode to allow the administrator to check the results of running it before committing to the fine forgiveness.

Details for the Fine thresholds RFC

Initial author: Daniel Sweeney (daniel dot sweeney at liblime dot com)

Overview

Libraries want to be able to forgive patrons who owe small amounts of money to the library at specific times of the year. Typically before the beginning of the term, libraries want to be able to just zero out fines that are only a few dollars to prevent patrons from being blocked from registration. Some libraries do this monthly. Different libraries also have different policies for this—some only forgive overdue fines, but not lost item fines, while some forgive all amounts across the board; some also only forgive overdue fines for some item types.

Pre-Existing Functionality

Koha includes task scheduling functionality, but it’s geared towards generating reports, not jobs that actually change data in the system.

Koha fines and fees (borrower financial accounts) are stored in the accountlines table. Each transaction is recorded in the table, with a code in the account type table. It appears that the account types are not table driven but stored in code.

The valid account types and codes are:

Account Code	Name	Description	Payment/Fine	Seen in
N	New card	?	?	C4::Overdues,members/pay.pl,members/pay.pl
F	Fine	Fine that is non-accruing	Fine	C4::Circulation,C4::Overdues,members/pay.pl
A	Account Management Fee	?	Fine	C4::Overdues,members/pay.pl
M	Sundry	?	?	C4::Overdues,members/pay.pl
L	Lost Item	Item marked as lost	Fine	C4::Overdues, C4::Circulation
REF	Cash Refund	?	Payment	C4::Overdues
CS
CB
CW
CF
CL
Pay	Payment	Payment made to library	Payement	C4::Overdues
FU	Fine Updated/accruing	Fine is still accruing, or was updated	Fine	C4::Circulation,C4::Overdues,members/pay.pl
O	Overdue	?	?	C4::Circulation,C4::Overdues
FFOR	Fine forgiven	Fine was forgiven by library	Payment	C4::Circulation,C4::Overdues
Rep	Replace	?	?	C4::Circulation,C4::Overdues
LR	Lost and Replaced	?	?	C4::Circulation,C4::Overdues
Res	?	?	?	members/pay.pl
IP	?	?	?	members/pay.pl
CH	?	?	?	?
RE	?	?	?	members/pay.pl
RL	?	?	?	members/pay.pl
Rent	Rental Fee	Library charged rental fee for item	Fine	C4::Circulation,C4::Overdues

All Account Types are case-sensitive

(There are more of these that need to be documented and possibly pulled into a table.)

Requirements / Description

Configuration

Administrators will be able to set up one or more configurations for the fine threshold job in the System Preferences area in Administration. This will be part of the “Patrons and Circulation” area and will be labeled “Fine Forgiveness Threshold Configuration.”

Each configuration will be named and will contain a list of entries. Each entry will contain:

1. A patron category code
2. An item type code
3. An account type
4. A cash amount to use as the forgiveness threshold

The patron category codes, item type codes and account types may contain wild-card values. If entries in the list conflict, then the most specific entry will be used. (In other words if a specific patron category has a wildcard, but also an entry for a specific item type, the threshold for the specific item type will be used. The same rule holds, vice versa, for item types.)

A new account type value will be defined for the fine threshold job. The value will be “TFORGIVE” for “Threshold Forgive.”

Fine Threshold Forgiveness batch job

Administrators will be able to run this job as needed from the Koha tools menu to forgive patron fines below a certain threshold.

By default, the job will run in “dry-run” mode—no changes will be written to the database but a log will be generated. Administrators will have to add a positive parameter to the job, by checking a check box indicating “Write Changes to Database”, for changes to actually be written to the database.

The job will write the following information to a log file:

1. The patron information, including at least barcode and name, of each patron whose fines are forgiven.
2. The specific amount of fines that are forgiven for a given patron.
3. The fine account type code for each fine.
4. Whether or not the job ran in dry-run or write-to-database mode.

When the job runs in dry-run mode, this log will be output, but no changes will be written to the database; when the job is run in write-to-database mode, changes will be written.

The general logic of the job is to, for each patron, look at the total balance payable for the patron for all the account types specified in the configuration file. If this balance is less than the threshold value in the configuration file, then all these charges are forgiven, using the TFORGIVE account type code. Forgiveness will take place just as if the operator forgave the fines using a “Forgiven” manual credit in Circulation, but using a different code. The Description for in the accountlines row will be “Forgive.”

Security and Privileges

Running the job will be covered by a new Tools Permission—it will be controlled according to the ordinary Koha permissions system.

For System Administration, access to the configuration area will be covered using the same privileges used now to control access to administration—the management parameter allowing access to the Administration/System Preferences area. In the future when we granularize these privileges more this may become a separate privilege.

Open Questions and notes

There is a question of “potential” fines that will be forgiven. I think in Koha if we support accrued fines (basically the fines a patron would be hit with if they returned all their items now) then these won’t be forgiven (in some sense they haven’t happened yet and the items that would cause them are still overdue.) There’s a potential unfairness here—if a patron owes three dollars in fines, and pays them in good faith, but the library’s policy is to forgive all fines below ten dollars at the end of the month, the honest patron paying three dollars while the lazy patron who does not pay the fine is forgiven and pays nothing.

Since the fine/fee system involves money, an update-free database approach may be best, where any transaction involves an insert into the database, and transaction rows are never updated. It appears that as of 6/9/08 the existing system does go back and update transaction rows, and it does this without ensuring uniqueness of the targeted row (using a LIKE operator). This is a serious bug that will block any reasonable operation of fines, including that proposed.

The tool will run for all patrons and items, regardless of what branch they belong to. Since the configurations allow patron category and item type granularity, it should be possible to have separate configurations for each branch if the system is set up appropriately.

I suggest that you allow a date parameter for limiting on either or both of the following: date of the fine assessment or date of the user's last known activity. Use case: purging old accounts. For example, a high school library may decide to forgive any fines that are from more than 4 years ago (since those kids are gone). Or a library could use this job to purge the fines of users it otherwise considers inactive as of X date. This would be much better than implicitly (silently) removing fines when a borrower record is dropped. --atz