3 # Copyright ByWater Solutions 2014
5 # This file is part of Koha.
7 # Koha is free software; you can redistribute it and/or modify it
8 # under the terms of the GNU General Public License as published by
9 # the Free Software Foundation; either version 3 of the License, or
10 # (at your option) any later version.
12 # Koha is distributed in the hope that it will be useful, but
13 # WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 # GNU General Public License for more details.
17 # You should have received a copy of the GNU General Public License
18 # along with Koha; if not, see <http://www.gnu.org/licenses>.
23 use List::MoreUtils qw(any);
28 use Koha::DateUtils qw( dt_from_string );
33 use C4::ClassSource; # FIXME We would like to avoid that
34 use C4::Log qw( logaction );
37 use Koha::CirculationRules;
38 use Koha::SearchEngine::Indexer;
39 use Koha::Item::Transfer::Limits;
40 use Koha::Item::Transfers;
45 use Koha::StockRotationItem;
46 use Koha::StockRotationRotas;
48 use base qw(Koha::Object);
52 Koha::Item - Koha Item object class
64 $params can take an optional 'skip_record_index' parameter.
65 If set, the reindexation process will not happen (index_records not called)
67 NOTE: This is a temporary fix to answer a performance issue when lot of items
68 are added (or modified) at the same time.
69 The correct way to fix this is to make the ES reindexation process async.
70 You should not turn it on if you do not understand what it is doing exactly.
76 my $params = @_ ? shift : {};
78 my $log_action = $params->{log_action} // 1;
80 # We do not want to oblige callers to pass this value
81 # Dev conveniences vs performance?
82 unless ( $self->biblioitemnumber ) {
83 $self->biblioitemnumber( $self->biblio->biblioitem->biblioitemnumber );
86 # See related changes from C4::Items::AddItem
87 unless ( $self->itype ) {
88 $self->itype($self->biblio->biblioitem->itemtype);
91 my $today = dt_from_string;
92 my $plugin_action = 'create';
94 unless ( $self->in_storage ) { #AddItem
95 unless ( $self->permanent_location ) {
96 $self->permanent_location($self->location);
98 unless ( $self->replacementpricedate ) {
99 $self->replacementpricedate($today);
101 unless ( $self->datelastseen ) {
102 $self->datelastseen($today);
105 unless ( $self->dateaccessioned ) {
106 $self->dateaccessioned($today);
109 if ( $self->itemcallnumber
110 or $self->cn_source )
112 my $cn_sort = GetClassSort( $self->cn_source, $self->itemcallnumber, "" );
113 $self->cn_sort($cn_sort);
116 logaction( "CATALOGUING", "ADD", $self->itemnumber, "item" )
117 if $log_action && C4::Context->preference("CataloguingLog");
121 $plugin_action = 'modify';
123 my %updated_columns = $self->_result->get_dirty_columns;
124 return $self->SUPER::store unless %updated_columns;
126 # Retrieve the item for comparison if we need to
128 exists $updated_columns{itemlost}
129 or exists $updated_columns{withdrawn}
130 or exists $updated_columns{damaged}
131 ) ? $self->get_from_storage : undef;
133 # Update *_on fields if needed
134 # FIXME: Why not for AddItem as well?
135 my @fields = qw( itemlost withdrawn damaged );
136 for my $field (@fields) {
138 # If the field is defined but empty or 0, we are
139 # removing/unsetting and thus need to clear out
141 if ( exists $updated_columns{$field}
142 && defined( $self->$field )
145 my $field_on = "${field}_on";
146 $self->$field_on(undef);
148 # If the field has changed otherwise, we much update
150 elsif (exists $updated_columns{$field}
151 && $updated_columns{$field}
152 && !$pre_mod_item->$field )
154 my $field_on = "${field}_on";
156 DateTime::Format::MySQL->format_datetime(
163 if ( exists $updated_columns{itemcallnumber}
164 or exists $updated_columns{cn_source} )
166 my $cn_sort = GetClassSort( $self->cn_source, $self->itemcallnumber, "" );
167 $self->cn_sort($cn_sort);
171 if ( exists $updated_columns{location}
172 and $self->location ne 'CART'
173 and $self->location ne 'PROC'
174 and not exists $updated_columns{permanent_location} )
176 $self->permanent_location( $self->location );
179 # If item was lost and has now been found,
180 # reverse any list item charges if necessary.
181 if ( exists $updated_columns{itemlost}
182 and $updated_columns{itemlost} <= 0
183 and $pre_mod_item->itemlost > 0 )
185 $self->_set_found_trigger($pre_mod_item);
189 logaction( "CATALOGUING", "MODIFY", $self->itemnumber, "item " . Dumper($self->unblessed) )
190 if $log_action && C4::Context->preference("CataloguingLog");
193 unless ( $self->dateaccessioned ) {
194 $self->dateaccessioned($today);
197 my $result = $self->SUPER::store;
198 my $indexer = Koha::SearchEngine::Indexer->new({ index => $Koha::SearchEngine::BIBLIOS_INDEX });
199 $indexer->index_records( $self->biblionumber, "specialUpdate", "biblioserver" )
200 unless $params->{skip_record_index};
201 $self->get_from_storage->_after_item_action_hooks({ action => $plugin_action });
212 my $params = @_ ? shift : {};
214 # FIXME check the item has no current issues
215 # i.e. raise the appropriate exception
217 my $indexer = Koha::SearchEngine::Indexer->new({ index => $Koha::SearchEngine::BIBLIOS_INDEX });
218 $indexer->index_records( $self->biblionumber, "specialUpdate", "biblioserver" )
219 unless $params->{skip_record_index};
221 $self->_after_item_action_hooks({ action => 'delete' });
223 logaction( "CATALOGUING", "DELETE", $self->itemnumber, "item" )
224 if C4::Context->preference("CataloguingLog");
226 return $self->SUPER::delete;
235 my $params = @_ ? shift : {};
237 my $safe_to_delete = $self->safe_to_delete;
238 return $safe_to_delete unless $safe_to_delete eq '1';
240 $self->move_to_deleted;
242 return $self->delete($params);
245 =head3 safe_to_delete
247 returns 1 if the item is safe to delete,
249 "book_on_loan" if the item is checked out,
251 "not_same_branch" if the item is blocked by independent branches,
253 "book_reserved" if the there are holds aganst the item, or
255 "linked_analytics" if the item has linked analytic records.
257 "last_item_for_hold" if the item is the last one on a record on which a biblio-level hold is placed
264 return "book_on_loan" if $self->checkout;
266 return "not_same_branch"
267 if defined C4::Context->userenv
268 and !C4::Context->IsSuperLibrarian()
269 and C4::Context->preference("IndependentBranches")
270 and ( C4::Context->userenv->{branch} ne $self->homebranch );
272 # check it doesn't have a waiting reserve
273 return "book_reserved"
274 if $self->holds->search( { found => [ 'W', 'T' ] } )->count;
276 return "linked_analytics"
277 if C4::Items::GetAnalyticsCount( $self->itemnumber ) > 0;
279 return "last_item_for_hold"
280 if $self->biblio->items->count == 1
281 && $self->biblio->holds->search(
290 =head3 move_to_deleted
292 my $is_moved = $item->move_to_deleted;
294 Move an item to the deleteditems table.
295 This can be done before deleting an item, to make sure the data are not completely deleted.
299 sub move_to_deleted {
301 my $item_infos = $self->unblessed;
302 delete $item_infos->{timestamp}; #This ensures the timestamp date in deleteditems will be set to the current timestamp
303 return Koha::Database->new->schema->resultset('Deleteditem')->create($item_infos);
307 =head3 effective_itemtype
309 Returns the itemtype for the item based on whether item level itemtypes are set or not.
313 sub effective_itemtype {
316 return $self->_result()->effective_itemtype();
326 $self->{_home_branch} ||= Koha::Libraries->find( $self->homebranch() );
328 return $self->{_home_branch};
331 =head3 holding_branch
338 $self->{_holding_branch} ||= Koha::Libraries->find( $self->holdingbranch() );
340 return $self->{_holding_branch};
345 my $biblio = $item->biblio;
347 Return the bibliographic record of this item
353 my $biblio_rs = $self->_result->biblio;
354 return Koha::Biblio->_new_from_dbic( $biblio_rs );
359 my $biblioitem = $item->biblioitem;
361 Return the biblioitem record of this item
367 my $biblioitem_rs = $self->_result->biblioitem;
368 return Koha::Biblioitem->_new_from_dbic( $biblioitem_rs );
373 my $checkout = $item->checkout;
375 Return the checkout for this item
381 my $checkout_rs = $self->_result->issue;
382 return unless $checkout_rs;
383 return Koha::Checkout->_new_from_dbic( $checkout_rs );
388 my $holds = $item->holds();
389 my $holds = $item->holds($params);
390 my $holds = $item->holds({ found => 'W'});
392 Return holds attached to an item, optionally accept a hashref of params to pass to search
397 my ( $self,$params ) = @_;
398 my $holds_rs = $self->_result->reserves->search($params);
399 return Koha::Holds->_new_from_dbic( $holds_rs );
404 my $transfer = $item->get_transfer;
406 Return the transfer if the item is in transit or undef
412 my $transfer_rs = $self->_result->branchtransfers->search({ datearrived => undef })->first;
413 return unless $transfer_rs;
414 return Koha::Item::Transfer->_new_from_dbic( $transfer_rs );
417 =head3 last_returned_by
419 Gets and sets the last borrower to return an item.
421 Accepts and returns Koha::Patron objects
423 $item->last_returned_by( $borrowernumber );
425 $last_returned_by = $item->last_returned_by();
429 sub last_returned_by {
430 my ( $self, $borrower ) = @_;
432 my $items_last_returned_by_rs = Koha::Database->new()->schema()->resultset('ItemsLastBorrower');
435 return $items_last_returned_by_rs->update_or_create(
436 { borrowernumber => $borrower->borrowernumber, itemnumber => $self->id } );
439 unless ( $self->{_last_returned_by} ) {
440 my $result = $items_last_returned_by_rs->single( { itemnumber => $self->id } );
442 $self->{_last_returned_by} = Koha::Patrons->find( $result->get_column('borrowernumber') );
446 return $self->{_last_returned_by};
450 =head3 can_article_request
452 my $bool = $item->can_article_request( $borrower )
454 Returns true if item can be specifically requested
456 $borrower must be a Koha::Patron object
460 sub can_article_request {
461 my ( $self, $borrower ) = @_;
463 my $rule = $self->article_request_type($borrower);
465 return 1 if $rule && $rule ne 'no' && $rule ne 'bib_only';
469 =head3 hidden_in_opac
471 my $bool = $item->hidden_in_opac({ [ rules => $rules ] })
473 Returns true if item fields match the hidding criteria defined in $rules.
474 Returns false otherwise.
476 Takes HASHref that can have the following parameters:
478 $rules : { <field> => [ value_1, ... ], ... }
480 Note: $rules inherits its structure from the parsed YAML from reading
481 the I<OpacHiddenItems> system preference.
486 my ( $self, $params ) = @_;
488 my $rules = $params->{rules} // {};
491 if C4::Context->preference('hidelostitems') and
494 my $hidden_in_opac = 0;
496 foreach my $field ( keys %{$rules} ) {
498 if ( any { $self->$field eq $_ } @{ $rules->{$field} } ) {
504 return $hidden_in_opac;
507 =head3 can_be_transferred
509 $item->can_be_transferred({ to => $to_library, from => $from_library })
510 Checks if an item can be transferred to given library.
512 This feature is controlled by two system preferences:
513 UseBranchTransferLimits to enable / disable the feature
514 BranchTransferLimitsType to use either an itemnumber or ccode as an identifier
515 for setting the limitations
517 Takes HASHref that can have the following parameters:
518 MANDATORY PARAMETERS:
521 $from : Koha::Library # if not given, item holdingbranch
522 # will be used instead
524 Returns 1 if item can be transferred to $to_library, otherwise 0.
526 To find out whether at least one item of a Koha::Biblio can be transferred, please
527 see Koha::Biblio->can_be_transferred() instead of using this method for
528 multiple items of the same biblio.
532 sub can_be_transferred {
533 my ($self, $params) = @_;
535 my $to = $params->{to};
536 my $from = $params->{from};
538 $to = $to->branchcode;
539 $from = defined $from ? $from->branchcode : $self->holdingbranch;
541 return 1 if $from eq $to; # Transfer to current branch is allowed
542 return 1 unless C4::Context->preference('UseBranchTransferLimits');
544 my $limittype = C4::Context->preference('BranchTransferLimitsType');
545 return Koha::Item::Transfer::Limits->search({
548 $limittype => $limittype eq 'itemtype'
549 ? $self->effective_itemtype : $self->ccode
553 =head3 pickup_locations
555 $pickup_locations = $item->pickup_locations( {patron => $patron } )
557 Returns possible pickup locations for this item, according to patron's home library (if patron is defined and holds are allowed only from hold groups)
558 and if item can be transferred to each pickup location.
562 sub pickup_locations {
563 my ($self, $params) = @_;
565 my $patron = $params->{patron};
567 my $circ_control_branch =
568 C4::Reserves::GetReservesControlBranch( $self->unblessed(), $patron->unblessed );
570 C4::Circulation::GetBranchItemRule( $circ_control_branch, $self->itype );
573 if(defined $patron) {
574 return \@libs if $branchitemrule->{holdallowed} == 3 && !$self->home_branch->validate_hold_sibling( {branchcode => $patron->branchcode} );
575 return \@libs if $branchitemrule->{holdallowed} == 1 && $self->home_branch->branchcode ne $patron->branchcode;
578 if ($branchitemrule->{hold_fulfillment_policy} eq 'holdgroup') {
579 @libs = $self->home_branch->get_hold_libraries;
580 push @libs, $self->home_branch unless scalar(@libs) > 0;
581 } elsif ($branchitemrule->{hold_fulfillment_policy} eq 'patrongroup') {
582 my $plib = Koha::Libraries->find({ branchcode => $patron->branchcode});
583 @libs = $plib->get_hold_libraries;
584 push @libs, $self->home_branch unless scalar(@libs) > 0;
585 } elsif ($branchitemrule->{hold_fulfillment_policy} eq 'homebranch') {
586 push @libs, $self->home_branch;
587 } elsif ($branchitemrule->{hold_fulfillment_policy} eq 'holdingbranch') {
588 push @libs, $self->holding_branch;
590 @libs = Koha::Libraries->search({
593 order_by => ['branchname']
597 my @pickup_locations;
598 foreach my $library (@libs) {
599 if ($library->pickup_location && $self->can_be_transferred({ to => $library })) {
600 push @pickup_locations, $library;
604 return \@pickup_locations;
607 =head3 article_request_type
609 my $type = $item->article_request_type( $borrower )
611 returns 'yes', 'no', 'bib_only', or 'item_only'
613 $borrower must be a Koha::Patron object
617 sub article_request_type {
618 my ( $self, $borrower ) = @_;
620 my $branch_control = C4::Context->preference('HomeOrHoldingBranch');
622 $branch_control eq 'homebranch' ? $self->homebranch
623 : $branch_control eq 'holdingbranch' ? $self->holdingbranch
625 my $borrowertype = $borrower->categorycode;
626 my $itemtype = $self->effective_itemtype();
627 my $rule = Koha::CirculationRules->get_effective_rule(
629 rule_name => 'article_requests',
630 categorycode => $borrowertype,
631 itemtype => $itemtype,
632 branchcode => $branchcode
636 return q{} unless $rule;
637 return $rule->rule_value || q{}
646 my $attributes = { order_by => 'priority' };
647 my $dtf = Koha::Database->new->schema->storage->datetime_parser;
649 itemnumber => $self->itemnumber,
652 reservedate => { '<=' => $dtf->format_date(dt_from_string) },
653 waitingdate => { '!=' => undef },
656 my $hold_rs = $self->_result->reserves->search( $params, $attributes );
657 return Koha::Holds->_new_from_dbic($hold_rs);
660 =head3 stockrotationitem
662 my $sritem = Koha::Item->stockrotationitem;
664 Returns the stock rotation item associated with the current item.
668 sub stockrotationitem {
670 my $rs = $self->_result->stockrotationitem;
672 return Koha::StockRotationItem->_new_from_dbic( $rs );
677 my $item = $item->add_to_rota($rota_id);
679 Add this item to the rota identified by $ROTA_ID, which means associating it
680 with the first stage of that rota. Should this item already be associated
681 with a rota, then we will move it to the new rota.
686 my ( $self, $rota_id ) = @_;
687 Koha::StockRotationRotas->find($rota_id)->add_item($self->itemnumber);
691 =head3 has_pending_hold
693 my $is_pending_hold = $item->has_pending_hold();
695 This method checks the tmp_holdsqueue to see if this item has been selected for a hold, but not filled yet and returns true or false
699 sub has_pending_hold {
701 my $pending_hold = $self->_result->tmp_holdsqueues;
702 return $pending_hold->count ? 1: 0;
707 my $mss = C4::Biblio::GetMarcSubfieldStructure( '', { unsafe => 1 } );
708 my $field = $item->as_marc_field({ [ mss => $mss ] });
710 This method returns a MARC::Field object representing the Koha::Item object
711 with the current mappings configuration.
716 my ( $self, $params ) = @_;
718 my $mss = $params->{mss} // C4::Biblio::GetMarcSubfieldStructure( '', { unsafe => 1 } );
719 my $item_tag = $mss->{'items.itemnumber'}[0]->{tagfield};
723 my @columns = $self->_result->result_source->columns;
725 foreach my $item_field ( @columns ) {
726 my $mapping = $mss->{ "items.$item_field"}[0];
727 my $tagfield = $mapping->{tagfield};
728 my $tagsubfield = $mapping->{tagsubfield};
729 next if !$tagfield; # TODO: Should we raise an exception instead?
730 # Feels like safe fallback is better
732 push @subfields, $tagsubfield => $self->$item_field
733 if defined $self->$item_field and $item_field ne '';
736 my $unlinked_item_subfields = C4::Items::_parse_unlinked_item_subfields_from_xml($self->more_subfields_xml);
737 push( @subfields, @{$unlinked_item_subfields} )
738 if defined $unlinked_item_subfields and $#$unlinked_item_subfields > -1;
742 $field = MARC::Field->new(
743 "$item_tag", ' ', ' ', @subfields
749 =head3 renewal_branchcode
751 Returns the branchcode to be recorded in statistics renewal of the item
755 sub renewal_branchcode {
757 my ($self, $params ) = @_;
759 my $interface = C4::Context->interface;
761 if ( $interface eq 'opac' ){
762 my $renewal_branchcode = C4::Context->preference('OpacRenewalBranch');
763 if( !defined $renewal_branchcode || $renewal_branchcode eq 'opacrenew' ){
764 $branchcode = 'OPACRenew';
766 elsif ( $renewal_branchcode eq 'itemhomebranch' ) {
767 $branchcode = $self->homebranch;
769 elsif ( $renewal_branchcode eq 'patronhomebranch' ) {
770 $branchcode = $self->checkout->patron->branchcode;
772 elsif ( $renewal_branchcode eq 'checkoutbranch' ) {
773 $branchcode = $self->checkout->branchcode;
779 $branchcode = ( C4::Context->userenv && defined C4::Context->userenv->{branch} )
780 ? C4::Context->userenv->{branch} : $params->{branch};
785 =head3 _set_found_trigger
787 $self->_set_found_trigger
789 Finds the most recent lost item charge for this item and refunds the patron
790 appropriately, taking into account any payments or writeoffs already applied
793 Internal function, not exported, called only by Koha::Item->store.
797 sub _set_found_trigger {
798 my ( $self, $pre_mod_item ) = @_;
800 ## If item was lost, it has now been found, reverse any list item charges if necessary.
801 my $no_refund_after_days =
802 C4::Context->preference('NoRefundOnLostReturnedItemsAge');
803 if ($no_refund_after_days) {
804 my $today = dt_from_string();
805 my $lost_age_in_days =
806 dt_from_string( $pre_mod_item->itemlost_on )->delta_days($today)
809 return $self unless $lost_age_in_days < $no_refund_after_days;
813 unless Koha::CirculationRules->get_lostreturn_policy(
816 return_branch => C4::Context->userenv
817 ? C4::Context->userenv->{'branch'}
822 # check for charge made for lost book
823 my $accountlines = Koha::Account::Lines->search(
825 itemnumber => $self->itemnumber,
826 debit_type_code => 'LOST',
827 status => [ undef, { '<>' => 'FOUND' } ]
830 order_by => { -desc => [ 'date', 'accountlines_id' ] }
834 return $self unless $accountlines->count > 0;
836 my $accountline = $accountlines->next;
837 my $total_to_refund = 0;
839 return $self unless $accountline->borrowernumber;
841 my $patron = Koha::Patrons->find( $accountline->borrowernumber );
843 unless $patron; # Patron has been deleted, nobody to credit the return to
844 # FIXME Should not we notify this somewhere
846 my $account = $patron->account;
849 if ( $accountline->amount > $accountline->amountoutstanding ) {
851 # some amount has been cancelled. collect the offsets that are not writeoffs
852 # this works because the only way to subtract from this kind of a debt is
853 # using the UI buttons 'Pay' and 'Write off'
854 my $credits_offsets = Koha::Account::Offsets->search(
856 debit_id => $accountline->id,
857 credit_id => { '!=' => undef }, # it is not the debit itself
858 type => { '!=' => 'Writeoff' },
859 amount => { '<' => 0 } # credits are negative on the DB
863 $total_to_refund = ( $credits_offsets->count > 0 )
864 ? $credits_offsets->total * -1 # credits are negative on the DB
868 my $credit_total = $accountline->amountoutstanding + $total_to_refund;
871 if ( $credit_total > 0 ) {
873 C4::Context->userenv ? C4::Context->userenv->{'branch'} : undef;
874 $credit = $account->add_credit(
876 amount => $credit_total,
877 description => 'Item found ' . $self->itemnumber,
878 type => 'LOST_FOUND',
879 interface => C4::Context->interface,
880 library_id => $branchcode,
881 item_id => $self->itemnumber,
882 issue_id => $accountline->issue_id
886 $credit->apply( { debits => [$accountline] } );
887 $self->{_refunded} = 1;
890 # Update the account status
891 $accountline->status('FOUND');
892 $accountline->store();
894 if ( defined $account and C4::Context->preference('AccountAutoReconcile') ) {
895 $account->reconcile_balance;
901 =head3 to_api_mapping
903 This method returns the mapping for representing a Koha::Item object
910 itemnumber => 'item_id',
911 biblionumber => 'biblio_id',
912 biblioitemnumber => undef,
913 barcode => 'external_id',
914 dateaccessioned => 'acquisition_date',
915 booksellerid => 'acquisition_source',
916 homebranch => 'home_library_id',
917 price => 'purchase_price',
918 replacementprice => 'replacement_price',
919 replacementpricedate => 'replacement_price_date',
920 datelastborrowed => 'last_checkout_date',
921 datelastseen => 'last_seen_date',
923 notforloan => 'not_for_loan_status',
924 damaged => 'damaged_status',
925 damaged_on => 'damaged_date',
926 itemlost => 'lost_status',
927 itemlost_on => 'lost_date',
928 withdrawn => 'withdrawn',
929 withdrawn_on => 'withdrawn_date',
930 itemcallnumber => 'callnumber',
931 coded_location_qualifier => 'coded_location_qualifier',
932 issues => 'checkouts_count',
933 renewals => 'renewals_count',
934 reserves => 'holds_count',
935 restricted => 'restricted_status',
936 itemnotes => 'public_notes',
937 itemnotes_nonpublic => 'internal_notes',
938 holdingbranch => 'holding_library_id',
940 timestamp => 'timestamp',
941 location => 'location',
942 permanent_location => 'permanent_location',
943 onloan => 'checked_out_date',
944 cn_source => 'call_number_source',
945 cn_sort => 'call_number_sort',
946 ccode => 'collection_code',
947 materials => 'materials_notes',
949 itype => 'item_type',
950 more_subfields_xml => 'extended_subfields',
951 enumchron => 'serial_issue_number',
952 copynumber => 'copy_number',
953 stocknumber => 'inventory_number',
954 new_status => 'new_status'
960 my $itemtype = $item->itemtype;
962 Returns Koha object for effective itemtype
968 return Koha::ItemTypes->find( $self->effective_itemtype );
971 =head2 Internal methods
973 =head3 _after_item_action_hooks
975 Helper method that takes care of calling all plugin hooks
979 sub _after_item_action_hooks {
980 my ( $self, $params ) = @_;
982 my $action = $params->{action};
989 item_id => $self->itemnumber,
1004 Kyle M Hall <kyle@bywatersolutions.com>