Integrating Koha and Unique's Gentle Nudge

by Kelly McElligott on Mar 24, 2023

Let's talk integrations! Koha integrates with so many third-party vendors- let's break down how Unique works with Koha.

Unique Plugin

When developers work with third-party vendors to integrate with Koha, they tend to choose to do this connection via a plugin. Plugins allow for changes to be made at any time versus if the connection was integrated into Koha proper, the changes would need to do at the time of upgrades. In addition, plugins are generally very specific to a vendor, which allows developers to cater to the connection individually.

For more information on plugins:

To plug, or not to plug? Why we develop Koha plugins

Monday Minutes: Plugins in Koha

KohaCon 2022: Leveling up with Plugins

To utilize the plugin to integrate Unique with Koha, download the plugin here.

If you are a partner of ByWater Solutions and prefer to have us do this process, submit a ticket!

Unique Gentle Nudge

This plugin automates the process of sending patrons to the UMS collections service and updating those patrons in Koha.

Gentle Nudge is a product offered by Unique Management Services to assist libraries with the recovery of overdue material and unpaid fines. ByWater’s Gentle Nudge plugin will generate and send reports of patrons to UMS. UMS then contacts those patrons and ‘nudges’ them to return to the library to pay their fines and/or return materials. UMS does not ‘collect’ on behalf of the library.

UMS will generally want three reports from Koha:

1. A Submission Report: Typically a weekly report of ‘new’ patrons that qualify for collections based on the specified criteria of minimum balance, patron types, account age, etc.
2. An Update Report: A report sent daily that monitors previously referred / active accounts for changes in account balance. This report keeps UNIQUE current on patron balances on active collection accounts.
3. A Synchronization report: A maintenance report of all users flagged for collection. This report sends the patron ID, Patron name, and total amount owed. Unique uses this report to query against our database to look for balance discrepancies and is useful for troubleshooting or catching up on missed updates or submission files.

What the plugin will do:

It will automatically flag patrons who meet specific requirements as being in collections and optionally add a processing fee and restrict their account. Once a patron clears their account by paying their fines to 0, the plugin can optionally automatically clear the collections flag. At this time, the patron’s account restriction must be manually removed by library staff.

Configuring the plugin

On what day of the week would you like new submissions sent to Unique?

Choose a single day of the week to report new patrons in collections to Unique. Any day of the week can be selected.

What patron categories are eligible for collections?

Enter the Koha category codes for the patrons that can be sent to collections. You can enter as many category codes as you need. Remember to enter the category code and not the Patron category name. You can find the category codes by going to Administration->Patron categories in Koha. If this field is left blank, all patron categories will be included.

Threshold: at what amount owed should patrons be sent to collections?

This is the minimum amount owed by a single patron that will move them to collections.

Processing fee: what fee, if any, should be applied to patrons’ accounts when they are sent to collections?

If you charge the patron an additional fee when they are moved to collections, enter it here. It will be added to the patron’s account as a line item.

Unique email: to what email address with UMS would you like the report sent?

This email will be provided to you by Unique Management Systems. It is the email address at which they will receive the weekly, daily, and sync reports from Koha.

Collections flag: How are you identifying patrons in collections?

This is the field that Koha will use to mark patrons as being in collections. Sort1, Sort2, or a Patron Attribute are often used. Your Data Librarian and Educator will discuss the options with you.

Count fees newer/older than

These parameters establish the age of fees that Koha will review in determining collection status for new submissions and updates, i.e. the total fees between X and Y days old to check if a patron should be sent to collections. The default values are older than 60, and newer than 90.

Clear collections flag

If you would like the collections to flag automatically cleared for patrons who have paid their balance to 0, select Yes from the dropdown.

Add Restriction

If your library restricts patrons while they are in collections, select Yes from the dropdown. Remember that while the collections flag can be set to clear automatically, restrictions must be manually cleared.

Flagging Collections

A library can use a Sort field or a Patron Attribute for flagging a patron.

If using sort1 or sort2 for your collections flag, make sure that there isn't already data in there! Patrons will ONLY be sent to collections if the collections flag value is either "no" or NULL.

If using a patron attribute, on the other hand, make sure that the only authorized values are 1 and 0 (preferably tied to the YES/NO authorised_value). When using an attribute, the plugin checks for 1/0 rather than literal yes/no.

Cron Job

This plugin is also connected to a cron job (a backend process). If you are a partner of ByWater, please let us know and we can ensure the set up is complete and start up this cronjob to run nightly.