C4/ILSDI/Services.pm

   1 package C4::ILSDI::Services;
   2
   3 # Copyright 2009 SARL Biblibre
   4 #
   5 # This file is part of Koha.
   6 #
   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.
  11 #
  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.
  16 #
  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>.
  19
  20 use strict;
  21 use warnings;
  22
  23 use C4::Members;
  24 use C4::Items;
  25 use C4::Circulation;
  26 use C4::Accounts;
  27 use C4::Biblio;
  28 use C4::Reserves qw(AddReserve CanBookBeReserved CanItemBeReserved IsAvailableForItemLevelRequest);
  29 use C4::Context;
  30 use C4::AuthoritiesMarc;
  31 use XML::Simple;
  32 use HTML::Entities;
  33 use CGI qw ( -utf8 );
  34 use DateTime;
  35 use C4::Auth;
  36 use C4::Members::Attributes qw(GetBorrowerAttributes);
  37 use Koha::DateUtils;
  38
  39 use Koha::Biblios;
  40 use Koha::Checkouts;
  41 use Koha::Items;
  42 use Koha::Libraries;
  43 use Koha::Patrons;
  44
  45 =head1 NAME
  46
  47 C4::ILS-DI::Services - ILS-DI Services
  48
  49 =head1 DESCRIPTION
  50
  51 Each function in this module represents an ILS-DI service.
  52 They all takes a CGI instance as argument and most of them return a
  53 hashref that will be printed by XML::Simple in opac/ilsdi.pl
  54
  55 =head1 SYNOPSIS
  56
  57     use C4::ILSDI::Services;
  58     use XML::Simple;
  59     use CGI qw ( -utf8 );
  60
  61     my $cgi = new CGI;
  62
  63     $out = LookupPatron($cgi);
  64
  65     print CGI::header('text/xml');
  66     print XMLout($out,
  67         noattr => 1,
  68         noescape => 1,
  69         nosort => 1,
  70                 xmldecl => '<?xml version="1.0" encoding="UTF-8" ?>',
  71         RootName => 'LookupPatron',
  72         SuppressEmpty => 1);
  73
  74 =cut
  75
  76 =head1 FUNCTIONS
  77
  78 =head2 GetAvailability
  79
  80 Given a set of biblionumbers or itemnumbers, returns a list with
  81 availability of the items associated with the identifiers.
  82
  83 Parameters:
  84
  85 =head3 id (Required)
  86
  87 list of either biblionumbers or itemnumbers
  88
  89 =head3 id_type (Required)
  90
  91 defines the type of record identifier being used in the request,
  92 possible values:
  93
  94   - bib
  95   - item
  96
  97 =head3 return_type (Optional)
  98
  99 requests a particular level of detail in reporting availability,
 100 possible values:
 101
 102   - bib
 103   - item
 104
 105 =head3 return_fmt (Optional)
 106
 107 requests a particular format or set of formats in reporting
 108 availability
 109
 110 =cut
 111
 112 sub GetAvailability {
 113     my ($cgi) = @_;
 114
 115     my $out = "<?xml version=\"1.0\" encoding=\"UTF-8\" ?>\n";
 116     $out .= "<dlf:collection\n";
 117     $out .= "  xmlns:dlf=\"http://diglib.org/ilsdi/1.1\"\n";
 118     $out .= "  xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n";
 119     $out .= "  xsi:schemaLocation=\"http://diglib.org/ilsdi/1.1\n";
 120     $out .= "    http://diglib.org/architectures/ilsdi/schemas/1.1/dlfexpanded.xsd\">\n";
 121
 122     foreach my $id ( split( / /, $cgi->param('id') ) ) {
 123         if ( $cgi->param('id_type') eq "item" ) {
 124             my ( $biblionumber, $status, $msg, $location ) = _availability($id);
 125
 126             $out .= "  <dlf:record>\n";
 127             $out .= "    <dlf:bibliographic id=\"" . ( $biblionumber || $id ) . "\" />\n";
 128             $out .= "    <dlf:items>\n";
 129             $out .= "      <dlf:item id=\"" . $id . "\">\n";
 130             $out .= "        <dlf:simpleavailability>\n";
 131             $out .= "          <dlf:identifier>" . $id . "</dlf:identifier>\n";
 132             $out .= "          <dlf:availabilitystatus>" . $status . "</dlf:availabilitystatus>\n";
 133             if ($msg)      { $out .= "          <dlf:availabilitymsg>" . $msg . "</dlf:availabilitymsg>\n"; }
 134             if ($location) { $out .= "          <dlf:location>" . $location . "</dlf:location>\n"; }
 135             $out .= "        </dlf:simpleavailability>\n";
 136             $out .= "      </dlf:item>\n";
 137             $out .= "    </dlf:items>\n";
 138             $out .= "  </dlf:record>\n";
 139         } else {
 140             my $status;
 141             my $msg;
 142             my $items = Koha::Items->search({ biblionumber => $id });
 143             if ($items->count) {
 144                 # Open XML
 145                 $out .= "  <dlf:record>\n";
 146                 $out .= "    <dlf:bibliographic id=\"" .$id. "\" />\n";
 147                 $out .= "    <dlf:items>\n";
 148                 # We loop over the items to clean them
 149                 while ( my $item = $items->next ) {
 150                     my $itemnumber = $item->itemnumber;
 151                     my ( $biblionumber, $status, $msg, $location ) = _availability($itemnumber);
 152                     $out .= "      <dlf:item id=\"" . $itemnumber . "\">\n";
 153                     $out .= "        <dlf:simpleavailability>\n";
 154                     $out .= "          <dlf:identifier>" . $itemnumber . "</dlf:identifier>\n";
 155                     $out .= "          <dlf:availabilitystatus>" . $status . "</dlf:availabilitystatus>\n";
 156                     if ($msg)      { $out .= "          <dlf:availabilitymsg>" . $msg . "</dlf:availabilitymsg>\n"; }
 157                     if ($location) { $out .= "          <dlf:location>" . $location . "</dlf:location>\n"; }
 158                     $out .= "        </dlf:simpleavailability>\n";
 159                     $out .= "      </dlf:item>\n";
 160                 }
 161                 # Close XML
 162                 $out .= "    </dlf:items>\n";
 163                 $out .= "  </dlf:record>\n";
 164             } else {
 165                 $status = "unknown";
 166                 $msg    = "Error: could not retrieve availability for this ID";
 167             }
 168         }
 169     }
 170     $out .= "</dlf:collection>\n";
 171
 172     return $out;
 173 }
 174
 175 =head2 GetRecords
 176
 177 Given a list of biblionumbers, returns a list of record objects that
 178 contain bibliographic information, as well as associated holdings and item
 179 information. The caller may request a specific metadata schema for the
 180 record objects to be returned.
 181
 182 This function behaves similarly to HarvestBibliographicRecords and
 183 HarvestExpandedRecords in Data Aggregation, but allows quick, real time
 184 lookup by bibliographic identifier.
 185
 186 You can use OAI-PMH ListRecords instead of this service.
 187
 188 Parameters:
 189
 190   - id (Required)
 191     list of system record identifiers
 192   - id_type (Optional)
 193     Defines the metadata schema in which the records are returned,
 194     possible values:
 195         - MARCXML
 196
 197 =cut
 198
 199 sub GetRecords {
 200     my ($cgi) = @_;
 201
 202     # Check if the schema is supported. For now, GetRecords only supports MARCXML
 203     if ( $cgi->param('schema') and $cgi->param('schema') ne "MARCXML" ) {
 204         return { code => 'UnsupportedSchema' };
 205     }
 206
 207     my @records;
 208
 209     # Loop over biblionumbers
 210     foreach my $biblionumber ( split( / /, $cgi->param('id') ) ) {
 211
 212         # Get the biblioitem from the biblionumber
 213         my $biblio = Koha::Biblios->find( $biblionumber );
 214         unless ( $biblio ) {
 215             push @records, { code => "RecordNotFound" };
 216             next;
 217         }
 218
 219         my $biblioitem = $biblio->biblioitem->unblessed;
 220
 221         my $embed_items = 1;
 222         my $record = GetMarcBiblio({
 223             biblionumber => $biblionumber,
 224             embed_items  => $embed_items });
 225         if ($record) {
 226             $biblioitem->{marcxml} = $record->as_xml_record();
 227         }
 228
 229         # Get most of the needed data
 230         my $biblioitemnumber = $biblioitem->{'biblioitemnumber'};
 231         my $holds  = $biblio->current_holds->unblessed;
 232         my $issues           = GetBiblioIssues($biblionumber);
 233         my $items            = $biblio->items->unblessed;
 234
 235         # We loop over the items to clean them
 236         foreach my $item (@$items) {
 237
 238             # This hides additionnal XML subfields, we don't need these info
 239             delete $item->{'more_subfields_xml'};
 240
 241             # Display branch names instead of branch codes
 242             my $home_library    = Koha::Libraries->find( $item->{homebranch} );
 243             my $holding_library = Koha::Libraries->find( $item->{holdingbranch} );
 244             $item->{'homebranchname'}    = $home_library    ? $home_library->branchname    : '';
 245             $item->{'holdingbranchname'} = $holding_library ? $holding_library->branchname : '';
 246         }
 247
 248         # Hashref building...
 249         $biblioitem->{'items'}->{'item'}       = $items;
 250         $biblioitem->{'reserves'}->{'reserve'} = $holds;
 251         $biblioitem->{'issues'}->{'issue'}     = $issues;
 252
 253         push @records, $biblioitem;
 254     }
 255
 256     return { record => \@records };
 257 }
 258
 259 =head2 GetAuthorityRecords
 260
 261 Given a list of authority record identifiers, returns a list of record
 262 objects that contain the authority records. The function user may request
 263 a specific metadata schema for the record objects.
 264
 265 Parameters:
 266
 267   - id (Required)
 268     list of authority record identifiers
 269   - schema (Optional)
 270     specifies the metadata schema of records to be returned, possible values:
 271       - MARCXML
 272
 273 =cut
 274
 275 sub GetAuthorityRecords {
 276     my ($cgi) = @_;
 277
 278     # If the user asks for an unsupported schema, return an error code
 279     if ( $cgi->param('schema') and $cgi->param('schema') ne "MARCXML" ) {
 280         return { code => 'UnsupportedSchema' };
 281     }
 282
 283     my @records;
 284
 285     # Let's loop over the authority IDs
 286     foreach my $authid ( split( / /, $cgi->param('id') ) ) {
 287
 288         # Get the record as XML string, or error code
 289         push @records, GetAuthorityXML($authid) || { code => 'RecordNotFound' };
 290     }
 291
 292     return { record => \@records };
 293 }
 294
 295 =head2 LookupPatron
 296
 297 Looks up a patron in the ILS by an identifier, and returns the borrowernumber.
 298
 299 Parameters:
 300
 301   - id (Required)
 302     an identifier used to look up the patron in Koha
 303   - id_type (Optional)
 304     the type of the identifier, possible values:
 305     - cardnumber
 306     - userid
 307         - email
 308     - borrowernumber
 309     - firstname
 310         - surname
 311
 312 =cut
 313
 314 sub LookupPatron {
 315     my ($cgi) = @_;
 316
 317     my $id      = $cgi->param('id');
 318     if(!$id) {
 319         return { message => 'PatronNotFound' };
 320     }
 321
 322     my $patrons;
 323     my $passed_id_type = $cgi->param('id_type');
 324     if($passed_id_type) {
 325         $patrons = Koha::Patrons->search( { $passed_id_type => $id } );
 326     } else {
 327         foreach my $id_type ('cardnumber', 'userid', 'email', 'borrowernumber',
 328                      'surname', 'firstname') {
 329             $patrons = Koha::Patrons->search( { $id_type => $id } );
 330             last if($patrons->count);
 331         }
 332     }
 333     unless ( $patrons->count ) {
 334         return { message => 'PatronNotFound' };
 335     }
 336
 337     return { id => $patrons->next->borrowernumber };
 338 }
 339
 340 =head2 AuthenticatePatron
 341
 342 Authenticates a user's login credentials and returns the identifier for
 343 the patron.
 344
 345 Parameters:
 346
 347   - username (Required)
 348     user's login identifier (userid or cardnumber)
 349   - password (Required)
 350     user's password
 351
 352 =cut
 353
 354 sub AuthenticatePatron {
 355     my ($cgi) = @_;
 356     my $username = $cgi->param('username');
 357     my $password = $cgi->param('password');
 358     my ($status, $cardnumber, $userid) = C4::Auth::checkpw( C4::Context->dbh, $username, $password );
 359     if ( $status ) {
 360         # Get the borrower
 361         my $patron = Koha::Patrons->find( { userid => $userid } );
 362         return { id => $patron->borrowernumber };
 363     }
 364     else {
 365         return { code => 'PatronNotFound' };
 366     }
 367 }
 368
 369 =head2 GetPatronInfo
 370
 371 Returns specified information about the patron, based on options in the
 372 request. This function can optionally return patron's contact information,
 373 fine information, hold request information, and loan information.
 374
 375 Parameters:
 376
 377   - patron_id (Required)
 378     the borrowernumber
 379   - show_contact (Optional, default 1)
 380     whether or not to return patron's contact information in the response
 381   - show_fines (Optional, default 0)
 382     whether or not to return fine information in the response
 383   - show_holds (Optional, default 0)
 384     whether or not to return hold request information in the response
 385   - show_loans (Optional, default 0)
 386     whether or not to return loan information request information in the response
 387   - show_attributes (Optional, default 0)
 388     whether or not to return additional patron attributes, when enabled the attributes
 389     are limited to those marked as opac visible only.
 390
 391 =cut
 392
 393 sub GetPatronInfo {
 394     my ($cgi) = @_;
 395
 396     # Get Member details
 397     my $borrowernumber = $cgi->param('patron_id');
 398     my $patron = Koha::Patrons->find( $borrowernumber );
 399     return { code => 'PatronNotFound' } unless $patron;
 400
 401     # Cleaning the borrower hashref
 402     my $borrower = $patron->unblessed;
 403     $borrower->{charges} = sprintf "%.02f", $patron->account->non_issues_charges; # FIXME Formatting should not be done here
 404     my $library = Koha::Libraries->find( $borrower->{branchcode} );
 405     $borrower->{'branchname'} = $library ? $library->branchname : '';
 406     delete $borrower->{'userid'};
 407     delete $borrower->{'password'};
 408
 409     # Contact fields management
 410     if ( defined $cgi->param('show_contact') && $cgi->param('show_contact') eq "0" ) {
 411
 412         # Define contact fields
 413         my @contactfields = (
 414             'email',              'emailpro',           'fax',                 'mobile',          'phone',             'phonepro',
 415             'streetnumber',       'zipcode',            'city',                'streettype',      'B_address',         'B_city',
 416             'B_email',            'B_phone',            'B_zipcode',           'address',         'address2',          'altcontactaddress1',
 417             'altcontactaddress2', 'altcontactaddress3', 'altcontactfirstname', 'altcontactphone', 'altcontactsurname', 'altcontactzipcode'
 418         );
 419
 420         # and delete them
 421         foreach my $field (@contactfields) {
 422             delete $borrower->{$field};
 423         }
 424     }
 425
 426     # Fines management
 427     if ( $cgi->param('show_fines') && $cgi->param('show_fines') eq "1" ) {
 428         $borrower->{fines}{fine} = $patron->account->lines->unblessed;
 429     }
 430
 431     # Reserves management
 432     if ( $cgi->param('show_holds') && $cgi->param('show_holds') eq "1" ) {
 433
 434         # Get borrower's reserves
 435         my $holds = $patron->holds;
 436         while ( my $hold = $holds->next ) {
 437
 438             my ( $item, $biblio, $biblioitem ) = ( {}, {}, {} );
 439             # Get additional informations
 440             if ( $hold->itemnumber ) {    # item level holds
 441                 $item       = Koha::Items->find( $hold->itemnumber );
 442                 $biblio     = $item->biblio;
 443                 $biblioitem = $biblio->biblioitem;
 444
 445                 # Remove unwanted fields
 446                 $item = $item->unblessed;
 447                 delete $item->{more_subfields_xml};
 448                 $biblio     = $biblio->unblessed;
 449                 $biblioitem = $biblioitem->unblessed;
 450             }
 451
 452             # Add additional fields
 453             my $unblessed_hold = $hold->unblessed;
 454             $unblessed_hold->{item}       = { %$item, %$biblio, %$biblioitem };
 455             my $library = Koha::Libraries->find( $hold->branchcode );
 456             my $branchname = $library ? $library->branchname : '';
 457             $unblessed_hold->{branchname} = $branchname;
 458             $biblio = Koha::Biblios->find( $hold->biblionumber ); # Should be $hold->get_biblio
 459             $unblessed_hold->{title} = $biblio ? $biblio->title : ''; # Just in case, but should not be needed
 460
 461             push @{ $borrower->{holds}{hold} }, $unblessed_hold;
 462
 463         }
 464     }
 465
 466     # Issues management
 467     if ( $cgi->param('show_loans') && $cgi->param('show_loans') eq "1" ) {
 468         my $pending_checkouts = $patron->pending_checkouts;
 469         my @checkouts;
 470         while ( my $c = $pending_checkouts->next ) {
 471             # FIXME We should only retrieve what is needed in the template
 472             my $issue = $c->unblessed_all_relateds;
 473             push @checkouts, $issue
 474         }
 475         $borrower->{'loans'}->{'loan'} = \@checkouts;
 476     }
 477
 478     if ( $cgi->param('show_attributes') eq "1" ) {
 479         my $attrs = GetBorrowerAttributes( $borrowernumber, 1 );
 480         $borrower->{'attributes'} = $attrs;
 481     }
 482
 483     # Add is expired information
 484     $borrower->{'is_expired'} = $patron->is_expired ? 1 : 0;
 485
 486     return $borrower;
 487 }
 488
 489 =head2 GetPatronStatus
 490
 491 Returns a patron's status information.
 492
 493 Parameters:
 494
 495   - patron_id (Required)
 496     the borrower ID
 497
 498 =cut
 499
 500 sub GetPatronStatus {
 501     my ($cgi) = @_;
 502
 503     # Get Member details
 504     my $borrowernumber = $cgi->param('patron_id');
 505     my $patron = Koha::Patrons->find( $borrowernumber );
 506     return { code => 'PatronNotFound' } unless $patron;
 507
 508     # Return the results
 509     return {
 510         type   => $patron->categorycode,
 511         status => 0, # TODO
 512         expiry => $patron->dateexpiry,
 513     };
 514 }
 515
 516 =head2 GetServices
 517
 518 Returns information about the services available on a particular item for
 519 a particular patron.
 520
 521 Parameters:
 522
 523   - patron_id (Required)
 524     a borrowernumber
 525   - item_id (Required)
 526     an itemnumber
 527
 528 =cut
 529
 530 sub GetServices {
 531     my ($cgi) = @_;
 532
 533     # Get the member, or return an error code if not found
 534     my $borrowernumber = $cgi->param('patron_id');
 535     my $patron = Koha::Patrons->find( $borrowernumber );
 536     return { code => 'PatronNotFound' } unless $patron;
 537
 538     my $borrower = $patron->unblessed;
 539     # Get the item, or return an error code if not found
 540     my $itemnumber = $cgi->param('item_id');
 541     my $item = Koha::Items->find($itemnumber);
 542     return { code => 'RecordNotFound' } unless $item;
 543
 544     my @availablefor;
 545
 546     # Reserve level management
 547     my $biblionumber = $item->biblionumber;
 548     my $canbookbereserved = CanBookBeReserved( $borrower, $biblionumber );
 549     if ($canbookbereserved->{status} eq 'OK') {
 550         push @availablefor, 'title level hold';
 551         my $canitembereserved = IsAvailableForItemLevelRequest($item->unblessed, $borrower);
 552         if ($canitembereserved) {
 553             push @availablefor, 'item level hold';
 554         }
 555     }
 556
 557     # Reserve cancellation management
 558     my $holds = $patron->holds;
 559     my @reserveditems;
 560     while ( my $hold = $holds->next ) { # FIXME This could be improved
 561         push @reserveditems, $hold->itemnumber;
 562     }
 563     if ( grep { $itemnumber eq $_ } @reserveditems ) {
 564         push @availablefor, 'hold cancellation';
 565     }
 566
 567     # Renewal management
 568     my @renewal = CanBookBeRenewed( $borrowernumber, $itemnumber );
 569     if ( $renewal[0] ) {
 570         push @availablefor, 'loan renewal';
 571     }
 572
 573     # Issuing management
 574     my $barcode = $item->barcode || '';
 575     $barcode = barcodedecode($barcode) if ( $barcode && C4::Context->preference('itemBarcodeInputFilter') );
 576     if ($barcode) {
 577         my ( $issuingimpossible, $needsconfirmation ) = CanBookBeIssued( $patron, $barcode );
 578
 579         # TODO push @availablefor, 'loan';
 580     }
 581
 582     my $out;
 583     $out->{'AvailableFor'} = \@availablefor;
 584
 585     return $out;
 586 }
 587
 588 =head2 RenewLoan
 589
 590 Extends the due date for a borrower's existing issue.
 591
 592 Parameters:
 593
 594   - patron_id (Required)
 595     a borrowernumber
 596   - item_id (Required)
 597     an itemnumber
 598   - desired_due_date (Required)
 599     the date the patron would like the item returned by
 600
 601 =cut
 602
 603 sub RenewLoan {
 604     my ($cgi) = @_;
 605
 606     # Get borrower infos or return an error code
 607     my $borrowernumber = $cgi->param('patron_id');
 608     my $patron = Koha::Patrons->find( $borrowernumber );
 609     return { code => 'PatronNotFound' } unless $patron;
 610
 611     # Get the item, or return an error code
 612     my $itemnumber = $cgi->param('item_id');
 613     my $item = Koha::Items->find($itemnumber);
 614     return { code => 'RecordNotFound' } unless $item;
 615
 616     # Add renewal if possible
 617     my @renewal = CanBookBeRenewed( $borrowernumber, $itemnumber );
 618     if ( $renewal[0] ) { AddRenewal( $borrowernumber, $itemnumber ); }
 619
 620     return unless $item; # FIXME should be handled
 621
 622     my $issue = $item->checkout;
 623     return $issue; # FIXME should be handled
 624
 625     # Hashref building
 626     my $out;
 627     $out->{'renewals'} = $issue->renewals;
 628     $out->{date_due}   = dt_from_string($issue->date_due)->strftime('%Y-%m-%d %H:%S');
 629     $out->{'success'}  = $renewal[0];
 630     $out->{'error'}    = $renewal[1];
 631
 632     return $out;
 633 }
 634
 635 =head2 HoldTitle
 636
 637 Creates, for a borrower, a biblio-level hold reserve.
 638
 639 Parameters:
 640
 641   - patron_id (Required)
 642     a borrowernumber
 643   - bib_id (Required)
 644     a biblionumber
 645   - request_location (Required)
 646     IP address where the end user request is being placed
 647   - pickup_location (Optional)
 648     a branch code indicating the location to which to deliver the item for pickup
 649   - needed_before_date (Optional)
 650     date after which hold request is no longer needed
 651   - pickup_expiry_date (Optional)
 652     date after which item returned to shelf if item is not picked up
 653
 654 =cut
 655
 656 sub HoldTitle {
 657     my ($cgi) = @_;
 658
 659     # Get the borrower or return an error code
 660     my $borrowernumber = $cgi->param('patron_id');
 661     my $patron = Koha::Patrons->find( $borrowernumber );
 662     return { code => 'PatronNotFound' } unless $patron;
 663
 664     # Get the biblio record, or return an error code
 665     my $biblionumber = $cgi->param('bib_id');
 666     my $biblio = Koha::Biblios->find( $biblionumber );
 667     return { code => 'RecordNotFound' } unless $biblio;
 668
 669     my @hostitems = get_hostitemnumbers_of($biblionumber);
 670     my @itemnumbers;
 671     if (@hostitems){
 672         push(@itemnumbers, @hostitems);
 673     }
 674
 675     my $items = Koha::Items->search({ -or => { biblionumber => $biblionumber, itemnumber => { in => \@itemnumbers } } });
 676
 677     unless ( $items->count ) {
 678         return { code => 'NoItems' };
 679     }
 680
 681     my $title = $biblio ? $biblio->title : '';
 682
 683     # Check if the biblio can be reserved
 684     my $code = CanBookBeReserved( $borrowernumber, $biblionumber )->{status};
 685     return { code => $code } unless ( $code eq 'OK' );
 686
 687     my $branch;
 688
 689     # Pickup branch management
 690     if ( $cgi->param('pickup_location') ) {
 691         $branch = $cgi->param('pickup_location');
 692         return { code => 'LocationNotFound' } unless Koha::Libraries->find($branch);
 693     } else { # if the request provide no branch, use the borrower's branch
 694         $branch = $patron->branchcode;
 695     }
 696
 697     # Add the reserve
 698     #    $branch,    $borrowernumber, $biblionumber,
 699     #    $constraint, $bibitems,  $priority, $resdate, $expdate, $notes,
 700     #    $title,      $checkitem, $found
 701     my $priority= C4::Reserves::CalculatePriority( $biblionumber );
 702     AddReserve( $branch, $borrowernumber, $biblionumber, undef, $priority, undef, undef, undef, $title, undef, undef );
 703
 704     # Hashref building
 705     my $out;
 706     $out->{'title'}           = $title;
 707     my $library = Koha::Libraries->find( $branch );
 708     $out->{'pickup_location'} = $library ? $library->branchname : '';
 709
 710     # TODO $out->{'date_available'}  = '';
 711
 712     return $out;
 713 }
 714
 715 =head2 HoldItem
 716
 717 Creates, for a borrower, an item-level hold request on a specific item of
 718 a bibliographic record in Koha.
 719
 720 Parameters:
 721
 722   - patron_id (Required)
 723     a borrowernumber
 724   - bib_id (Required)
 725     a biblionumber
 726   - item_id (Required)
 727     an itemnumber
 728   - pickup_location (Optional)
 729     a branch code indicating the location to which to deliver the item for pickup
 730   - needed_before_date (Optional)
 731     date after which hold request is no longer needed
 732   - pickup_expiry_date (Optional)
 733     date after which item returned to shelf if item is not picked up
 734
 735 =cut
 736
 737 sub HoldItem {
 738     my ($cgi) = @_;
 739
 740     # Get the borrower or return an error code
 741     my $borrowernumber = $cgi->param('patron_id');
 742     my $patron = Koha::Patrons->find( $borrowernumber );
 743     return { code => 'PatronNotFound' } unless $patron;
 744
 745     # Get the biblio or return an error code
 746     my $biblionumber = $cgi->param('bib_id');
 747     my $biblio = Koha::Biblios->find( $biblionumber );
 748     return { code => 'RecordNotFound' } unless $biblio;
 749
 750     my $title = $biblio ? $biblio->title : '';
 751
 752     # Get the item or return an error code
 753     my $itemnumber = $cgi->param('item_id');
 754     my $item = Koha::Items->find($itemnumber);
 755     return { code => 'RecordNotFound' } unless $item;
 756
 757     # If the biblio does not match the item, return an error code
 758     return { code => 'RecordNotFound' } if $item->biblionumber ne $biblio->biblionumber;
 759
 760     # Check for item disponibility
 761     my $canitembereserved = C4::Reserves::CanItemBeReserved( $borrowernumber, $itemnumber )->{status};
 762     return { code => $canitembereserved } unless $canitembereserved eq 'OK';
 763
 764     # Pickup branch management
 765     my $branch;
 766     if ( $cgi->param('pickup_location') ) {
 767         $branch = $cgi->param('pickup_location');
 768         return { code => 'LocationNotFound' } unless Koha::Libraries->find($branch);
 769     } else { # if the request provide no branch, use the borrower's branch
 770         $branch = $patron->branchcode;
 771     }
 772
 773     # Add the reserve
 774     #    $branch,    $borrowernumber, $biblionumber,
 775     #    $constraint, $bibitems,  $priority, $resdate, $expdate, $notes,
 776     #    $title,      $checkitem, $found
 777     my $priority= C4::Reserves::CalculatePriority( $biblionumber );
 778     AddReserve( $branch, $borrowernumber, $biblionumber, undef, $priority, undef, undef, undef, $title, $itemnumber, undef );
 779
 780     # Hashref building
 781     my $out;
 782     my $library = Koha::Libraries->find( $branch );
 783     $out->{'pickup_location'} = $library ? $library->branchname : '';
 784
 785     # TODO $out->{'date_available'} = '';
 786
 787     return $out;
 788 }
 789
 790 =head2 CancelHold
 791
 792 Cancels an active reserve request for the borrower.
 793
 794 Parameters:
 795
 796   - patron_id (Required)
 797         a borrowernumber
 798   - item_id (Required)
 799         a reserve_id
 800
 801 =cut
 802
 803 sub CancelHold {
 804     my ($cgi) = @_;
 805
 806     # Get the borrower or return an error code
 807     my $borrowernumber = $cgi->param('patron_id');
 808     my $patron = Koha::Patrons->find( $borrowernumber );
 809     return { code => 'PatronNotFound' } unless $patron;
 810
 811     # Get the reserve or return an error code
 812     my $reserve_id = $cgi->param('item_id');
 813     my $hold = Koha::Holds->find( $reserve_id );
 814     return { code => 'RecordNotFound' } unless $hold;
 815     return { code => 'RecordNotFound' } unless ($hold->borrowernumber == $borrowernumber);
 816
 817     $hold->cancel;
 818
 819     return { code => 'Canceled' };
 820 }
 821
 822 =head2 _availability
 823
 824 Returns, for an itemnumber, an array containing availability information.
 825
 826  my ($biblionumber, $status, $msg, $location) = _availability($id);
 827
 828 =cut
 829
 830 sub _availability {
 831     my ($itemnumber) = @_;
 832     my $item = Koha::Items->find($itemnumber);
 833
 834     unless ( $item ) {
 835         return ( undef, 'unknown', 'Error: could not retrieve availability for this ID', undef );
 836     }
 837
 838     my $biblionumber = $item->biblioitemnumber;
 839     my $library = Koha::Libraries->find( $item->holdingbranch );
 840     my $location = $library ? $library->branchname : '';
 841
 842     if ( $item->notforloan ) {
 843         return ( $biblionumber, 'not available', 'Not for loan', $location );
 844     } elsif ( $item->onloan ) {
 845         return ( $biblionumber, 'not available', 'Checked out', $location );
 846     } elsif ( $item->itemlost ) {
 847         return ( $biblionumber, 'not available', 'Item lost', $location );
 848     } elsif ( $item->withdrawn ) {
 849         return ( $biblionumber, 'not available', 'Item withdrawn', $location );
 850     } elsif ( $item->damaged ) {
 851         return ( $biblionumber, 'not available', 'Item damaged', $location );
 852     } else {
 853         return ( $biblionumber, 'available', undef, $location );
 854     }
 855 }
 856
 857 1;