Hourly circulation policies RFC

Overlap with : http://wiki.koha-community.org/wiki/Hourly_Loans_RFC

This page/RFC won't probably be implemented (it's an old LL proposal)

RFC: Hourly circulation policies

Koha 3's circulation loans are currently measured only in units of days. However, because some libraries perform loans that are measured in minutes or hours, particularly for course reserves and short loans, LibLime proposes to add support for measuring loan periods in time intervals shorter than a day. This support will be a new feature although it may draw on work that Near Eastern University has done for Koha 2.

The main changes will include:

• adding columns to issuingrules to specify whether the loan time,

,grace period, and charging (fining) interval are measure in units of days, hours, or minutes

• adding the ability to define a policy for an overnight loan, i.e., a loan that is due the following day at a defined time.
• adding display of due times
• adding the ability to calculate custom shot glasses overdue fines on an hourly basis

This RFC refers to several other RFCs that have been sent or will be sent soon, including

• System groups
• Opening hours
• Recalls

Additional specifications for hourly circulation policies

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

Overview

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. These policies will work in tandem with new calendars that allow the library to express their opening and

closing times in hours. 

Pre-Existing Functionality

Koha supports loan and fine periods measured in complete days only. Although Near East University in Cyprus is known to have developed a separate system that supports hourly loans, that has not been implemented in Koha 3.

The basic Koha infrastructure in previous releases determines loan periods and fine rates based on the branch, patron category and item type for each transaction. Administrators may define default values that are used when a more specific value is not available—so when no specific policy for a branch is used, the default branch policies are used. There are also defaults for patron category and item type. The specific branch that is used in the transaction can be configured globally to be any of the patron’s home branch, the item’s home branch, or the branch where the circulation desk is taking place. This infrastructure will not be changed by the hourly circulation policies project.

Fines are calculated based on an initial fine and a further loan cycle, so that the initial fine amount is added after the item becomes overdue and a further interval passes, then the fine is reapplied according to a cycle.

The administrative user interface for fine rules (in finesrules.pl) and for issuing rules (in issuingrules.pl) allows administrators to enter policies by entering several values at once, separated by commas. For instance, for issuing rules, the administrator can enter “21,5” to indicate that the loan period is 21 days, with 5 possible loans. This is a good quick way to do things, but becomes a lot more complicated when setting up policies that are more complex. Once units are included in the calculation, it becomes harder to make this work, because each value has its own unit calculation.

As part of ongoing development, a “System Groups” feature is being added to Koha—this feature will make it possible to group and separate multiple branches so that they inherit policies from each other, or are insulated from each other. This project will not be changed by the hourly circulation policies project.

The Koha calendaring system works in days, not in hours, so it is not possible to say that a branch opens or closes at specific times of day, only that the branch is open or closed on a given day. This is changing in Koha as part of the opening hours project—that project depends on this one. In particular, fine and fee calculation becomes more complicated in the presence of complex calendars—that change is detailed in the specification for opening hours.

As part of ongoing development, term loan functionality is being added to Koha—term loans are circulation policies that, for a given branch, patron category and item type, automatically assign a fixed due date. This kind of policy is an alternative to the other kinds of circulation policies—if term loans are in effect for a transaction, there is no calculated charge period, instead a fixed due date is assigned.

Recalls are also being added to Koha, with their own circulation policies. The recalls project depends on this one. It will be possible to express recall limits and intervals in hours or minutes as well. (It may be difficult for libraries to get recall notices to people on an hourly basis, but we will support the hourly policies.)

The actual circulation policies are stored in the issuingrules table. The key columns are:

|issuelength|The length of time that an item is loaned for.| |fine|The base fine rate.| |chargeperiod|the interval between applying the fine rate for overdue items.| |firstremind|the period an item can be overdue without any overdue fines being applied. | |maxissueqty|how many times an item can be loaned.|

Note that chargeperiod is not the loan period—‘issue’ means loan, ‘charge’ means fine.

Note also that the overduerules table contains trigger information for sending overdue notices, not overdue policies.

When fines are recalculated, the Koha assumes the values in issuingrules are expressed in days at this time.

Overdue fines are calculated as follows:

Once the item is overdue and the grace period (firstremind) has elapsed, the fine is applied once.

Every time the chargeperiod elapses after the grace period is over, apply the fine amount again.

A script called fines2.pl is intended to run periodically to calculate and apply accrued overdue fines.

Note that the fine rate does not include a unit of time—it is assessed per chargeperiod. Chargeperiod uses a unit of days now, but will change to include an explicit unit (day, hour or minute) in the future.

Requirements

New units for circulation policies

It will be possible for administrators to express the following policies in several different kinds of unit:

1. Loan time. This corresponds to the issuingrules.issuelength column.
2. Grace Period. This corresponds to the issuingrules.firstremind column.
3. Charging Interval. This corresponds to the issuingrules.chargeperiod column.

(The labels here match the ones on smart-rules.pl—the labels are different on some of the other forms by default.)

The possible units will be:

1. Days.
2. Hours
3. Minutes

Forms on which circulation polices are established

Circulation policies are established on the following forms:

1. issuingrules.pl,
2. smart-rules.pl
3. finesrules.pl

On each of these forms, it must be possible to express loan periods and fine rates in days, hours or minutes. The pre-existing forms do not have any drop-down menus to indicate the type of unit—these forms will be enhanced to contain drop-down menus listing the units. The unit type will default to “days” to be consistent with the behavior of previous versions. The browser will make it possible to control the drop-down menus using the keyboard so it will be possible to set up these policies using the keyboard.

On the issuing Rules form, issuingrules.pl, each cell in the table will have two text fields with a units dropdown, replacing the single text field in previous releases. The first text field will contain the loan period/issuelength, with a units drop-down, and the second text field will contain the number of loans allowed/maxissues.

On the fines rules form, finesrules.pl, each cell in the table will have three text fields, with two units dropdowns, replacing the single text field in previous releases. The first text field will contain the amount, the second text field will contain the grace period/firstremind with a units drop-down, and the second text field will contain the charging interval/chargeperiod.

Overdue fine calculation

At a high level, fine and fee calculation will use the same principles as in the past, except that the various policies may be expressed in units of time other than calendar days. (Note that the introduction of Opening Hours support also complicates overdue fine calculation.) The major difference has to do with the actual times used to make the fine calculations—in previous releases, fine calculations were granular to the day, whereas now they will be granular to the hour or minute, depending on the units used to set up the circulation policies.

If some parts of the circulation policy for a given charge use different units, for instance the loan period is expressed in days but the overdue fine policy is expressed in hours, then the following rules will apply:

A policy using days will be considered to run until the end of the day (23:59) if it is necessary to compare it in date calculations using hours or minutes. For instance, an item that becomes overdue using a day-based due date, but that is fined on a 2-hour cycle, will be treated as if it became overdue at 23:59 on the day that it was due.

A policy using hours will be considered to run until the end of the hour (minute 59) if it is necessary to compare it in date calculations using minutes.

A policy using minutes will be considered to run until the end of the hour if it is necessary to compare it in date calculations using hours.

A policy using minutes or hours will be considered to run until the end of the day if it is necessary to compare it in date calculations with days.

Overnight loan policies

For specific item type and patron category combinations, administrators will be able to specify that the item type and patron category are eligible for overnight loan. Like the other borrowing parameters, it will be possible to adjust this policy by branch, with a default setting that will apply if a specific branch does not have a policy.

To keep the interface manageable, administrators will specify these parameters in a separate form from the other loan policies. Administrators will only be able to specify overnight loans policies for patron categories and item types that already have hourly or minute-based loan policies already defined.

When an administrator changes a loan policy from hourly or minute-based to day-based, or deletes the policy altogether, then any overnight loan policy associated with the loan policy will be deleted.

If a patron category and item type are eligible for overnight loan, then administrators must provide:

Overnight loan window begins. The number of hours or minutes before closing that the overnight loan is available.

Overnight loan due time. The number of hours or minutes after opening that the overnight loan is due.

Overnight loans over closed days. Whether the overnight loan will be available if the library is closed the next day.

Overnight loan due time calculation

By default when a patron tries to borrow an item, and the applicable circulation policy makes the item due after closing time, the due time will be shortened to the library’s closing time.

If the applicable circulation policy allows overnight loans then things will work as follows:

On a given day, the overnight loan window opens for a given transaction when the current time passes the closing time according to the calendar minus the “overnight loan window begins” parameter.

The overnight due time for a given transaction will be determined as follows:

1. If “Overnight loans over closed days” is true, the opening time the next day the library is open, plus the “overnight loan due time” parameter.
2. If “Overnight loans over closed days” is false,
   1. and the library is closed the next day, then the overnight due time will be the library’s closing time.
   2. If the library is open the next day, then the overnight due time will be the library’s opening time the next day, plus the “overnight loan due time” parameter.

Overdue notices and alerts

It will be possible to generate overdue notices and alerts on a shorter basis than daily—it should be possible to run the notice process at least once an hour so that email and SMS messages are sent out through the day. Also, it’s desirable to split the notices up by format, so that email and SMS messages are sent hourly, but paper notices wait until a daily batch job runs.

Display of due dates and times in the public catalog and staff interface

1. When displaying due dates and times in the public catalog, if a due date is calculated using an hourly or minute-based loan period, then the time that the item is due will display.
2. If a due date is calculated using a day-based loan period, then the time the item is due will not display—only the date. (Showing the time that the library closes on the due date can be confusing, so we only show the date.)

Open Questions and notes

Overnight loans are tricky—it may be too much administration to set these at the patron category/item type level, but we must at least take item type into account. Also, it makes some sense to set these up in the calendar, so it’s possible to make overnight loans do later after opening on the weekend or something. As written, every day has the same overnight loan policies.