Hourly Loans RFC

From Koha Wiki

Jump to: navigation, search
Home > Development > RFCs
Home > Development > RFCs > Koha components for RFCs > Library System Modules RFCs > Circulation RFCs
Home > Development > RFCs > Koha version targeted RFCs > RFCs not targeted at a particular Koha version


Hourly Loans

Sponsored by Unknown and developed by Ian Walls, ByWater Solutions., expected for/deadline: 2010-12-28

See also Bug 5549.

Work in progress: No URL given.


Koha 3.2's circulation loans are currently measured only in units of days. However, because some libraries, especially academic libraries, perform loans that are measured in minutes or hours, particularly for course reserves and short loans, it is necessary to modify Koha to perform all circulation and related transactions in units of minutes

The main changes will include:

  • editing the issues, reserves and items tables (and their old/deleted equivalents) to store data in datetime rather than just date.
  • editing the issuing rules to allow for selection of different units (minutes, hours or days), as well as ‘rounding periods’ and circulation behavior over periods when the library is closed
  • editing the library calendars to allow for opening and closing times and exceptions thereto
  • adding display of due times
  • adding the ability to calculate overdue fines by the minute
  • adding the ability to send email or SMS notices hours or minutes before/after an item is due

This RFC is similar to the unimplemented RFC for Hourly circulation policies from Koha 3.2



This specification changes the loan system in Koha to support loan, grace periods and fine periods measured in hours. As part of this project, it will be possible to create circulation policies in terms of hours and minutes. These policies will work in tandem with new calendars that allow the library to express their opening and closing times in hours.

Circulation Policies

The following policies will be expressible in the smart-rules.pl with a combination of numeric field and unit dropdown selector.:

  1. Loan time: Duration of the loan
  2. Grace Period: How long after the due time before fines begin to accrue.
  3. Charging Interval. How often to increment fines
  4. Suspension period: how long a patron will be blocked from circulating after an item becomes overdue (factoring in the grace period)

The possible units will be:

  1. Days
  2. Hours
  3. Minutes

Koha will store the policies’ numeric values with the minute as the base unit. The smart-rules.pl interface will automatically convert hours and days into minutes using JavaScript. Any numeric value in the field when the unit is changed will be mathematically converted. If the conversion does not yield an integer (for example, converting 1 minute to hours), the value will be rounded down (or up) to the nearest integer. A system preference can be used to control whether rounding is up or down.

COMMENT: This paragraph should probably be revised for clairty. I cannot imagine any combination of hours and days which should not be convertable to minutes with no remainder. The only place I can see for rounding to be needed is in the caculation of fines when a patron returns an item, for example, 90 seconds overdue, which is addressed in this RFC below. -chris_n

COMMENT: Logic (such as unit conversion) should probably be left to the controller portion of the code rather than pushed off to the display portion (thinking MVC here). Perhaps it would be better to use an ajax type call to change/convert units in the view. -chris_n

Additional circulation policies will become necessary to handle “rounding” of due times, since the library does not necessarily wish an item checked out for 1 day to be due exactly 1440 minutes later.

Options for rounding should include:

  1. do not round (exact)
  2. next 5 minute increment
  3. next 10 minute increment
  4. next 15 minute increment
  5. next half hour
  6. next hour
  7. next end of day (closing time)
  8. next beginning of day (opening time)

Another policy is necessary to handle the situation when calculated due times occur when the library is closed. Either the material is:

  1. not for loan
  2. due at the library’s closing
  3. due at the library’s next opening
  4. due at the library’s next opening plus however long the due time occurred after the previous closing (i.e. pause the loan period while the library is closed)
  5. due at the library’s next opening plus a fixed time

Examples of possible circulation situations and policies:


a material with a 3 hour loan period is checked out 1 hour before the library closes.

Possible policies:
  • The material is not for loan
  • The material is due at close
  • The material is due at the next open day
  • The material is due 2 hours after the next opening

a material with a 2 hour loan period is checked out at 2:23pm

Possible policies:
  • The material is due at exactly 4:23pm
  • The material is due at 4:30 or 5:00 (rounding to nearest 'nice' time as per circ policy)

A material with a 3 day loan period is checked out at 3:33pm on Monday

Possible policies:
  • The material is due at 3:33pm on Thursday
  • The material is due at close on Thursday
  • The material is due at opening on Friday

Overdue fine calculation

Overdue fine calculation will behave essentially the same way, except it will occur more frequently than the typical ‘once a night’ scheduling of files.pl. This script, or it’s updated analog, could be scheduled to run on cron every minute, or a daemon could be written to handle fine calculation on demand.

COMMENT: I favor using a daemon. This would effectively allow fines calculations in real time.-chris_n

After an item’s calculated due time plus the defined grace period, overdue fines will begin to accrue. The charges will increment by the fine amount again after the fine charging interval. Fine accrual will stop after the maximum fine value has been reached, or the item is returned, or the item is marked lost.

If a library utilizes patron suspension periods instead of or in addition to fines, the borrower will be marked as suspended for the defined suspension period after the item’s due time plus defined grace period

COMMENT: It would be nice to have a syspref to define the method of fining. This would allow us to hide the fields related to suspension periods or monitary fines (depending on the pref setting) in the view and make it less confusing to those who use a different method. -chris_n

Display of due dates and times

When displaying due dates and times in the OPAC, both the date and time will be shown. If the due time is at the library’s open or closing hour for that day, the time can be suppressed from displaying with a system preference.

In the staff client, due times will need to be shown not only in Circulation, but also in Patron reading history and the item’s circulation history.

Defining Library Hours

The library calendar should be moved from Tools to Administration, since it shall now be so vital to the library’s circulation policies.

Staff shall continue to be able to specify the specific branch they wish to work with.

The calendar shall have two different kinds of events that can be specified: Library Hours, and Exceptions. Library Hours shall include an opening time and a closing time. When configuring Library Hours, the staff members shall have the option to set the hours to repeat daily or weekly, until a specified end date. Future edits to Library Hours that were initial set up as repeating shall offer the option to propagate the changes to the rest of the pattern, or apply only to this day.

Exceptions shall be either one-off events or annually repeated (like holidays). They will specify an alternate opening and closing time for the day that will overwrite the value configured in Library Hours. Future changes to the Library Hours for that day will not effect the Exception unless the Exception is deleted

COMMENT: This would be a good time to clarify the terminoloy used in the calendar. Currently one must specify the weekends as holidays. This is a bit confusing. -chris_n


The system shall need to be able to take in Holds Effective Dates and Expiry Dates in periods of minutes, as well, to match the circulation options. This would allow students to indicate that a hold is not useful to them before their class gets out at 4pm, or after they have to take their mid-terms at 2:30pm. The time specification is optional, and will default to the library’s opening time for that date if it is not specified.

Similarly, Koha would need to be able to take in units other than days for automatically canceling expired or unfilled holds.


The current cronjob for messaging is set up to process advanced notices and overdues nightly, and queue those messages for processing by a script that runs hourly (by default). For loan periods of less than 1 day, we'd need something quicker to make notices worthwhile. For example, it would be nice to send patrons an SMS message (if they opt in for that) 5 minutes before a reserve book is due.

This means that either the message script will need to run every minute or so, or there needs to be a daemon. If the cron runs every minute, and goes off the EXACT due time for generating notices, the circulations will be spread out enough through the day to prevent there being any kind of pile-up (where the script takes longer than 1 minute to run). This could be a problem if a batch circulation was done for some reason...

COMMENT: Here again, I think a daemon would be the better choice. This avoides many potential issues including those mentioned above. -chris_n

A daemon would provide more on-demand messaging, but would be one additional process to initiate and maintain for Koha.

COMMENT: It might be possible to write one daemon to handle all of this housekeeping. -chris_n

An additional wrinkle comes with allowing users to define how far in advance they receive notices; having the option of '3 days' in advance doesn't do any good for a 2 hour loan, just as '5 minutes' in advance doesn't work for a 3 day loan. Either they'd need to be able to set both "longer term" and "shorter term" advanced notice preferences, or have the time in advance removed as an option for their configuration.

COMMENT: Perhaps have options for advanced notices on "hourly loans" and another on "daily loans," etc. (vs. "longer term" and "shorter term") -chris_n

This could easily be it’s own development project.

COMMENT: The development of a housekeeping daemon surely could! -chris_n

System Preferences

Several existing system preferences need to be changed in light of the new loan periods

  • dateformat -> needs to include HH::MM
  • TransfersMaxDaysWarning -> convert to minutes
  • ReservesMaxPickupDelay -> convert to minutes

Possible new system preferences:

  • FineMethod -> suspension, monitary
Personal tools