C4::Circulation - Koha circulation module
use C4::Circulation;
The functions in this module deal with circulation, issues, and returns, as well as general information about the library. Also deals with inventory.
$str = &barcodedecode($barcode, [$filter]);
Generic filter function for barcode string. Called on every circ if the System Pref itemBarcodeInputFilter is set. Will do some manipulation of the barcode for systems that deliver a barcode to circulation.pl that differs from the barcode stored for the item. For proper functioning of this filter, calling the function on the correct barcode string (items.barcode) should return an unaltered barcode. Barcode is going to be automatically trimmed of leading/trailing whitespaces.
The optional $filter argument is to allow for testing or explicit behavior that ignores the System Pref. Valid values are the same as the System Pref options.
$str = &_decode($chunk);
Decodes a segment of a string emitted by a CueCat barcode scanner and returns it.
FIXME: Should be replaced with Barcode::Cuecat from CPAN or Javascript based decoding on the client side.
($dotransfer, $messages, $iteminformation) = &transferbook({ from_branch => $frombranch to_branch => $tobranch, barcode => $barcode, ignore_reserves => $ignore_reserves, trigger => $trigger });
Transfers an item to a new branch. If the item is currently on loan, it is automatically returned before the actual transfer.
$fbr
is the code for the branch initiating the transfer. $tbr
is the code for the branch to which the item should be transferred.
$barcode
is the barcode of the item to be transferred.
If $ignore_reserves
is true, &transferbook
ignores reserves. Otherwise, if an item is reserved, the transfer fails.
$trigger
is the enum value for what triggered the transfer.
Returns three values:
is true if the transfer was successful.
is a reference-to-hash which may have any of the following keys:
BadBarcode
There is no item in the catalog with the given barcode. The value is $barcode
.
DestinationEqualsHolding
The item is already at the branch to which it is being transferred. The transfer is nonetheless considered to have failed. The value should be ignored.
WasReturned
The item was on loan, and &transferbook
automatically returned it before transferring it. The value is the borrower number of the patron who had the item.
ResFound
The item was reserved. The value is a reference-to-hash whose keys are fields from the reserves table of the Koha database, and biblioitemnumber
. It also has the key ResFound
, whose value is either Waiting
or Reserved
.
WasTransferred
The item was eligible to be transferred. Barring problems communicating with the database, the transfer should indeed have succeeded. The value should be ignored.
RecallPlacedAtHoldingBranch
A recall for this item was found, and the transfer has already been completed as the item's branch matches the recall's pickup branch.
RecallFound
A recall for this item was found, and the item needs to be transferred to the recall's pickup branch.
( $issuingimpossible, $needsconfirmation, [ $alerts ] ) = CanBookBeIssued( $patron, $barcode, $duedate, $inprocess, $ignore_reserves, $params );
Check if a book can be issued.
$issuingimpossible
and $needsconfirmation
are hashrefs.
IMPORTANT: The assumption by users of this routine is that causes blocking the issue are keyed by uppercase labels and other returned data is keyed in lower case!
$patron
is a Koha::Patron$barcode
is the bar code of the book being issued.$duedates
is a DateTime object.$inprocess
boolean switch$ignore_reserves
boolean switch$params
Hashref of additional parametersAvailable keys: override_high_holds - Ignore high holds onsite_checkout - Checkout is an onsite checkout that will not leave the library item - Optionally pass the object for the item we are checking out to save a lookup
Returns :
$issuingimpossible
a reference to a hash. It contains reasons why issuing is impossible. Possible values are :sticky due date is invalid
borrower gone with no address
borrower declared it's card lost
borrower debarred
barcode unknown
item is not for loan
item withdrawn.
item is restricted (set by ??)
$needsconfirmation
a reference to a hash. It contains reasons why the loan could be prevented, but ones that can be overriden by the operator.
Possible values are :
borrower has debts.
renewing, not issuing
issued to someone else.
reserved for someone else.
reserved and being transferred for someone else.
sticky due date is invalid or due date in the past
if the borrower borrows to much things
recalled by someone else
($returnallowed, $message) = CanBookBeReturned($item, $branch)
Check whether the item can be returned to the provided branch
$item
is a hash of item information as returned Koha::Items->find->unblessed (Temporary, should be a Koha::Item instead)$branch
is the branchcode where the return is taking placeReturns:
$returnallowed
is 0 or 1, corresponding to whether the return is allowed (1) or not (0)$message
is the branchcode where the item SHOULD be returned, if the return is not allowedused when syspref decreaseLoanHighHolds is active. Returns 1 or 0 to define whether the minimum value held in decreaseLoanHighHoldsValue is exceeded, the total number of outstanding holds, the number of days the loan has been decreased to (held in syspref decreaseLoanHighHoldsValue), and the new due date
&AddIssue($patron, $barcode, [$datedue], [$cancelreserve], [$issuedate])
Issue a book. Does no check, they are done in CanBookBeIssued. If we reach this sub, it means the user confirmed if needed.
$patron
is a patron object.$barcode
is the barcode of the item being issued.$datedue
is a DateTime object for the max date of return, i.e. the date due (optional). Calculated if empty.$cancelreserve
is 1 to override and cancel any pending reserves for the item (optional).$issuedate
is a DateTime object for the date to issue the item (optional). Defaults to today.AddIssue does the following things :
- step 01: check that there is a borrowernumber & a barcode provided - check for RENEWAL (book issued & being issued to the same patron) - renewal YES = Calculate Charge & renew - renewal NO = * BOOK ACTUALLY ISSUED ? do a return if book is actually issued (but to someone else) * RESERVE PLACED ? - fill reserve if reserve to this patron - cancel reserve or not, otherwise * RECALL PLACED ? - fill recall if recall to this patron - cancel recall or not - revert recall's waiting status or not * TRANSFERT PENDING ? - complete the transfert * ISSUE THE BOOK
my $loanlength = &GetLoanLength($borrowertype,$itemtype,branchcode)
Get loan length for an itemtype, a borrower type and a branch
my ($hardduedate,$hardduedatecompare) = &GetHardDueDate($borrowertype,$itemtype,branchcode)
Get the Hard Due Date and it's comparison for an itemtype, a borrower type and a branch
my $branch_cat_rule = GetBranchBorrowerCircRule($branchcode, $categorycode);
Retrieves circulation rule attributes that apply to the given branch and patron category, regardless of item type. The return value is a hashref containing the following key:
patron_maxissueqty - maximum number of loans that a patron of the given category can have at the given branch. If the value is undef, no limit.
patron_maxonsiteissueqty - maximum of on-site checkouts that a patron of the given category can have at the given branch. If the value is undef, no limit.
This will check for different branch/category combinations in the following order: branch and category branch only category only default branch and category
If no rule has been found in the database, it will default to the buillt in rule:
patron_maxissueqty - undef patron_maxonsiteissueqty - undef
$branchcode
and $categorycode
should contain the literal branch code and patron category code, respectively - no wildcards.
my $branch_item_rule = GetBranchItemRule($branchcode, $itemtype);
Retrieves circulation rule attributes that apply to the given branch and item type, regardless of patron category.
The return value is a hashref containing the following keys:
holdallowed => Hold policy for this branch and itemtype. Possible values: not_allowed: No holds allowed. from_home_library: Holds allowed only by patrons that have the same homebranch as the item. from_any_library: Holds allowed from any patron. from_local_hold_group: Holds allowed from libraries in hold group
This searches branchitemrules in the following order:
* Same branchcode and itemtype * Same branchcode, itemtype '*' * branchcode '*', same itemtype * branchcode and itemtype '*'
Neither $branchcode
nor $itemtype
should be '*'.
($doreturn, $messages, $iteminformation, $borrower) = &AddReturn( $barcode, $branch [,$exemptfine] [,$returndate] [,$skip_localuse ] );
Returns a book.
$barcode
is the bar code of the book being returned.$branch
is the code of the branch where the book is being returned.$exemptfine
indicates that overdue charges for the item will be removed. Optional.$return_date
allows the default return date to be overridden by the given return date. Optional.$skip_localuse
indicated that localuse should not be recorded. Optional.&AddReturn
returns a list of four items:
$doreturn
is true iff the return succeeded.
$messages
is a reference-to-hash giving feedback on the operation. The keys of the hash are:
BadBarcode
No item with this barcode exists. The value is $barcode
.
NotIssued
The book is not currently on loan. The value is $barcode
.
withdrawn
This book has been withdrawn/cancelled. The value should be ignored.
Wrongbranch
This book has was returned to the wrong branch. The value is a hashref so that $messages-
{Wrongbranch}->{Wrongbranch}> and $messages-
{Wrongbranch}->{Rightbranch}> contain the branchcode of the incorrect and correct return library, respectively.
ResFound
The item was reserved. The value is a reference-to-hash whose keys are fields from the reserves table of the Koha database, and biblioitemnumber
. It also has the key ResFound
, whose value is either Waiting
, Reserved
, or 0.
WasReturned
Value 1 if return is successful.
NeedsTransfer
If AutomaticItemReturn is disabled, return branch is given as value of NeedsTransfer.
RecallFound
This item can fill a recall. The recall object is returned. If the recall pickup branch differs from the branch this item is being returned at, RecallNeedsTransfer
is also returned which contains this branchcode.
TransferredRecall
This item has been transferred to this branch to fill a recall. The recall object is returned.
$iteminformation
is a reference-to-hash, giving information about the returned item from the issues table.
$borrower
is a reference-to-hash, giving information about the patron who last borrowed the book.
MarkIssueReturned($borrowernumber, $itemnumber, $returndate, $privacy, [$params] );
Unconditionally marks an issue as being returned by moving the issues
row to old_issues
and setting returndate
to the current date.
if $returndate
is specified (in iso format), it is used as the date of the return.
$privacy
contains the privacy parameter. If the patron has set privacy to 2, the old_issue is immediately anonymised
Ideally, this function would be internal to C4::Circulation
, not exported, but it is currently used in misc/cronjobs/longoverdue.pl and offline_circ/process_koc.pl.
The last optional parameter allos passing skip_record_index to the item store call.
_debar_user_on_return($patron, $item, $datedue, $returndate);
$patron
patron object
$item
item object
$datedue
date due DateTime object
$returndate
DateTime object representing the return time
Internal function, called only by AddReturn that calculates and updates the user fine days, and debars them if necessary.
Should only be called for overdue returns
Calculation of the debarment date has been moved to a separate subroutine _calculate_new_debar_dt to ease testing.
&_FixOverduesOnReturn($borrowernumber, $itemnumber, $exemptfine, $status);
$borrowernumber
borrowernumber
$itemnumber
itemnumber
$exemptfine
BOOL -- remove overdue charge associated with this issue.
$status
ENUM -- reason for fix [ RETURNED, RENEWED, LOST, FORGIVEN ]
Internal function
my $circ_control_branch = _GetCircControlBranch($item, $patron);
Internal function :
Return the library code to be used to determine which circulation policy applies to a transaction. Looks up the CircControl and HomeOrHoldingBranch system preferences.
$item
is an item object.
$patron
is a patron object.
my $upcoming_dues = GetUpcomingDueIssues( { days_in_advance => 4 } );
($ok,$error,$info) = &CanBookBeRenewed($patron, $issue, $override_limit, $cron);
Find out whether a borrowed item may be renewed.
$patron
is the patron who currently has the issue.
$issue
is the checkout to renew.
$cron
true or false, specifies if this check is being made by the automatic_renewals.pl cronscript
$override_limit
, if supplied with a true value, causes the limit on the number of times that the loan can be renewed (as controlled by the item type) to be ignored. Overriding also allows to renew sooner than "No renewal before" and to manually renew loans that are automatically renewed.
$CanBookBeRenewed
returns a true value if the item may be renewed. The item must currently be on loan to the specified borrower; renewals must be allowed for the item's type; and the borrower must not have already renewed the loan. $error will contain the reason the renewal can not proceed $info will contain a hash of additional info currently 'soonest_renew_date' if error is 'too soon'
$new_date_due = AddRenewal({ borrowernumber => $borrowernumber, itemnumber => $itemnumber, branch => $branch, [datedue => $datedue], [lastreneweddate => $lastreneweddate], [skipfinecalc => $skipfinecalc], [seen => $seen], [automatic => $automatic], [skip_record_index => $skip_record_index] });
Renews a loan, returns the updated due date upon success.
$borrowernumber
is the borrower number of the patron who currently has the item.
$itemnumber
is the number of the item to renew.
$branch
is the library where the renewal took place (if any). The library that controls the circ policies for the renewal is retrieved from the issues record.
$datedue
can be a DateTime object used to set the due date.
$lastreneweddate
is an optional ISO-formatted date used to set issues.lastreneweddate. If this parameter is not supplied, lastreneweddate is set to the current date.
$skipfinecalc
is an optional boolean. There may be circumstances where, even if the CalculateFinesOnReturn syspref is enabled, we don't want to calculate fines upon renew, for example, when we're renewing as a result of a fine being paid (see RenewAccruingItemWhenPaid syspref)
If $datedue
is the empty string, &AddRenewal
will calculate the due date automatically from the book's item type.
$seen
is a boolean flag indicating if the item was seen or not during the renewal. This informs the incrementing of the unseen_renewals column. If this flag is not supplied, we fallback to a true value
$automatic
is a boolean flag indicating the renewal was triggered automatically and not by a person ( librarian or patron )
$skip_record_index
is an optional boolean flag to indicate whether queuing the search indexing should be skipped for this renewal.
$NoRenewalBeforeThisDate = &GetSoonestRenewDate($patron, $issue);
Find out the soonest possible renew date of a borrowed item.
$patron
is the patron who currently has the item on loan.
$issue
is the the item issue.
$is_auto
is this soonest renew date for an auto renewal?
$GetSoonestRenewDate
returns the DateTime of the soonest possible renew date, based on the value "No renewal before" of the applicable issuing rule. Returns the current date if the item can already be renewed, and returns undefined if the patron, item, or checkout cannot be found.
$NoAutoRenewalAfterThisDate = &GetLatestAutoRenewDate($patron, $issue);
Find out the latest possible auto renew date of a borrowed item.
$patron
is the patron who currently has the item on loan.
$issue
is the item issue.
$GetLatestAutoRenewDate
returns the DateTime of the latest possible auto renew date, based on the value "No auto renewal after" and the "No auto renewal after (hard limit) of the applicable issuing rule. Returns undef if there is no date specify in the circ rules or if the patron, loan, or item cannot be found.
($charge, $item_type) = &GetIssuingCharges($itemnumber, $borrowernumber);
Calculate how much it would cost for a given patron to borrow a given item, including any applicable discounts.
$itemnumber
is the item number of item the patron wishes to borrow.
$borrowernumber
is the patron's borrower number.
&GetIssuingCharges
returns two values: $charge
is the rental charge, and $item_type
is the code for the item's item type (e.g., VID
if it's a video).
&AddIssuingCharge( $checkout, $charge, $type )
@results = GetTransfersFromTo($frombranch,$tobranch);
Returns the list of pending transfers between $from and $to branch
Send out a check-in
or checkout
alert using the messaging system.
Parameters:
Valid values for this parameter are: CHECKIN
and CHECKOUT
.
Hashref of information about the item being checked in or out.
Hashref of information about the borrower of the item.
The branchcode from where the checkout or check-in took place.
Example:
SendCirculationAlert({ type => 'CHECKOUT', item => $item, borrower => $borrower, branch => $branch, });
$newdatedue = CalcDateDue($startdate,$itemtype,$branchcode,$borrower);
this function calculates the due date given the start date and configured circulation rules, checking against the holidays calendar as per the daysmode circulation rule. $startdate
= DateTime object representing start date of loan period (assumed to be today) $itemtype
= itemtype code of item in question $branch
= location whose calendar to use $patron
= Patron object $isrenewal
= Boolean: is true if we want to calculate the date due for a renewal. Else is false.
$allowed = IsBranchTransferAllowed( $toBranch, $fromBranch, $code );
Code is either an itemtype or collection doe depending on the pref BranchTransferLimitsType
Deprecated in favor of Koha::Item::Transfer::Limits->find/search and Koha::Item->can_be_transferred.
CreateBranchTransferLimit( $toBranch, $fromBranch, $code );
$code is either itemtype or collection code depending on what the pref BranchTransferLimitsType is set to.
Deprecated in favor of Koha::Item::Transfer::Limit->new.
my $result = DeleteBranchTransferLimits($frombranch);
Deletes all the library transfer limits for one library. Returns the number of limits deleted, 0e0 if no limits were deleted, or undef if no arguments are supplied.
Deprecated in favor of Koha::Item::Transfer::Limits->search({ fromBranch => $fromBranch })->delete.
LostItem( $itemnumber, $mark_lost_from, $force_mark_returned, [$params] );
The final optional parameter, $params
, expected to contain 'skip_record_index' key, which relayed down to Koha::Item/store, there it prevents calling of ModZebra index_records, which takes most of the time in batch adds/deletes: index_records better to be called later in additem.pl
after the whole loop.
$params: skip_record_index => 1|0
TransferSlip($user_branch, $itemnumber, $barcode, $to_branch) Returns letter hash ( see C4::Letters::GetPreparedLetter ) or undef
CheckIfIssuedToPatron($borrowernumber, $biblionumber) Return 1 if any record item is issued to patron, otherwise return 0
IsItemIssued( $itemnumber ) Return 1 if the item is on loan, otherwise return 0
my $ageRestriction = GetAgeRestriction($record_restrictions);
@PARAM1 the koha.biblioitems.agerestriction value, like K18, PEGI 13, ... @RETURNS The age restriction age in years.
Koha Development Team <http://koha-community.org/>