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 = GetItem( $itemnumber );
 539     return { code => 'RecordNotFound' } unless $$item{itemnumber};
 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, $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 = GetItem( $itemnumber );
 611     return { code => 'RecordNotFound' } unless $$item{itemnumber};
 612
 613     # Add renewal if possible
 614     my @renewal = CanBookBeRenewed( $borrowernumber, $itemnumber );
 615     if ( $renewal[0] ) { AddRenewal( $borrowernumber, $itemnumber ); }
 616
 617     my $issue = Koha::Checkouts->find( { itemnumber => $itemnumber } ) or return; # FIXME should be handled
 618
 619     # Hashref building
 620     my $out;
 621     $out->{'renewals'} = $issue->renewals;
 622     $out->{date_due}   = dt_from_string($issue->date_due)->strftime('%Y-%m-%d %H:%S');
 623     $out->{'success'}  = $renewal[0];
 624     $out->{'error'}    = $renewal[1];
 625
 626     return $out;
 627 }
 628
 629 =head2 HoldTitle
 630
 631 Creates, for a borrower, a biblio-level hold reserve.
 632
 633 Parameters:
 634
 635   - patron_id (Required)
 636     a borrowernumber
 637   - bib_id (Required)
 638     a biblionumber
 639   - request_location (Required)
 640     IP address where the end user request is being placed
 641   - pickup_location (Optional)
 642     a branch code indicating the location to which to deliver the item for pickup
 643   - needed_before_date (Optional)
 644     date after which hold request is no longer needed
 645   - pickup_expiry_date (Optional)
 646     date after which item returned to shelf if item is not picked up
 647
 648 =cut
 649
 650 sub HoldTitle {
 651     my ($cgi) = @_;
 652
 653     # Get the borrower or return an error code
 654     my $borrowernumber = $cgi->param('patron_id');
 655     my $patron = Koha::Patrons->find( $borrowernumber );
 656     return { code => 'PatronNotFound' } unless $patron;
 657
 658     # Get the biblio record, or return an error code
 659     my $biblionumber = $cgi->param('bib_id');
 660     my $biblio = Koha::Biblios->find( $biblionumber );
 661     return { code => 'RecordNotFound' } unless $biblio;
 662
 663     my $title = $biblio ? $biblio->title : '';
 664
 665     # Check if the biblio can be reserved
 666     return { code => 'NotHoldable' } unless CanBookBeReserved( $borrowernumber, $biblionumber )->{status} eq 'OK';
 667
 668     my $branch;
 669
 670     # Pickup branch management
 671     if ( $cgi->param('pickup_location') ) {
 672         $branch = $cgi->param('pickup_location');
 673         return { code => 'LocationNotFound' } unless Koha::Libraries->find($branch);
 674     } else { # if the request provide no branch, use the borrower's branch
 675         $branch = $patron->branchcode;
 676     }
 677
 678     # Add the reserve
 679     #    $branch,    $borrowernumber, $biblionumber,
 680     #    $constraint, $bibitems,  $priority, $resdate, $expdate, $notes,
 681     #    $title,      $checkitem, $found
 682     my $priority= C4::Reserves::CalculatePriority( $biblionumber );
 683     AddReserve( $branch, $borrowernumber, $biblionumber, undef, $priority, undef, undef, undef, $title, undef, undef );
 684
 685     # Hashref building
 686     my $out;
 687     $out->{'title'}           = $title;
 688     my $library = Koha::Libraries->find( $branch );
 689     $out->{'pickup_location'} = $library ? $library->branchname : '';
 690
 691     # TODO $out->{'date_available'}  = '';
 692
 693     return $out;
 694 }
 695
 696 =head2 HoldItem
 697
 698 Creates, for a borrower, an item-level hold request on a specific item of
 699 a bibliographic record in Koha.
 700
 701 Parameters:
 702
 703   - patron_id (Required)
 704     a borrowernumber
 705   - bib_id (Required)
 706     a biblionumber
 707   - item_id (Required)
 708     an itemnumber
 709   - pickup_location (Optional)
 710     a branch code indicating the location to which to deliver the item for pickup
 711   - needed_before_date (Optional)
 712     date after which hold request is no longer needed
 713   - pickup_expiry_date (Optional)
 714     date after which item returned to shelf if item is not picked up
 715
 716 =cut
 717
 718 sub HoldItem {
 719     my ($cgi) = @_;
 720
 721     # Get the borrower or return an error code
 722     my $borrowernumber = $cgi->param('patron_id');
 723     my $patron = Koha::Patrons->find( $borrowernumber );
 724     return { code => 'PatronNotFound' } unless $patron;
 725
 726     # Get the biblio or return an error code
 727     my $biblionumber = $cgi->param('bib_id');
 728     my $biblio = Koha::Biblios->find( $biblionumber );
 729     return { code => 'RecordNotFound' } unless $biblio;
 730
 731     my $title = $biblio ? $biblio->title : '';
 732
 733     # Get the item or return an error code
 734     my $itemnumber = $cgi->param('item_id');
 735     my $item = GetItem( $itemnumber );
 736     return { code => 'RecordNotFound' } unless $$item{itemnumber};
 737
 738     # If the biblio does not match the item, return an error code
 739     return { code => 'RecordNotFound' } if $$item{biblionumber} ne $biblio->biblionumber;
 740
 741     # Check for item disponibility
 742     my $canitembereserved = C4::Reserves::CanItemBeReserved( $borrowernumber, $itemnumber );
 743     my $canbookbereserved = C4::Reserves::CanBookBeReserved( $borrowernumber, $biblionumber );
 744     return { code => 'NotHoldable' } unless $canbookbereserved->{status} eq 'OK' and $canitembereserved->{status} eq 'OK';
 745
 746     # Pickup branch management
 747     my $branch;
 748     if ( $cgi->param('pickup_location') ) {
 749         $branch = $cgi->param('pickup_location');
 750         return { code => 'LocationNotFound' } unless Koha::Libraries->find($branch);
 751     } else { # if the request provide no branch, use the borrower's branch
 752         $branch = $patron->branchcode;
 753     }
 754
 755     # Add the reserve
 756     #    $branch,    $borrowernumber, $biblionumber,
 757     #    $constraint, $bibitems,  $priority, $resdate, $expdate, $notes,
 758     #    $title,      $checkitem, $found
 759     my $priority= C4::Reserves::CalculatePriority( $biblionumber );
 760     AddReserve( $branch, $borrowernumber, $biblionumber, undef, $priority, undef, undef, undef, $title, $itemnumber, undef );
 761
 762     # Hashref building
 763     my $out;
 764     my $library = Koha::Libraries->find( $branch );
 765     $out->{'pickup_location'} = $library ? $library->branchname : '';
 766
 767     # TODO $out->{'date_available'} = '';
 768
 769     return $out;
 770 }
 771
 772 =head2 CancelHold
 773
 774 Cancels an active reserve request for the borrower.
 775
 776 Parameters:
 777
 778   - patron_id (Required)
 779         a borrowernumber
 780   - item_id (Required)
 781         a reserve_id
 782
 783 =cut
 784
 785 sub CancelHold {
 786     my ($cgi) = @_;
 787
 788     # Get the borrower or return an error code
 789     my $borrowernumber = $cgi->param('patron_id');
 790     my $patron = Koha::Patrons->find( $borrowernumber );
 791     return { code => 'PatronNotFound' } unless $patron;
 792
 793     # Get the reserve or return an error code
 794     my $reserve_id = $cgi->param('item_id');
 795     my $hold = Koha::Holds->find( $reserve_id );
 796     return { code => 'RecordNotFound' } unless $hold;
 797     return { code => 'RecordNotFound' } unless ($hold->borrowernumber == $borrowernumber);
 798
 799     $hold->cancel;
 800
 801     return { code => 'Canceled' };
 802 }
 803
 804 =head2 _availability
 805
 806 Returns, for an itemnumber, an array containing availability information.
 807
 808  my ($biblionumber, $status, $msg, $location) = _availability($id);
 809
 810 =cut
 811
 812 sub _availability {
 813     my ($itemnumber) = @_;
 814     my $item = GetItem( $itemnumber, undef, undef );
 815
 816     if ( not $item->{'itemnumber'} ) {
 817         return ( undef, 'unknown', 'Error: could not retrieve availability for this ID', undef );
 818     }
 819
 820     my $biblionumber = $item->{'biblioitemnumber'};
 821     my $library = Koha::Libraries->find( $item->{holdingbranch} );
 822     my $location = $library ? $library->branchname : '';
 823
 824     if ( $item->{'notforloan'} ) {
 825         return ( $biblionumber, 'not available', 'Not for loan', $location );
 826     } elsif ( $item->{'onloan'} ) {
 827         return ( $biblionumber, 'not available', 'Checked out', $location );
 828     } elsif ( $item->{'itemlost'} ) {
 829         return ( $biblionumber, 'not available', 'Item lost', $location );
 830     } elsif ( $item->{'withdrawn'} ) {
 831         return ( $biblionumber, 'not available', 'Item withdrawn', $location );
 832     } elsif ( $item->{'damaged'} ) {
 833         return ( $biblionumber, 'not available', 'Item damaged', $location );
 834     } else {
 835         return ( $biblionumber, 'available', undef, $location );
 836     }
 837 }
 838
 839 1;