Koha How-To

Old Debits and New Credits in 19.11

by Andrew Fuerste-Henry on Jun 16, 2020

Koha version 19.11 made a lot of great changes to improve the data structure around fines and fees. We looked at those broadly in this previous blog post. As our partners get upgraded, though, we've had several questions about one specific aspect of these changes. Libraries are finding patrons who appear to have come out of the upgrade owing the library money on old fines. That's not exactly the case, but it bears some further explanation.

Let's establish a couple of vocabulary terms before we get further in here. Throughout this post I'm going to use "debit" as an umbrella term for any accountlines entry reflecting that the patron owes the library more money (fines, fees, etc). I'll be using the term "credit" as an umbrella term for any accountlines entry reflecting that the patron owes the library less money (payments, writeoffs, actual credits, etc).

A credit for every debit

The relevant changes here are rooted in the idea that whenever the amount outstanding of a debit is reduced, there should be a credit recorded for that change. This seems like a pretty obvious idea -- we all like a clear data trail around fines and fees -- but is a change for Koha. Prior to 19.11, there were several situations in which Koha just edited debits without creating a credit.

The most common example of this has to do with lost item fees for libraries that forgive lost fees when the item is found. In 19.05 and previous, when a lost item was returned, Koha simply found that lost charge and set the amount outstanding to zero (and changes the accounttype from L to LR), without creating any further data trail. In 19.11 and forward, when a lost item is returned Koha instead creates a new accountlines entry for a credit in the amount of the lost item fee and then uses that credit to pay off the fee, leaving a clear data trail. That's great!

Retroactive changes

However, folks have been a little bit confused about what Koha has done with old accountlines data. The upgrade process went back through old debits that had been edited without a corresponding credit, as described above, and reworked the data to match the new, improved structure. The upgrade set the amount outstanding on those debits back to their original amounts and then generated new credits to offset those debits. But the upgrade did not actually apply those credits, which is where the confusion comes from.

Here's an example patron from one of our test sites. From the checkout screen, it looks like this patron owes us money. If that amount were above our fines threshold for checkout, that patron would be blocked from circulation.

However, here's the Make A Payment tab for the same patron. Here we can see that the patron doesn't really owe us anything. They have $4.70 in debits, but also $4.70 in credits, for a net balance of $0. Koha just hasn't yet reconciled the two.

Cleaning up

So our credits and debits all line up as they should, we just need to tell Koha to reconcile the two, setting those outstanding amounts to zero. We've got few ways we can do this.

First, on any individual patron we can click that Apply button you can see in my second screenshot. That will reconcile the credit and debit, leaving this patron's account clear. Easy enough, but it only addresses the one patron. If you like, you could just clean these up as you find them, waiting for the patrons to come to you.

Second, we could write a report to find all of the patrons who have credits like this, so staff could go through and proactively look at their accounts and click those apply buttons. That may be a lot of work, depending on how many patrons it involves, but gives you a lot of manual control. Here's one option for that report:

SELECT CONCAT('<a href=\"/cgi-bin/koha/members/boraccount.pl?borrowernumber=',borrowernumber,'\">', borrowernumber, '</a>') AS borrowernumber,surname, firstname, cardnumber, sum(if(debit_type_code is not null,amountoutstanding,0)) as total_debits, sum(if(credit_type_code is not null,amountoutstanding,0)) as total_creditsFROM borrowers LEFT JOIN accountlines USING (borrowernumber)GROUP BY borrowernumberHAVING total_credits < 0

Third, we do have a script we can run on your site from the commandline that will automatically do through all of your patrons and reconcile any credits and debits it finds. Essentially, the computer clicks all those Apply buttons for you. This is definitely the easiest option, but lacks manual oversight. It's also the only one of these options that one cannot handle entirely from the Koha staff interface.

However you decide to proceed with this, please don't hesitate to reach out for help or further information. We know fines and fees can be a source of concern, so we want to help smooth this out as much as possible.