Library opening hours and term loans RFC

RFC: Opening hours and term due dates

This RFC covers two distinct enhancements. The first, opening hours, would let the administrator specify what hours the library is open. This would affect several due times for hourly and overnight loans and fine calculations for hourly loans.

Since some libraries stay open past midnight, the enhancement would also introduce the notion of a library service day that can be different from a calendar day. In other words, if a library is open from 8 a.m. to 2 a.m., items returned at 1 a.m. could be considered to have been returned the previous day. The next service day would not start until the library opens again at 8 a.m.

For a consortial Koha user that has libraries in more than one time zone, it would be possible to specify a time zone associated with each branch. Opening hours would be displayed relative to each branch's time zone.

The second part of this RFC, term due dates, would give an academic library (e.g.) the ability to specify the start and end dates of their terms, then establish term loan circulation policies. For example, if a library's autumn term runs from August 31 to December 15, the library would be able to define a term loan circulation policy that sets December 15 as the due date for all loans made during the term. This type of loan policy would be part of the circulation policy matrix, thus making it possible to give faculty term loans but only give undergraduates normal 3-week loans.

Details for opening hours and term due dates RFC

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

Overview

This specification changes the calendar system in Koha to support terms and more complex opening hours. It also adds a term due date that administrators can use for circulation purposes.

Many libraries are open after midnight, but do not consider the period of the day after midnight to be part of the following library service day for purposes of fine and fee accrual, circulation transaction calculations, and so on.

One particular problem arises when libraries provide overnight hourly loans—if a patron borrows an hourly item at 1:00 AM, and the library’s policies make it due by 10:00 AM the next day, then the system should use the next library service day, not the next calendar day (the next calendar day after a 1:00 AM loan is actually a full day away.)

Many libraries are open on a term basis, where the library’s hours vary during academic terms—typically there are fewer service hours during periods where the campus is closed. (Public libraries sometimes have shorter or longer hours during the summer or winter as well.) Typically these changes are not associated with a predictable date in the calendar, but are instead decided by campus administrators, so library administrators need to be able to adjust library open hours as appropriate as decisions are made.

As part of the term system, many libraries want to be able to set policies that allow patrons to have items on loan until a specific date in the term. For instance, students working on theses may have loans that run until the end of the term so they don’t need to keep renewing the items they are using for research. Some institutions allow students to borrow materials over a break with a single fixed due date when the break is over.

In addition, each branch will have a time zone associated with it. This will allow different branches to be in different time zones, and for a branch to have a different time zone than the koha user on the server uses.

Pre-Existing Functionality

Each branch has a calendar in Koha. The calendar operates on a daily basis, and has no provision for open and closing hours—in previous versions the branch was either open or closed on a given day. (By default the library was assumed to be open—exceptions were stored in the special_holidays and repeatable_holidays tables.) There is no default calendar for the whole system.

In previous versions, there was no facility for hourly loans, but this will be added to Koha soon. This feature assumes Koha has hourly loan capability and that circulation policies and due dates may include hourly intervals, and that fine calculation also may take place on an hourly basis. (Without hourly loans this feature does not make much sense.) Branches could be set to be closed for an individual day, the same day every week, or the same day annually. Exceptions could be added to bypass those rules, so for instance the library could be closed every Sunday, but open on Sunday during finals week.

Requirements / Description

Basic Branch Calendars with hours

As in previous releases, each Koha branch may have its own calendar.

Within each calendar, administrators will be able to specify basic opening and closing hours for each day.

Administrators may decide how long after midnight to extend the library service day. The closing hours for a day may extend later than the calendar day by up to 24 hours. In other words, it will be possible to extend the library’s Monday service day any time during the following Tuesday. The administrator must specify an opening hour as well, but this must occur during the calendar day (after midnight/0:00 in the morning.)
Opening hours may not overlap between days, so if, for instance, the library’s Monday service day is extended until 4:00 AM, the library may not begin the Tuesday service day until 4:01 AM.
The basic interface will be geared toward setting up the hours for each day of the week.
If no opening and closing hours are specified, the library will be assumed to be open from midnight until 11:59 PM/23:59 (the day begins at 0:00 and ends at 23:59). Institutions that are open continuously and keep calendar days should use this, and it should work correctly for libraries that do not use any kind of hourly loan.

Exception days

Administrators may set up recurring or individual exception days.

Exception days have different hours than the hours that the basic weekly calendar indicates.
Recurring exception days may be set up to recur annually, based on calendar date.
Any exception day may not have its hours overlap another day when the library is open. This should be checked at the point the exception day is established, and also when the basic calendar is edited.
The user interface will provide a means of setting up large blocks of individual exception dates, for instance to indicate that the library has special hours over the summer and winter academic breaks. Typically the library’s hours vary by day of the week within a range of dates, so it should be possible to specify that, between a beginning and ending date, the hours for each of the 7 days of the week, and have all those exception dates set in one operation.

Term Due dates

Administrators will be able to set up one or more “Term Due Dates.” These due dates will be independent of the branch calendars. Each set of Term due dates will work as follows:

Each set of term due dates will have a name (the name will be used to add the term due date to a circulation policy).
Each set of term due dates will contain a sequence of triplets of dates—a fixed due date, and a date after which this fixed due date is to be applied, and a date after which the term due date will no longer be applied.
Administrators will be able to add a set of term due dates to a circulation policy, alongside an ordinary interval-based circulation policy.
If a circulation policy has a set of term due dates associated with it, and a transaction occurs between the beginning date and the end date, then the fixed due date will be used. Otherwise the ordinary circulation transaction policy will be used.
So for instance, if a library wanted to ensure that books were due at the beginning of the next term when they are loaned close to the end of the term, but circulate normally before that, they could use the following set of term due dates, assuming that the term ends towards the end of December and May and picks up again around the middle of March and the end of August. Patrons who borrow items towards the end of the break will get their ordinary circulation policies:

For items charged after:	Until:	Use due date:
December 15, 2007	January 10, 2008	January 15, 2008
May 15, 2008	August 15, 2008	August 31, 2008
December 12, 2008	January 13, 2009	January 20, 2009
May 17, 2009	August 20, 2009	September 1, 2009
(And so on)

It’s possible to set up a circulation policy that uses term loan sets entirely, for instance for adjunct faculty for whom all items are due at the end of term. If the beginning and ending dates for a term loan set have no gaps, then the term loan set will cover all the possible circulation dates.

Calculating loan periods and fines

When calculating loan periods and fines, any process that uses a daily interval must take “Library Days” into account, rather than calendar days. That means that for every date that is used in the process, the date must be resolved against the calendar to ensure that it belongs to the correct library day. So for instance, if:

A calendar is in effect that extends each weekday until 2:00 A.M, while the library opens up again at 7:00 A.M. for the rest of the day.
A patron borrows a book with a two-day loan period at 1:00 AM on Tuesday—part of the “Monday” library service day. The book will be due on Wednesday.
The patron returns the book on Thursday at 8:00 A.M. The patron is now liable for one day of overdue fines, because the book was due on Wednesday.
If alternately the patron returns the item at 1:30 AM on Thursday, they would not have been liable for the fine because they would have been within the two-day limit. 1:30 AM on Thursday is part of the Wednesday library service day.
Note that using the number of hours between loan and return is not enough to get the calculation right—the patron could have kept the item for 48 ½ hours and not paid a fine in the example above.
Each day-based date computation must take library service days into account-in the above the item was loaned on Monday and returned on Thursday for a difference of three days.

Time zone settings

Each branch will be able to set its time zone independently. At installation or upgrade, branch time zones will be set to match the time zone of the user who is installing or upgrading Koha. After upgrade, it will be possible to reset the time zone setting for a branch to use a different time zone. The timezone supplied must be have time zone information database available on the server.

Once the time zone has been set for a branch, it is possible that its interactions with other branches may need time zone correction. For instance, it’s possible that items transferred from one branch to another may arrive earlier than they left, according to the local times at each branch. Time zone handling should be used to avoid these problems.

For circulation transactions the time zone in effect should follow the branch where the circulation transaction is taking place, even if, for instance, the patron or item is from a branch with a different time zone.

The main area where time zone handling is important is in the case when the time zone of the branch is different from the time zone of the Koha user or database—the clock time must be adjusted for all of these to be sure that the application is using the right time for its calculations.

For this to work, we must be sure that the times stored in the underlying database are consistent—they should be stored as UTC times or be qualified with time zones, not as the local time for the branch.

Security and Privileges

In previous versions of Koha, editing calendars was linked to the “tools” permission. Tools permissions are being reorganized in a separate project—editing the calendar will be controlled by permissions defined by that project.

Open Questions and notes

Fine calculations take place using a script that is run after midnight, calendar time. If fine calculations must take hourly loans and a more complex calendar into account, then this job must be run after the end of the library day, not after midnight. (So for instance, if the library closes at 2:00 AM, the fine job should run at 2:01 A.M. or later.)

In some respects term loans work like the desired functionality for overnight loans—after a certain point, a fixed due time is applied. There are three differences: the granularity of the timing—term loans work on days; the repeatability—term loans work on specific days while overnight loans are more repeatable; and that the desired overnight loan functionality is not attached to specific patron categories.