=item C<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.

=item C<RecallFound>

A recall for this item was found, and the item needs to be transferred to the recall's pickup branch.

    # find recall

    my $recall = Koha::Recalls->find({ itemnumber => $itemnumber, status => 'T' });

    if ( defined $recall ) {

        # do a transfer if the recall branch is different to the item holding branch

        if ( $recall->branchcode eq $fbr ) {

            $dotransfer = 0;

            $messages->{'RecallPlacedAtHoldingBranch'} = 1;

        } else {

            $dotransfer = 1;

            $messages->{'RecallFound'} = $recall;

        }

    }

=head3 RECALLED

recalled by someone else

          * RECALL PLACED ?

              - fill recall if recall to this patron

              - cancel recall or not

              - revert recall's waiting status or not

    my $cancel_recall = $params && $params->{cancel_recall};

    my $recall_id = $params && $params->{recall_id};

            Koha::Recalls->move_recall({ action => $cancel_recall, recall_id => $recall_id, itemnumber => $item_object->itemnumber, borrowernumber => $borrower->{borrowernumber} });

=item C<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, C<RecallNeedsTransfer> is also returned which contains this

branchcode.

=item C<TransferredRecall>

This item has been transferred to this branch to fill a recall. The recall object is returned.

    # find recalls...

    # check if this item is recallable first, which includes checking if UseRecalls syspref is enabled

    my $recall = $item->check_recalls if $item->can_be_waiting_recall;

    if ( defined $recall ) {

        $messages->{RecallFound} = $recall;

        if ( $recall->branchcode ne $branch ) {

            $messages->{RecallNeedsTransfer} = $branch;

        }

    }

    my $transfer_recall = Koha::Recalls->find({ itemnumber => $item->itemnumber, status => 'T' }); # all recalls that have triggered a transfer will have an allocated itemnumber

    if ( $transfer_recall && $transfer_recall->branchcode eq $branch ) {

        $messages->{TransferredRecall} = $transfer_recall;

    }

    my $recall = $item->check_recalls if $item->can_be_waiting_recall;

    if ( defined $recall ) {

        if ( $recall->item_level_recall ) {

            # item-level recall. check if this item is the recalled item, otherwise renewal will be allowed

            return ( 0, 'recalled' ) if ( $recall->itemnumber == $item->itemnumber );

        } else {

            # biblio-level recall, so only disallow renewal if the biblio-level recall has been fulfilled by a different item

            return ( 0, 'recalled' ) unless ( $recall->waiting );

        }

    }

        my $item_recalled_count   = 0;

                # is item a waiting recall?

                my $recallstatus = '';

                    $recallstatus = 'Waiting' if Koha::Recalls->search({ itemnumber => $item->{itemnumber}, status => 'W' })->count;

                    || $recallstatus eq 'Waiting'

                    $item_recalled_count++   if $recallstatus eq 'Waiting';

                    $other_items->{$key}->{recalled} = ($recallstatus) ? 1 : 0;

        $oldbiblio->{recalledcount}        = $item_recalled_count;

        my $recalls = Koha::Recalls->search({ itemnumber => $item->itemnumber, status => 'W' });

=head3 recalls

    my $recalls = $biblio->recalls;

Return all active recalls attached to this biblio, sorted by oldest first

=cut

sub recalls {

    my ( $self ) = @_;

    $self->{_recalls} ||= Koha::Recalls->search({ biblionumber => $self->biblionumber, old => undef }, { order_by => { -asc => 'recalldate' } } );

    return $self->{_recalls};

}

=head3 can_be_recalled

    my @items_for_recall = $biblio->can_be_recalled({ patron => $patron_object });

Does biblio-level checks and returns the items attached to this biblio that are available for recall

=cut

sub can_be_recalled {

    my ( $self, $params ) = @_;

    return 0 if !( C4::Context->preference('UseRecalls') );

    my $patron = $params->{patron};

    my $branchcode = C4::Context->userenv->{'branch'};

    if ( C4::Context->preference('CircControl') eq 'PatronLibrary' and $patron ) {

        $branchcode = $patron->branchcode;

    }

    # items are unavailable for recall if they are lost, withdrawn or notforloan

    my @items = Koha::Items->search({ biblionumber => $self->biblionumber, itemlost => 0, withdrawn => 0, notforloan => 0 });

    # if there are no available items at all, no recall can be placed

    return 0 if ( scalar @items == 0 );

    my @itemtypes;

    my @itemnumbers;

    foreach my $item ( @items ) {

        push( @itemtypes, $item->effective_itemtype );

        push( @itemnumbers, $item->itemnumber );

    }

    # Check the circulation rule for each relevant itemtype for this biblio

    my ( @recalls_allowed, @recalls_per_record, @on_shelf_recalls );

    foreach my $itemtype ( @itemtypes ) {

        my $rule = Koha::CirculationRules->get_effective_rules({

            branchcode => $branchcode,

            categorycode => $patron ? $patron->categorycode : undef,

            itemtype => $itemtype,

            rules => [

                'recalls_allowed',

                'recalls_per_record',

                'on_shelf_recalls',

            ],

        });

        push( @recalls_allowed, $rule->{recalls_allowed} ) if $rule;

        push( @recalls_per_record, $rule->{recalls_per_record} ) if $rule;

        push( @on_shelf_recalls, $rule->{on_shelf_recalls} ) if $rule;

    }

    my $recalls_allowed = (sort {$b <=> $a} @recalls_allowed)[0]; # take highest

    my $recalls_per_record = (sort {$b <=> $a} @recalls_per_record)[0]; # take highest

    my %on_shelf_recalls_count = ();

    foreach my $count ( @on_shelf_recalls ) {

        $on_shelf_recalls_count{$count}++;

    }

    my $on_shelf_recalls = (sort {$on_shelf_recalls_count{$b} <=> $on_shelf_recalls_count{$a}} @on_shelf_recalls)[0]; # take most common

    # check recalls allowed has been set and is not zero

    return 0 if ( !defined($recalls_allowed) || $recalls_allowed == 0 );

    if ( $patron ) {

        # check borrower has not reached open recalls allowed limit

        return 0 if ( $patron->recalls->count >= $recalls_allowed );

        # check borrower has not reached open recalls allowed per record limit

        return 0 if ( $patron->recalls({ biblionumber => $self->biblionumber })->count >= $recalls_per_record );

        # check if any of the items under this biblio are already checked out by this borrower

        return 0 if ( Koha::Checkouts->search({ itemnumber => [ @itemnumbers ], borrowernumber => $patron->borrowernumber })->count > 0 );

    }

    # check item availability

    my $checked_out_count = 0;

    foreach (@items) {

        if ( Koha::Checkouts->search({ itemnumber => $_->itemnumber })->count > 0 ){ $checked_out_count++; }

    }

    # can't recall if on shelf recalls only allowed when all unavailable, but items are still available for checkout

    return 0 if ( $on_shelf_recalls eq 'all' && $checked_out_count < scalar @items );

    # can't recall if no items have been checked out

    return 0 if ( $checked_out_count == 0 );

    # can recall

    return @items;

}

=head3 recall

    my $recall = $item->recall;

Return the relevant recall for this item

=cut

sub recall {

    my ( $self ) = @_;

    my @recalls = Koha::Recalls->search({ biblionumber => $self->biblionumber, old => undef }, { order_by => { -asc => 'recalldate' } });

    foreach my $recall (@recalls) {

        if ( $recall->item_level_recall and $recall->itemnumber == $self->itemnumber ){

            return $recall;

        }

    }

    # no item-level recall to return, so return earliest biblio-level

    # FIXME: eventually this will be based on priority

    return $recalls[0];

}

=head3 can_be_recalled

    if ( $item->can_be_recalled({ patron => $patron_object }) ) # do recall

Does item-level checks and returns if items can be recalled by this borrower

=cut

sub can_be_recalled {

    my ( $self, $params ) = @_;

    return 0 if !( C4::Context->preference('UseRecalls') );

    # check if this item is not for loan, withdrawn or lost

    return 0 if ( $self->notforloan != 0 );

    return 0 if ( $self->itemlost != 0 );

    return 0 if ( $self->withdrawn != 0 );

    # check if this item is not checked out - if not checked out, can't be recalled

    return 0 if ( !defined( $self->checkout ) );

    my $patron = $params->{patron};

    my $branchcode = C4::Context->userenv->{'branch'};

    if ( $patron ) {

        $branchcode = C4::Circulation::_GetCircControlBranch( $self->unblessed, $patron->unblessed );

    }

    # Check the circulation rule for each relevant itemtype for this item

    my $rule = Koha::CirculationRules->get_effective_rules({

        branchcode => $branchcode,

        categorycode => $patron ? $patron->categorycode : undef,

        itemtype => $self->effective_itemtype,

        rules => [

            'recalls_allowed',

            'recalls_per_record',

            'on_shelf_recalls',

        ],

    });

    # check recalls allowed has been set and is not zero

    return 0 if ( !defined($rule->{recalls_allowed}) || $rule->{recalls_allowed} == 0 );

    if ( $patron ) {

        # check borrower has not reached open recalls allowed limit

        return 0 if ( $patron->recalls->count >= $rule->{recalls_allowed} );

        # check borrower has not reach open recalls allowed per record limit

        return 0 if ( $patron->recalls({ biblionumber => $self->biblionumber })->count >= $rule->{recalls_per_record} );

        # check if this patron has already recalled this item

        return 0 if ( Koha::Recalls->search({ itemnumber => $self->itemnumber, borrowernumber => $patron->borrowernumber, old => undef })->count > 0 );

        # check if this patron has already checked out this item

        return 0 if ( Koha::Checkouts->search({ itemnumber => $self->itemnumber, borrowernumber => $patron->borrowernumber })->count > 0 );

        # check if this patron has already reserved this item

        return 0 if ( Koha::Holds->search({ itemnumber => $self->itemnumber, borrowernumber => $patron->borrowernumber })->count > 0 );

    }

    # check item availability

    # items are unavailable for recall if they are lost, withdrawn or notforloan

    my @items = Koha::Items->search({ biblionumber => $self->biblionumber, itemlost => 0, withdrawn => 0, notforloan => 0 });

    # if there are no available items at all, no recall can be placed

    return 0 if ( scalar @items == 0 );

    my $checked_out_count = 0;

    foreach (@items) {

        if ( Koha::Checkouts->search({ itemnumber => $_->itemnumber })->count > 0 ){ $checked_out_count++; }

    }

    # can't recall if on shelf recalls only allowed when all unavailable, but items are still available for checkout

    return 0 if ( $rule->{on_shelf_recalls} eq 'all' && $checked_out_count < scalar @items );

    # can't recall if no items have been checked out

    return 0 if ( $checked_out_count == 0 );

    # can recall

    return 1;

}

=head3 can_be_waiting_recall

    if ( $item->can_be_waiting_recall ) { # allocate item as waiting for recall

Checks item type and branch of circ rules to return whether this item can be used to fill a recall.

At this point the item has already been recalled. We are now at the checkin and set waiting stage.

=cut

sub can_be_waiting_recall {

    my ( $self ) = @_;

    return 0 if !( C4::Context->preference('UseRecalls') );

    # check if this item is not for loan, withdrawn or lost

    return 0 if ( $self->notforloan != 0 );

    return 0 if ( $self->itemlost != 0 );

    return 0 if ( $self->withdrawn != 0 );

    my $branchcode = $self->holdingbranch;

    if ( C4::Context->preference('CircControl') eq 'PickupLibrary' and C4::Context->userenv and C4::Context->userenv->{'branch'} ) {

        $branchcode = C4::Context->userenv->{'branch'};

    } else {

        $branchcode = ( C4::Context->preference('HomeOrHoldingBranch') eq 'homebranch' ) ? $self->homebranch : $self->holdingbranch;

    }

    # Check the circulation rule for each relevant itemtype for this item

    my $rule = Koha::CirculationRules->get_effective_rules({

        branchcode => $branchcode,

        categorycode => undef,

        itemtype => $self->effective_itemtype,

        rules => [

            'recalls_allowed',

        ],

    });

    # check recalls allowed has been set and is not zero

    return 0 if ( !defined($rule->{recalls_allowed}) || $rule->{recalls_allowed} == 0 );

    # can recall

    return 1;

}

=head3 check_recalls

    my $recall = $item->check_recalls;

Get the most relevant recall for this item.

=cut

sub check_recalls {

    my ( $self ) = @_;

    my @recalls = Koha::Recalls->search({ itemnumber => $self->itemnumber, status => [ 'R','O','W' ] }, { order_by => { -asc => 'recalldate' } });

    if ( scalar @recalls == 0 ) {

        # no item-level recalls or recalls waiting for this specific item

        # look for biblio-level recalls

        @recalls = Koha::Recalls->search({ biblionumber => $self->biblionumber, itemnumber => [ $self->itemnumber, undef ], status => [ 'R','O','W' ] }, { order_by => { -asc => 'recalldate' } });

    }

    my $recall;

    # iterate through relevant recalls to find the best one.

    # if we come across a waiting recall, use this one.

    # if we have iterated through all recalls and not found a waiting recall, use the first recall in the array, which should be the oldest recall.

    foreach my $r ( @recalls ) {

        if ( $r->waiting ) {

            $recall = $r;

            last;

        }

    }

    unless ( defined $recall ) {

        $recall = $recalls[0];

    }

    return $recall;

}

=head3 recalls

    my $recalls = $patron->recalls;

    my $recalls = $patron->recalls({ biblionumber => $biblionumber });

Return the patron's active recalls - total, or on a specific biblio

=cut

sub recalls {

    my ( $self, $params ) = @_;

    my $biblionumber = $params->{biblionumber};

    my $recalls_rs = Koha::Recalls->search({ borrowernumber => $self->borrowernumber, old => undef });

    if ( $biblionumber ) {

        $recalls_rs = Koha::Recalls->search({ borrowernumber => $self->borrowernumber, old => undef, biblionumber => $biblionumber });

    }

    return $recalls_rs;

}

use Koha::Recalls;

sub RecallsCount {

    my ( $self, $biblionumber ) = @_;

    my $recalls = Koha::Recalls->search({ biblionumber => $biblionumber, old => undef });

    return $recalls->count;

}

subtest 'Recalls tests' => sub {

    plan tests => 12;

    $schema->storage->txn_begin;

    my $item1 = $builder->build_sample_item;

    my $biblio = $item1->biblio;

    my $branchcode = $item1->holdingbranch;

    my $patron1 = $builder->build_object({ class => 'Koha::Patrons', value => { branchcode => $branchcode } });

    my $patron2 = $builder->build_object({ class => 'Koha::Patrons', value => { branchcode => $branchcode } });

    my $patron3 = $builder->build_object({ class => 'Koha::Patrons', value => { branchcode => $branchcode } });

    my $item2 = $builder->build_object({ class => 'Koha::Items', value => { holdingbranch => $branchcode, homebranch => $branchcode, biblionumber => $biblio->biblionumber, itype => $item1->effective_itemtype } });

    t::lib::Mocks::mock_userenv({ patron => $patron1 });

    my $recall1 = Koha::Recall->new({

        borrowernumber => $patron1->borrowernumber,

        recalldate => Koha::DateUtils::dt_from_string,

        biblionumber => $biblio->biblionumber,

        branchcode => $branchcode,

        status => 'R',

        itemnumber => $item1->itemnumber,

        expirationdate => undef,

        item_level_recall => 1

    })->store;

    my $recall2 = Koha::Recall->new({

        borrowernumber => $patron2->borrowernumber,

        recalldate => Koha::DateUtils::dt_from_string,

        biblionumber => $biblio->biblionumber,

        branchcode => $branchcode,

        status => 'R',

        itemnumber => undef,

        expirationdate => undef,

        item_level_recall => 0

    })->store;

    my $recall3 = Koha::Recall->new({

        borrowernumber => $patron3->borrowernumber,

        recalldate => Koha::DateUtils::dt_from_string,

        biblionumber => $biblio->biblionumber,

        branchcode => $branchcode,

        status => 'R',

        itemnumber => $item1->itemnumber,

        expirationdate => undef,

        item_level_recall => 1

    })->store;

    my $recalls_count = $biblio->recalls->count;

    is( $recalls_count, 3, 'Correctly get number of active recalls for biblio' );

    $recall1->set_cancelled;

    $recall2->set_expired({ interface => 'COMMANDLINE' });

    $recalls_count = $biblio->recalls->count;

    is( $recalls_count, 1, 'Correctly get number of active recalls for biblio' );

    t::lib::Mocks::mock_preference('UseRecalls', 0);

    is( $biblio->can_be_recalled({ patron => $patron1 }), 0, "Can't recall with UseRecalls disabled" );

    t::lib::Mocks::mock_preference("UseRecalls", 1);

    $item1->update({ notforloan => 1 });

    is( $biblio->can_be_recalled({ patron => $patron1 }), 0, "Can't recall with no available items" );

    $item1->update({ notforloan => 0 });

    Koha::CirculationRules->set_rules({

        branchcode => $branchcode,

        categorycode => $patron1->categorycode,

        itemtype => $item1->effective_itemtype,

        rules => {

            recalls_allowed => 0,

            recalls_per_record => 1,

            on_shelf_recalls => 'all',

        },

    });

    is( $biblio->can_be_recalled({ patron => $patron1 }), 0, "Can't recall if recalls_allowed = 0" );

    Koha::CirculationRules->set_rules({

        branchcode => $branchcode,

        categorycode => $patron1->categorycode,

        itemtype => $item1->effective_itemtype,

        rules => {

            recalls_allowed => 1,

            recalls_per_record => 1,

            on_shelf_recalls => 'all',

        },

    });

    is( $biblio->can_be_recalled({ patron => $patron1 }), 0, "Can't recall if patron has more existing recall(s) than recalls_allowed" );

    is( $biblio->can_be_recalled({ patron => $patron1 }), 0, "Can't recall if patron has more existing recall(s) than recalls_per_record" );

    $recall1->set_cancelled;

    C4::Circulation::AddIssue( $patron1->unblessed, $item2->barcode );

    is( $biblio->can_be_recalled({ patron => $patron1 }), 0, "Can't recall if patron has already checked out an item attached to this biblio" );

    is( $biblio->can_be_recalled({ patron => $patron1 }), 0, "Can't recall if on_shelf_recalls = all and items are still available" );

    Koha::CirculationRules->set_rules({

        branchcode => $branchcode,

        categorycode => $patron1->categorycode,

        itemtype => $item1->effective_itemtype,

        rules => {

            recalls_allowed => 1,

            recalls_per_record => 1,

            on_shelf_recalls => 'any',

        },

    });

    C4::Circulation::AddReturn( $item2->barcode, $branchcode );

    is( $biblio->can_be_recalled({ patron => $patron1 }), 0, "Can't recall if no items are checked out" );

    $recall2->set_cancelled;

    C4::Circulation::AddIssue( $patron2->unblessed, $item2->barcode );

    is( $biblio->can_be_recalled({ patron => $patron1 }), 2, "Can recall two items" );

    $item1->update({ withdrawn => 1 });

    is( $biblio->can_be_recalled({ patron => $patron1 }), 1, "Can recall one item" );

    $schema->storage->txn_rollback;

};