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     return $borrower;
 484 }
 485
 486 =head2 GetPatronStatus
 487
 488 Returns a patron's status information.
 489
 490 Parameters:
 491
 492   - patron_id (Required)
 493     the borrower ID
 494
 495 =cut
 496
 497 sub GetPatronStatus {
 498     my ($cgi) = @_;
 499
 500     # Get Member details
 501     my $borrowernumber = $cgi->param('patron_id');
 502     my $patron = Koha::Patrons->find( $borrowernumber );
 503     return { code => 'PatronNotFound' } unless $patron;
 504
 505     # Return the results
 506     return {
 507         type   => $patron->categorycode,
 508         status => 0, # TODO
 509         expiry => $patron->dateexpiry,
 510     };
 511 }
 512
 513 =head2 GetServices
 514
 515 Returns information about the services available on a particular item for
 516 a particular patron.
 517
 518 Parameters:
 519
 520   - patron_id (Required)
 521     a borrowernumber
 522   - item_id (Required)
 523     an itemnumber
 524
 525 =cut
 526
 527 sub GetServices {
 528     my ($cgi) = @_;
 529
 530     # Get the member, or return an error code if not found
 531     my $borrowernumber = $cgi->param('patron_id');
 532     my $patron = Koha::Patrons->find( $borrowernumber );
 533     return { code => 'PatronNotFound' } unless $patron;
 534
 535     my $borrower = $patron->unblessed;
 536     # Get the item, or return an error code if not found
 537     my $itemnumber = $cgi->param('item_id');
 538     my $item = Koha::Items->find($itemnumber);
 539     return { code => 'RecordNotFound' } unless $item;
 540
 541     my @availablefor;
 542
 543     # Reserve level management
 544     my $biblionumber = $item->biblionumber;
 545     my $canbookbereserved = CanBookBeReserved( $borrower, $biblionumber );
 546     if ($canbookbereserved->{status} eq 'OK') {
 547         push @availablefor, 'title level hold';
 548         my $canitembereserved = IsAvailableForItemLevelRequest($item->unblessed, $borrower);
 549         if ($canitembereserved) {
 550             push @availablefor, 'item level hold';
 551         }
 552     }
 553
 554     # Reserve cancellation management
 555     my $holds = $patron->holds;
 556     my @reserveditems;
 557     while ( my $hold = $holds->next ) { # FIXME This could be improved
 558         push @reserveditems, $hold->itemnumber;
 559     }
 560     if ( grep { $itemnumber eq $_ } @reserveditems ) {
 561         push @availablefor, 'hold cancellation';
 562     }
 563
 564     # Renewal management
 565     my @renewal = CanBookBeRenewed( $borrowernumber, $itemnumber );
 566     if ( $renewal[0] ) {
 567         push @availablefor, 'loan renewal';
 568     }
 569
 570     # Issuing management
 571     my $barcode = $item->barcode || '';
 572     $barcode = barcodedecode($barcode) if ( $barcode && C4::Context->preference('itemBarcodeInputFilter') );
 573     if ($barcode) {
 574         my ( $issuingimpossible, $needsconfirmation ) = CanBookBeIssued( $patron, $barcode );
 575
 576         # TODO push @availablefor, 'loan';
 577     }
 578
 579     my $out;
 580     $out->{'AvailableFor'} = \@availablefor;
 581
 582     return $out;
 583 }
 584
 585 =head2 RenewLoan
 586
 587 Extends the due date for a borrower's existing issue.
 588
 589 Parameters:
 590
 591   - patron_id (Required)
 592     a borrowernumber
 593   - item_id (Required)
 594     an itemnumber
 595   - desired_due_date (Required)
 596     the date the patron would like the item returned by
 597
 598 =cut
 599
 600 sub RenewLoan {
 601     my ($cgi) = @_;
 602
 603     # Get borrower infos or return an error code
 604     my $borrowernumber = $cgi->param('patron_id');
 605     my $patron = Koha::Patrons->find( $borrowernumber );
 606     return { code => 'PatronNotFound' } unless $patron;
 607
 608     # Get the item, or return an error code
 609     my $itemnumber = $cgi->param('item_id');
 610     my $item = Koha::Items->find($itemnumber);
 611     return { code => 'RecordNotFound' } unless $item;
 612
 613     # Add renewal if possible
 614     my @renewal = CanBookBeRenewed( $borrowernumber, $itemnumber );
 615     if ( $renewal[0] ) { AddRenewal( $borrowernumber, $itemnumber ); }
 616
 617     return unless $item; # FIXME should be handled
 618
 619     my $issue = $item->checkout;
 620     return $issue; # FIXME should be handled
 621
 622     # Hashref building
 623     my $out;
 624     $out->{'renewals'} = $issue->renewals;
 625     $out->{date_due}   = dt_from_string($issue->date_due)->strftime('%Y-%m-%d %H:%S');
 626     $out->{'success'}  = $renewal[0];
 627     $out->{'error'}    = $renewal[1];
 628
 629     return $out;
 630 }
 631
 632 =head2 HoldTitle
 633
 634 Creates, for a borrower, a biblio-level hold reserve.
 635
 636 Parameters:
 637
 638   - patron_id (Required)
 639     a borrowernumber
 640   - bib_id (Required)
 641     a biblionumber
 642   - request_location (Required)
 643     IP address where the end user request is being placed
 644   - pickup_location (Optional)
 645     a branch code indicating the location to which to deliver the item for pickup
 646   - needed_before_date (Optional)
 647     date after which hold request is no longer needed
 648   - pickup_expiry_date (Optional)
 649     date after which item returned to shelf if item is not picked up
 650
 651 =cut
 652
 653 sub HoldTitle {
 654     my ($cgi) = @_;
 655
 656     # Get the borrower or return an error code
 657     my $borrowernumber = $cgi->param('patron_id');
 658     my $patron = Koha::Patrons->find( $borrowernumber );
 659     return { code => 'PatronNotFound' } unless $patron;
 660
 661     # Get the biblio record, or return an error code
 662     my $biblionumber = $cgi->param('bib_id');
 663     my $biblio = Koha::Biblios->find( $biblionumber );
 664     return { code => 'RecordNotFound' } unless $biblio;
 665
 666     my @hostitems = get_hostitemnumbers_of($biblionumber);
 667     my @itemnumbers;
 668     if (@hostitems){
 669         push(@itemnumbers, @hostitems);
 670     }
 671
 672     my $items = Koha::Items->search({ -or => { biblionumber => $biblionumber, itemnumber => { in => \@itemnumbers } } });
 673
 674     unless ( $items->count ) {
 675         return { code => 'NoItems' };
 676     }
 677
 678     my $title = $biblio ? $biblio->title : '';
 679
 680     # Check if the biblio can be reserved
 681     my $code = CanBookBeReserved( $borrowernumber, $biblionumber )->{status};
 682     return { code => $code } unless ( $code eq 'OK' );
 683
 684     my $branch;
 685
 686     # Pickup branch management
 687     if ( $cgi->param('pickup_location') ) {
 688         $branch = $cgi->param('pickup_location');
 689         return { code => 'LocationNotFound' } unless Koha::Libraries->find($branch);
 690     } else { # if the request provide no branch, use the borrower's branch
 691         $branch = $patron->branchcode;
 692     }
 693
 694     # Add the reserve
 695     #    $branch,    $borrowernumber, $biblionumber,
 696     #    $constraint, $bibitems,  $priority, $resdate, $expdate, $notes,
 697     #    $title,      $checkitem, $found
 698     my $priority= C4::Reserves::CalculatePriority( $biblionumber );
 699     AddReserve( $branch, $borrowernumber, $biblionumber, undef, $priority, undef, undef, undef, $title, undef, undef );
 700
 701     # Hashref building
 702     my $out;
 703     $out->{'title'}           = $title;
 704     my $library = Koha::Libraries->find( $branch );
 705     $out->{'pickup_location'} = $library ? $library->branchname : '';
 706
 707     # TODO $out->{'date_available'}  = '';
 708
 709     return $out;
 710 }
 711
 712 =head2 HoldItem
 713
 714 Creates, for a borrower, an item-level hold request on a specific item of
 715 a bibliographic record in Koha.
 716
 717 Parameters:
 718
 719   - patron_id (Required)
 720     a borrowernumber
 721   - bib_id (Required)
 722     a biblionumber
 723   - item_id (Required)
 724     an itemnumber
 725   - pickup_location (Optional)
 726     a branch code indicating the location to which to deliver the item for pickup
 727   - needed_before_date (Optional)
 728     date after which hold request is no longer needed
 729   - pickup_expiry_date (Optional)
 730     date after which item returned to shelf if item is not picked up
 731
 732 =cut
 733
 734 sub HoldItem {
 735     my ($cgi) = @_;
 736
 737     # Get the borrower or return an error code
 738     my $borrowernumber = $cgi->param('patron_id');
 739     my $patron = Koha::Patrons->find( $borrowernumber );
 740     return { code => 'PatronNotFound' } unless $patron;
 741
 742     # Get the biblio or return an error code
 743     my $biblionumber = $cgi->param('bib_id');
 744     my $biblio = Koha::Biblios->find( $biblionumber );
 745     return { code => 'RecordNotFound' } unless $biblio;
 746
 747     my $title = $biblio ? $biblio->title : '';
 748
 749     # Get the item or return an error code
 750     my $itemnumber = $cgi->param('item_id');
 751     my $item = Koha::Items->find($itemnumber);
 752     return { code => 'RecordNotFound' } unless $item;
 753
 754     # If the biblio does not match the item, return an error code
 755     return { code => 'RecordNotFound' } if $item->biblionumber ne $biblio->biblionumber;
 756
 757     # Check for item disponibility
 758     my $canitembereserved = C4::Reserves::CanItemBeReserved( $borrowernumber, $itemnumber )->{status};
 759     return { code => $canitembereserved } unless $canitembereserved eq 'OK';
 760
 761     # Pickup branch management
 762     my $branch;
 763     if ( $cgi->param('pickup_location') ) {
 764         $branch = $cgi->param('pickup_location');
 765         return { code => 'LocationNotFound' } unless Koha::Libraries->find($branch);
 766     } else { # if the request provide no branch, use the borrower's branch
 767         $branch = $patron->branchcode;
 768     }
 769
 770     # Add the reserve
 771     #    $branch,    $borrowernumber, $biblionumber,
 772     #    $constraint, $bibitems,  $priority, $resdate, $expdate, $notes,
 773     #    $title,      $checkitem, $found
 774     my $priority= C4::Reserves::CalculatePriority( $biblionumber );
 775     AddReserve( $branch, $borrowernumber, $biblionumber, undef, $priority, undef, undef, undef, $title, $itemnumber, undef );
 776
 777     # Hashref building
 778     my $out;
 779     my $library = Koha::Libraries->find( $branch );
 780     $out->{'pickup_location'} = $library ? $library->branchname : '';
 781
 782     # TODO $out->{'date_available'} = '';
 783
 784     return $out;
 785 }
 786
 787 =head2 CancelHold
 788
 789 Cancels an active reserve request for the borrower.
 790
 791 Parameters:
 792
 793   - patron_id (Required)
 794         a borrowernumber
 795   - item_id (Required)
 796         a reserve_id
 797
 798 =cut
 799
 800 sub CancelHold {
 801     my ($cgi) = @_;
 802
 803     # Get the borrower or return an error code
 804     my $borrowernumber = $cgi->param('patron_id');
 805     my $patron = Koha::Patrons->find( $borrowernumber );
 806     return { code => 'PatronNotFound' } unless $patron;
 807
 808     # Get the reserve or return an error code
 809     my $reserve_id = $cgi->param('item_id');
 810     my $hold = Koha::Holds->find( $reserve_id );
 811     return { code => 'RecordNotFound' } unless $hold;
 812     return { code => 'RecordNotFound' } unless ($hold->borrowernumber == $borrowernumber);
 813
 814     $hold->cancel;
 815
 816     return { code => 'Canceled' };
 817 }
 818
 819 =head2 _availability
 820
 821 Returns, for an itemnumber, an array containing availability information.
 822
 823  my ($biblionumber, $status, $msg, $location) = _availability($id);
 824
 825 =cut
 826
 827 sub _availability {
 828     my ($itemnumber) = @_;
 829     my $item = Koha::Items->find($itemnumber);
 830
 831     unless ( $item ) {
 832         return ( undef, 'unknown', 'Error: could not retrieve availability for this ID', undef );
 833     }
 834
 835     my $biblionumber = $item->biblioitemnumber;
 836     my $library = Koha::Libraries->find( $item->holdingbranch );
 837     my $location = $library ? $library->branchname : '';
 838
 839     if ( $item->notforloan ) {
 840         return ( $biblionumber, 'not available', 'Not for loan', $location );
 841     } elsif ( $item->onloan ) {
 842         return ( $biblionumber, 'not available', 'Checked out', $location );
 843     } elsif ( $item->itemlost ) {
 844         return ( $biblionumber, 'not available', 'Item lost', $location );
 845     } elsif ( $item->withdrawn ) {
 846         return ( $biblionumber, 'not available', 'Item withdrawn', $location );
 847     } elsif ( $item->damaged ) {
 848         return ( $biblionumber, 'not available', 'Item damaged', $location );
 849     } else {
 850         return ( $biblionumber, 'available', undef, $location );
 851     }
 852 }
 853
 854 1;