Catalyst IT Recalls

= Description =
Developed by Aleisha Amohia, Catalyst IT 
Recalls can be thought of as high-priority reserves, with a few more conditions. Borrowers can recall items or records that they need urgently, but are currently checked out or awaiting pickup. Once the recall is confirmed, the borrower who currently has the item checked out will be notified that their due date has been adjusted and they need to return their item. Once recalled items are returned, the recall requester will be notified that their item is awaiting pickup at their specified pickup location. 
This has been written to be separate to reserves for a purpose - simply, it is a separate function to reserves. Being similar is not enough reason to share code. There would be a mess of confusing conditionals throughout the code, making it harder to expand, build upon, read and customise.
= Configuration and Setting Up =
=== Administration ===
The UseRecalls system preference must be enabled. This preference controls whether the recalls feature is enabled or not.
The RecallsMaxPickUpDelay system preference must also be set. This preference defines the maximum pickup period for waiting recalls. It is used when setting a recalled item to 'awaiting pickup' if there is no defined pickup period in the circulation rules. You can also view the recalls waiting for more than the value of this preference in Circulation.
The RecallsLog system preference can also be enabled to log recalls actions such as create, cancel, expire, overdue, fulfill.
Set the following relevant circulation rules: 
*Recalls allowed (count) 
*Recalls per record (count) 
*On shelf recalls allowed ( If any unavailable / If all unavailable ) 
*Recall due date interval (days) 
*Recall overdue fine amount 
*Recall pickup period (days)
There is a new user permission for patrons that may manage_recalls.
There are two cronjobs that can be enabled for managing recalls. We recommend these cronjobs be configured to run daily.
* /usr/share/koha/bin/cronjobs/recalls/expire_recalls.pl (expires recalls that have been awaiting pickup for longer than the recall pickup period, or have surpassed the manually set expiration date)
* /usr/share/koha/bin/cronjobs/recalls/overdue_recalls.pl (sets a recall as overdue if a recalled item has not been checked in by the adjusted due date)
Add email and/or SMS notices with the following codes: 
*PICKUP_RECALLED_ITEM
Date: <<today>>
<<borrowers.firstname>> <<borrowers.surname>>,
A recall that you requested on the following item: <<biblio.title>> / <<biblio.author>> (<<items.barcode>>) is now ready for you to pick up at <<recalls.branchcode>>. Please pick up your item by <<recalls.expirationdate>>.
Thank you!
*RETURN_RECALLED_ITEM
Date: <<today>>
<<borrowers.firstname>> <<borrowers.surname>>,
A recall has been placed on the following item: <<biblio.title>> / <<biblio.author>> (<<items.barcode>>). The due date has been updated, and is now <<issues.date_due>>. Please return the item before the due date.
Thank you!
 
Add a print notice with the following code:
*RECALL_REQUESTER_DET
Date: <<today>>
Recall for pickup at <<branches.branchname>>
<<borrowers.surname>>, <<borrowers.firstname>> (<<borrowers.cardnumber>>)
<<borrowers.phone>>
<<borrowers.streetnumber>> <<borrowers.address>>, <<borrowers.address2>>, <<borrowers.city>> <<borrowers.zipcode>>
<<borrowers.email>>
ITEM RECALLED
<<biblio.title>> by <<biblio.author>>
Barcode: <<items.barcode>>
Callnumber: <<items.itemcallnumber>>
Waiting since: <<recalls.waitingdate>>
Notes: <<recalls.recallnotes>>
=== Statuses ===
*R - Requested (a new recall request has been made and the item must be returned) 
*W - Waiting (a recalled item is awaiting pickup at the requester's chosen branch) 
*T - In transit (an item has been allocated to a recall and is in transit to the requester's chosen pickup branch) 
*O - Overdue (a recalled item is overdue to be returned) 
*F - Finished (a recalled item has been checked out to the recall requester, and the recall is complete) 
*E - Expired (the recall was not completed before a defined expiration date OR the recall requester failed to pick up their waiting recall within the pickup period) 
*C - Cancelled (the recall request was cancelled. Only requested or overdue recalls can be cancelled)
Recalls with a status of F, E or C also have an 'old' flag.
= Borrower Usage (OPAC) =
*Borrowers can request recalls through the OPAC. They can place biblio-level or item-level recalls. 
*They can view their recalls history opac-recalls.pl 
*They can view and cancel their current open recalls opac-user.pl
= Staff Usage (Staff Client) =
*Staff cannot currently place recalls. This is future work.
*Staff cannot set recalls as overdue. This is done via cronjob.
*Staff can allocate a recalled item as 'awaiting pickup' by checking it in
*The recall is fulfilled when the recalled item is checked out to the recall requester
*Slips about the recall requester can be printed when checking in a recalled item
*Notices are sent when an item is recalled and needs to be returned, and when a recalled item is ready to be picked up
== Where to view recalls ==
*Circulation -> Old recalls: all inactive recalls (recalls/recalls_old_queue.pl)
*Circulation -> Recalls queue: all active recalls (recalls/recalls_queue.pl)
**Available actions: cancel, expire, revert waiting status, cancel multiple, mark overdue
*Circulation -> Recalls to pull: recalls that could be fulfilled by available items (recalls/recalls_to_pull.pl)
**Available actions: cancel, cancel recall and return item to branch
*Circulation -> Recalls awaiting pickup: recalls awaiting pickup, and recalls awaiting pickup more then RecallsMaxPickUpDelay days (recalls/recalls_waiting.pl)
**Available actions: expire, revert waiting status
*Circulation -> Overdue recalls: recalled items that are overdue to be returned (recalls/recalls_overdue.pl)
**Available actions: cancel, cancel multiple
*Biblio -> Recalls: biblio's active recalls (recalls/request?biblionumber=X)
**Available actions: cancel, expire, revert waiting status, cancel multiple, mark overdue
*Patron -> Recalls tab: patron's active recalls (circ/circulation.pl?borrowernumber=X and members/moremember.pl?borrowernumber=X)
**Available actions: cancel, expire, revert waiting status, cancel multiple, mark overdue
*Patron -> Recalls history: all active and inactive recalls by this patron (members/recallshistory.pl?borrowernumber=X)
**Available actions: cancel, expire, revert waiting status, cancel multiple, mark overdue
* Log viewer: show all recalls create, cancel, expire, overdue and fulfill actions (tools/viewlog.pl)
== Available recall actions ==
ACTION: starting status -> final status
*cancel: requested (R) and overdue (O) recalls -> cancelled (C). Action logged
*expire: waiting (W) recalls -> expired (E). Action logged
*revert: waiting (W) recalls -> requested (R).
*cancel recall and return item to branch: in transit (T) recalls -> requested (R). Action logged
*overdue: requested (R) -> overdue (O).
= Recent Work and Test Plans =
*Biblio-level recalls for Waikato Institute of Technology 
*Checkin and checkout of recalls in Circulation for Toi Ohomai Institute of Technology 
*SMS notifications for recalls for Toi Ohomai Institute of Technology 
*Recalls bug fixes for Waikato Institute of Technology
*Post-go live recalls bugs fixes and enhancements for Waikato Institute of Technology
*Biblio-level recalls bugs fixes for Waikato Institute of Technology
*Recalls cronjobs and expiry fixes for Waikato Institute of Technology
*Overdue fines for bib-level recalls for Waikato Institute of Technology
*Fix recall due date calculation to use relevant checkout for Waikato Institute of Technology
*Allow override of recall when placing reserve for Waikato Institute of Technology
= Future Work =
*staff-side recalls 
*priority queue for recalls
*add a recalls toolbar with an export button
= Sponsors =
Thank you to the following organisations for sponsoring the development of this feature: 
*Toi Ohomai Institute of Technology 
*Waikato Institute of Technology 
*Catalyst IT