C4/SIP/ILS/Item.pm

   1 #
   2 # ILS::Item.pm
   3 #
   4 # A Class for hiding the ILS's concept of the item from OpenSIP
   5 #
   6
   7 package C4::SIP::ILS::Item;
   8
   9 use strict;
  10 use warnings;
  11
  12 use C4::SIP::Sip qw(siplog);
  13 use Carp;
  14 use Template;
  15
  16 use C4::SIP::ILS::Transaction;
  17 use C4::SIP::Sip qw(add_field maybe_add);
  18
  19 use C4::Biblio;
  20 use C4::Circulation qw( barcodedecode );
  21 use C4::Context;
  22 use C4::Items;
  23 use C4::Members;
  24 use Koha::Biblios;
  25 use Koha::Checkouts::ReturnClaims;
  26 use Koha::Checkouts;
  27 use Koha::Database;
  28 use Koha::DateUtils qw( dt_from_string );
  29 use Koha::Holds;
  30 use Koha::Items;
  31 use Koha::Patrons;
  32
  33 =encoding UTF-8
  34
  35 =head1 EXAMPLE
  36
  37  our %item_db = (
  38     '1565921879' => {
  39         title => "Perl 5 desktop reference",
  40         id => '1565921879',
  41         sip_media_type => '001',
  42         magnetic_media => 0,
  43         hold_queue => [],
  44     },
  45     '0440242746' => {
  46         title => "The deep blue alibi",
  47         id => '0440242746',
  48         sip_media_type => '001',
  49         magnetic_media => 0,
  50         hold_queue => [
  51             {
  52             itemnumber => '823',
  53             priority => '1',
  54             reservenotes => undef,
  55             reservedate => '2008-10-09',
  56             found => undef,
  57             rtimestamp => '2008-10-09 11:15:06',
  58             biblionumber => '406',
  59             borrowernumber => '756',
  60             branchcode => 'CPL'
  61             }
  62         ],
  63     },
  64     '660' => {
  65         title => "Harry Potter y el cáliz de fuego",
  66         id => '660',
  67         sip_media_type => '001',
  68         magnetic_media => 0,
  69         hold_queue => [],
  70     },
  71 );
  72
  73 =cut
  74
  75 sub new {
  76     my ($class, $item_id) = @_;
  77     my $type = ref($class) || $class;
  78     my $item = Koha::Items->find( { barcode => barcodedecode( $item_id ) } );
  79     unless ( $item ) {
  80         siplog("LOG_DEBUG", "new ILS::Item('%s'): not found", $item_id);
  81         warn "new ILS::Item($item_id) : No item '$item_id'.";
  82         return;
  83     }
  84     my $self = $item->unblessed;
  85     $self->{_object}            = $item;
  86     $self->{id}                 = $item->barcode; # to SIP, the barcode IS the id.
  87     if (C4::Context->preference('UseLocationAsAQInSIP')) {
  88         $self->{permanent_location} = $item->permanent_location;
  89     } else {
  90         $self->{permanent_location} = $item->homebranch;
  91     }
  92     $self->{collection_code}    = $item->ccode;
  93     $self->{call_number}        = $item->itemcallnumber;
  94     $self->{'shelving_location'}           = $item->location;
  95     $self->{'permanent_shelving_location'} = $item->permanent_location;
  96
  97     $self->{object} = $item;
  98
  99     my $it = $item->effective_itemtype;
 100     $self->{itemtype} = $it;
 101     my $itemtype = Koha::Database->new()->schema()->resultset('Itemtype')->find( $it );
 102     $self->{sip_media_type} = $itemtype->sip_media_type() if $itemtype;
 103
 104     # check if its on issue and if so get the borrower
 105     my $issue = Koha::Checkouts->find( { itemnumber => $item->itemnumber } );
 106     if ($issue) {
 107         $self->{due_date} = dt_from_string( $issue->date_due, 'sql' )->truncate( to => 'minute' );
 108         my $patron = Koha::Patrons->find( $issue->borrowernumber );
 109         $self->{borrowernumber} = $patron->borrowernumber;
 110     }
 111     my $biblio = Koha::Biblios->find( $self->{biblionumber} );
 112     my $holds = $biblio->current_holds->unblessed;
 113     $self->{hold_queue} = $holds;
 114     $self->{hold_attached} = [( grep { defined $_->{found}  and ( $_->{found} eq 'W' or $_->{found} eq 'P' or $_->{found} eq 'T' ) } @{$self->{hold_queue}} )];
 115     $self->{pending_queue} = [( grep {(! defined $_->{found}) or ( $_->{found} ne 'W' and $_->{found} ne 'P' and $_->{found} ne 'T' ) } @{$self->{hold_queue}} )];
 116     $self->{title} = $biblio->title;
 117     $self->{author} = $biblio->author;
 118     bless $self, $type;
 119
 120     siplog( "LOG_DEBUG", "new ILS::Item('%s'): found with title '%s'",
 121         $item_id, $self->{title} // '' );
 122
 123     return $self;
 124 }
 125
 126 # 0 means read-only
 127 # 1 means read/write
 128
 129 my %fields = (
 130     id                  => 0,
 131     sip_media_type      => 0,
 132     sip_item_properties => 0,
 133     magnetic_media      => 0,
 134     permanent_location  => 0,
 135     current_location    => 0,
 136     print_line          => 1,
 137     screen_msg          => 1,
 138     itemnumber          => 0,
 139     biblionumber        => 0,
 140     barcode             => 0,
 141     onloan              => 0,
 142     collection_code     => 0,
 143     shelving_location   => 0,
 144     permanent_shelving_location   => 0,
 145     call_number         => 0,
 146     enumchron           => 0,
 147     location            => 0,
 148     author              => 0,
 149     title               => 0,
 150     itemtype            => 0,
 151 );
 152
 153 sub next_hold {
 154     my $self = shift;
 155     # use Data::Dumper; warn "next_hold() hold_attached: " . Dumper($self->{hold_attached}); warn "next_hold() pending_queue: " . $self->{pending_queue};
 156     foreach (@{$self->hold_attached}) {    # If this item was taken from the hold shelf, then that reserve still governs
 157         next unless ($_->{itemnumber} and $_->{itemnumber} == $self->{itemnumber});
 158         return $_;
 159     }
 160     if (scalar @{$self->{pending_queue}}) {    # Otherwise, if there is at least one hold, the first (best priority) gets it
 161         return  $self->{pending_queue}->[0];
 162     }
 163     return;
 164 }
 165
 166 # hold_patron_id is NOT the barcode.  It's the borrowernumber.
 167 # If a return triggers capture for a hold the borrowernumber is passed
 168 # and saved so that other hold info can be retrieved
 169 sub hold_patron_id {
 170     my $self = shift;
 171     my $id   = shift;
 172     if ($id) {
 173         $self->{hold}->{borrowernumber} = $id;
 174     }
 175     if ($self->{hold} ) {
 176         return $self->{hold}->{borrowernumber};
 177     }
 178     return;
 179
 180 }
 181 sub hold_patron_name {
 182     my ( $self, $template ) = @_;
 183     my $borrowernumber = $self->hold_patron_id() or return q{};
 184
 185     if ($template) {
 186         my $tt = Template->new();
 187
 188         my $patron = Koha::Patrons->find($borrowernumber);
 189
 190         my $output;
 191         $tt->process( \$template, { patron => $patron }, \$output );
 192         return $output;
 193     }
 194
 195     my $holder = Koha::Patrons->find( $borrowernumber );
 196     unless ($holder) {
 197         siplog("LOG_ERR", "While checking hold, failed to retrieve the patron with borrowernumber '$borrowernumber'");
 198         return q{};
 199     }
 200     my $email = $holder->email || '';
 201     my $phone = $holder->phone || '';
 202     my $extra = ($email and $phone) ? " ($email, $phone)" :  # both populated, employ comma
 203                 ($email or  $phone) ? " ($email$phone)"   :  # only 1 populated, we don't care which: no comma
 204                 "" ;                                         # neither populated, empty string
 205     my $name = $holder->firstname ? $holder->firstname . ' ' : '';
 206     $name .= $holder->surname . $extra;
 207     return $name;
 208 }
 209
 210 sub hold_patron_bcode {
 211     my $self = shift;
 212     my $borrowernumber = (@_ ? shift: $self->hold_patron_id()) or return q{};
 213     my $holder = Koha::Patrons->find( $borrowernumber );
 214     if ($holder and $holder->cardnumber ) {
 215         return $holder->cardnumber;
 216     }
 217     return q();
 218 }
 219
 220 sub destination_loc {
 221     my $self = shift;
 222     my $set_loc = shift;
 223     if ($set_loc) {
 224         $self->{dest_loc} = $set_loc;
 225     }
 226     if ($self->{dest_loc} ) {
 227         return $self->{dest_loc};
 228     }
 229     return q{};
 230 }
 231
 232 our $AUTOLOAD;
 233
 234 sub DESTROY { } # keeps AUTOLOAD from catching inherent DESTROY calls
 235
 236 sub AUTOLOAD {
 237     my $self = shift;
 238     my $class = ref($self) or croak "$self is not an object";
 239     my $name = $AUTOLOAD;
 240
 241     $name =~ s/.*://;
 242
 243     unless (exists $fields{$name}) {
 244                 croak "Cannot access '$name' field of class '$class'";
 245     }
 246
 247         if (@_) {
 248         $fields{$name} or croak "Field '$name' of class '$class' is READ ONLY.";
 249                 return $self->{$name} = shift;
 250         } else {
 251                 return $self->{$name};
 252         }
 253 }
 254
 255 sub status_update {     # FIXME: this looks unimplemented
 256     my ($self, $props) = @_;
 257     my $status = C4::SIP::ILS::Transaction->new();
 258     $self->{sip_item_properties} = $props;
 259     $status->{ok} = 1;
 260     return $status;
 261 }
 262
 263 sub title_id {
 264     my $self = shift;
 265     return $self->{title};
 266 }
 267
 268 sub sip_circulation_status {
 269     my $self = shift;
 270     if ( $self->{_object}->get_transfer ) {
 271         return '10'; # in transit between libraries
 272     }
 273     elsif ( Koha::Checkouts::ReturnClaims->search({ itemnumber => $self->{_object}->id, resolution => undef })->count ) {
 274         return '11';    # claimed returned
 275     }
 276     elsif ( $self->{itemlost} ) {
 277         return '12';    # lost
 278     }
 279     elsif ( $self->{borrowernumber} ) {
 280         return '04';    # charged
 281     }
 282     elsif ( grep { $_->{itemnumber} == $self->{itemnumber}  } @{ $self->{hold_attached} } ) {
 283         return '08';    # waiting on hold shelf
 284     }
 285     elsif ( $self->{location} and $self->{location} eq 'CART' ) {
 286         return '09';    # waiting to be re-shelved
 287     }
 288     elsif ( $self->{damaged} ) {
 289         return '01';    # damaged
 290     }
 291     elsif ( $self->{notforloan} < 0 ) {
 292         return '02';    # on order
 293     }
 294     else {
 295         return '03';    # available
 296     }    # FIXME: 01-13 enumerated in spec.
 297 }
 298
 299 sub sip_security_marker {
 300     my $self = shift;
 301     return '02';        # FIXME? 00-other; 01-None; 02-Tattle-Tape Security Strip (3M); 03-Whisper Tape (3M)
 302 }
 303 sub sip_fee_type {
 304     my $self = shift;
 305     return '01';    # FIXME? 01-09 enumerated in spec.  We just use O1-other/unknown.
 306 }
 307
 308 sub fee {
 309     my $self = shift;
 310     return $self->{fee} || 0;
 311 }
 312 sub fee_currency {
 313     my $self = shift;
 314     return $self->{currency} || 'USD';
 315 }
 316 sub owner {
 317     my $self = shift;
 318     return $self->{homebranch};
 319 }
 320 sub hold_queue {
 321     my $self = shift;
 322         (defined $self->{hold_queue}) or return [];
 323     return $self->{hold_queue};
 324 }
 325 sub pending_queue {
 326     my $self = shift;
 327         (defined $self->{pending_queue}) or return [];
 328     return $self->{pending_queue};
 329 }
 330 sub hold_attached {
 331     my $self = shift;
 332     (defined $self->{hold_attached}) or return [];
 333     return $self->{hold_attached};
 334 }
 335
 336 sub hold_queue_position {
 337         my ($self, $patron_id) = @_;
 338         ($self->{hold_queue}) or return 0;
 339         my $i = 0;
 340         foreach (@{$self->{hold_queue}}) {
 341                 $i++;
 342                 $_->{patron_id} or next;
 343                 if ($self->barcode_is_borrowernumber($patron_id, $_->{borrowernumber})) {
 344                         return $i;  # maybe should return $_->{priority}
 345                 }
 346         }
 347     return 0;
 348 }
 349
 350 sub due_date {
 351     my $self = shift;
 352     return $self->{due_date} || 0;
 353 }
 354 sub recall_date {
 355     my $self = shift;
 356     return $self->{recall_date} || 0;
 357 }
 358 sub hold_pickup_date {
 359     my $self = shift;
 360
 361     my $hold = Koha::Holds->find({ itemnumber => $self->{itemnumber}, found => 'W' });
 362     if ( $hold ) {
 363         return $hold->expirationdate || 0;
 364     }
 365
 366     return 0;
 367 }
 368
 369 # This is a partial check of "availability".  It is not supposed to check everything here.
 370 # An item is available for a patron if it is:
 371 # 1) checked out to the same patron
 372 #    AND no pending (i.e. non-W) hold queue
 373 # OR
 374 # 2) not checked out
 375 #    AND (not on hold_attached OR is on hold_attached for patron)
 376 #
 377 # What this means is we are consciously allowing the patron to checkout (but not renew) an item that DOES
 378 # have non-W holds on it, but has not been "picked" from the stacks.  That is to say, the
 379 # patron has retrieved the item before the librarian.
 380 #
 381 # We don't check if the patron is at the front of the pending queue in the first case, because
 382 # they should not be able to place a hold on an item they already have.
 383
 384 sub available {
 385         my ($self, $for_patron) = @_;
 386         my $count  = (defined $self->{pending_queue}) ? scalar @{$self->{pending_queue}} : 0;
 387     my $count2 = (defined $self->{hold_attached}   ) ? scalar @{$self->{hold_attached}   } : 0;
 388     if (defined($self->{borrowernumber})) {
 389         ($self->{borrowernumber} eq $for_patron) or return 0;
 390                 return ($count ? 0 : 1);
 391         } else {        # not checked out
 392         ($count2) and return $self->barcode_is_borrowernumber($for_patron, $self->{hold_attached}[0]->{borrowernumber});
 393         }
 394         return 0;
 395 }
 396
 397 sub _barcode_to_borrowernumber {
 398     my $known = shift;
 399     return unless defined $known;
 400     my $patron = Koha::Patrons->find( { cardnumber => $known } ) or return;
 401     return $patron->borrowernumber
 402 }
 403 sub barcode_is_borrowernumber {    # because hold_queue only has borrowernumber...
 404     my $self = shift;
 405     my $barcode = shift;
 406     my $number  = shift or return;    # can't be zero
 407     return unless defined $barcode; # might be 0 or 000 or 000000
 408     my $converted = _barcode_to_borrowernumber($barcode);
 409     return unless $converted;
 410     return ($number == $converted);
 411 }
 412
 413 =head2 build_additional_item_fields_string
 414
 415 This method builds the part of the sip message for additional item fields
 416 to send in the item related message responses
 417
 418 =cut
 419
 420 sub build_additional_item_fields_string {
 421     my ( $self, $server ) = @_;
 422
 423     my $string = q{};
 424
 425     if ( $server->{account}->{item_field} ) {
 426         my @fields_to_send =
 427           ref $server->{account}->{item_field} eq "ARRAY"
 428           ? @{ $server->{account}->{item_field} }
 429           : ( $server->{account}->{item_field} );
 430
 431         foreach my $f ( @fields_to_send ) {
 432             my $code = $f->{code};
 433             my $value = $self->{object}->$code;
 434             $string .= add_field( $f->{field}, $value );
 435         }
 436     }
 437
 438     if ( $server->{account}->{custom_item_field} ) {
 439         my @custom_fields =
 440             ref $server->{account}->{custom_item_field} eq "ARRAY"
 441             ? @{ $server->{account}->{custom_item_field} }
 442             : $server->{account}->{custom_item_field};
 443
 444         foreach my $custom_field ( @custom_fields ) {
 445             my $field = $custom_field->{field};
 446             return q{} unless defined $field;
 447             my $template = $custom_field->{template};
 448             my $formatted = $self->format( $template );
 449             my $substring = maybe_add( $field, $formatted, $server );
 450             $string .= $substring;
 451         }
 452     }
 453
 454     return $string;
 455 }
 456
 457 =head2 build_custom_field_string
 458
 459 This method builds the part of the sip message for custom item fields as defined in the sip config
 460
 461 =cut
 462
 463 sub build_custom_field_string {
 464     my ( $self, $server ) = @_;
 465
 466     my $string = q{};
 467
 468
 469     return $string;
 470 }
 471
 472 =head2 format
 473
 474 This method uses a template to build a string from a Koha::Item object
 475 If errors are encountered in processing template we log them and return nothing
 476
 477 =cut
 478
 479 sub format {
 480     my ( $self, $template ) = @_;
 481
 482     if ($template) {
 483         require Template;
 484
 485         my $tt = Template->new();
 486
 487         my $item = $self->{_object};
 488
 489         my $output;
 490         eval {
 491             $tt->process( \$template, { item => $item }, \$output );
 492         };
 493         if ( $@ ){
 494             siplog("LOG_DEBUG", "Error processing template: $template");
 495             return "";
 496         }
 497         return $output;
 498     }
 499 }
 500
 501 1;
 502 __END__
 503