[Koha] Need help for a new calendar (performance improvement and library opening hours) BZ17015

[Francois Charbonnier]

Dear community,

We submitted a patch recently that would benefit many. It solves two old 
bug put on hold for a while (Move calculation code out of C4::Calendar) 
and (hourly loans doesn't know when library closed). If you a have a bit 
of time ahead of you to help us get it upstreamed. It will be much 
appreciated!

When I read again the description from bugzilla, I felt that an overview 
of the work and its benefits will help you get involved.
*
*_*Short version*_ :

The communinity and some of our clients noticed two issues :

1. Hour loans doesn't know when a library is closed
2. We have performance issues when checking in overdue book or managing 
overdue fines.

We identified that both issues are related to the way Koha does date 
calculation. To improve and fix these issues, we developped a new 
calendar with a couple of new features.

_The benefits of this new calendar are_ :

1. management of the libraries opening hours (new feature).
2. performance improvement when circulating items and managing fines. In 
particular, when checking in overdue book or managing overdue fines.
3. help to setup holidays/closed days from one year to another (new feature)

To acheive this, we redesigned the calendar database table and rewrote 
part of the code in charge of the date calculation. We used this work to 
move part of the code and separate what's in charge of the calendar and 
what's used to do the calculation.

This way, we solved two bugzilla issues opened a long time ago :
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=11211 (Move 
calculation code out of C4::Calendar) (opened by Jesse Weaver on the 
2013-11-06)
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=8133 (hourly 
loans doesn't know when library closed) (opended by Nicole C. Engard on 
the 2012-05-21)

For now, BZ 11211 blocked BZ 8133.

All features from the old calendar is available in the new calendar.

The new calendar passed all the unit tests.

The patch for the new calendar is here : 
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=17015
_*
*__*Long version*_ :

The calendar's database table contains only rules to set whether the 
library is closed or not. If Koha needs a date or a range of date (was 
the library closed that day? how long is this book overdue? etc.), it 
has to be calculated using these rules. Depending on the type of 
transactions, how Koha does the calculation is not always efficient. For 
example, a return of overdue books can take as long as many seconds (for 
2 months old overdues for example). We redesigned the calendar table to 
be able to give Koha the information it needs to do the calculation in a 
more efficient way.

In the calendar's new table, we don't store rules anymore. Each day from 
the calendar is now stored (an entry for each day). For each day, we can 
indicate if the library is open or closed. We took this redesign 
opportunity to add the library opening hours as well. That way, Koha 
gets straight the information it needs to determine if the library is 
open or not, it can take into consideration the opening hours (good for 
hour loans and the date range calculation is simplified by using the 
information stored in the database. No need to calculate it based on 
different rules anymore.

Among the patches we submitted, we have a script to benchmark checkin 
and checkout transactions. The benchmark of checkin is more indicative 
of the performance improvement. Here is an example of collected 
statistics. When an item is returned the day the checkout expires, the 
calculation time decreased of 22% (for 100 checkins, the calculation 
time drops from 52.2s to 40.7s). When an item is 2 months overdue and 
returned, the calculation time decreased of 70% (for 100 checkins, the 
calculation time drops from 154s to 46.6s).

_How does the new calendar work_ ?

Before the first use, a script will populate the new calendar table with 
on entry for each day of the year. This script can retreive your actual 
setting to keep track of your old set up. It also creates all the 
entries for future years. The basic set up would be : the library wants 
to have a 1 year overview of the calendar so they can set it up in 
advance. The script creates every entry in the table to be able to set 
up the calendar 1 year in advance.

Then, another script will be scheduled to run every day. This script 
will add a new entry for every day spent. In this manner, Koha keeps a 1 
year advance overview at all time.

The advantage of this last script is to help the koha admin to set up 
the calendar in advance. Each time the script will add a new entry (a 
new day), it will check one year in the past how the same day was set up 
to try to determine if the library should be closed or not :

- If the date is a unique holiday : the script will not keep it for the 
new entry.
- If the date is a repeatable holiday : the script will keep it. (For 
example, a library closed every saturday)
- If the day type was "floatting" (it's a new type of holiday) : the new 
entry status is "needs confirmation". Thus, when setting up the 
calendar, I have two options :
1. I know it's a repeatable holiday every year or very week, I choose 
the date type 'repeatable'. When the script add a new entry, it keeps 
the holiday.
2. I want to check the holiday every year to adjust the settings (for 
example, Easter stat holiday), I choose the new date type "floatting". 
Then, when the script add a new entry, it doesn't assume the library is 
closed but change the date status to "needs confirmation". Then I will 
be able to overview these "need confirmation" holidays and set them up 
when I get the information.

The script manage the opening hours as well. It checks the previous week 
settings instead of the previous year.

The other new feature to help setting up the calendar is in the way Koha 
can create holidays between two dates. When creating this range of 
dates, you can :

- either use a specific day and copy its settings to all the dates in 
the range.
- or use a range of dates and copy the settings of each day to each day 
of the new range.

Besides that, the calendar keeps all its actual features.

The patch for the new calendar is here : 
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=17015

Thank you very much!

François
-- 
François Charbonnier,
Bibl. prof. / Chef de produits

Tél.  : (888) 604-2627
francois.charbonnier at inLibro.com <mailto:francois.charbonnier at inLibro.com>

inLibro | Spécialistes en technologies documentaires | www.inLibro.com 
<http://www.inLibro.com>