Koha/REST/V1/Patrons.pm

   1 package Koha::REST::V1::Patrons;
   2
   3 # This file is part of Koha.
   4 #
   5 # Koha is free software; you can redistribute it and/or modify it under the
   6 # terms of the GNU General Public License as published by the Free Software
   7 # Foundation; either version 3 of the License, or (at your option) any later
   8 # version.
   9 #
  10 # Koha is distributed in the hope that it will be useful, but WITHOUT ANY
  11 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  12 # A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  13 #
  14 # You should have received a copy of the GNU General Public License along
  15 # with Koha; if not, write to the Free Software Foundation, Inc.,
  16 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  17
  18 use Modern::Perl;
  19
  20 use Mojo::Base 'Mojolicious::Controller';
  21
  22 use Koha::DateUtils;
  23 use Koha::Patrons;
  24
  25 use Scalar::Util qw(blessed);
  26 use Try::Tiny;
  27
  28 =head1 NAME
  29
  30 Koha::REST::V1::Patrons
  31
  32 =head1 API
  33
  34 =head2 Methods
  35
  36 =head3 list
  37
  38 Controller function that handles listing Koha::Patron objects
  39
  40 =cut
  41
  42 sub list {
  43     my $c = shift->openapi->valid_input or return;
  44
  45     return try {
  46         my $attributes = {};
  47         my $args = $c->validation->output;
  48         my ( $params, $reserved_params ) = $c->extract_reserved_params( $args );
  49
  50         # Merge sorting into query attributes
  51         $c->dbic_merge_sorting({ attributes => $attributes, params => $reserved_params });
  52
  53         # Merge pagination into query attributes
  54         $c->dbic_merge_pagination({ filter => $attributes, params => $reserved_params });
  55
  56         my $restricted = $args->{restricted};
  57
  58         $params = _to_model($params)
  59             if defined $params;
  60         # deal with string params
  61         $params = $c->build_query_params( $params, $reserved_params );
  62
  63         # translate 'restricted' => 'debarred'
  64         $params->{debarred} = { '!=' => undef }
  65           if $restricted;
  66
  67         my $patrons = Koha::Patrons->search( $params, $attributes );
  68         if ( $patrons->is_paged ) {
  69             $c->add_pagination_headers(
  70                 {
  71                     total  => $patrons->pager->total_entries,
  72                     params => $args,
  73                 }
  74             );
  75         }
  76
  77         return $c->render( status => 200, openapi => $patrons->to_api );
  78     }
  79     catch {
  80         if ( $_->isa('DBIx::Class::Exception') ) {
  81             return $c->render(
  82                 status  => 500,
  83                 openapi => { error => $_->{msg} }
  84             );
  85         }
  86         else {
  87             return $c->render(
  88                 status  => 500,
  89                 openapi => { error => "Something went wrong, check the logs." }
  90             );
  91         }
  92     };
  93 }
  94
  95
  96 =head3 get
  97
  98 Controller function that handles retrieving a single Koha::Patron object
  99
 100 =cut
 101
 102 sub get {
 103     my $c = shift->openapi->valid_input or return;
 104
 105     my $patron_id = $c->validation->param('patron_id');
 106     my $patron    = Koha::Patrons->find($patron_id);
 107
 108     unless ($patron) {
 109         return $c->render( status => 404, openapi => { error => "Patron not found." } );
 110     }
 111
 112     return $c->render( status => 200, openapi => $patron->to_api );
 113 }
 114
 115 =head3 add
 116
 117 Controller function that handles adding a new Koha::Patron object
 118
 119 =cut
 120
 121 sub add {
 122     my $c = shift->openapi->valid_input or return;
 123
 124     return try {
 125
 126         my $body = _to_model( $c->validation->param('body') );
 127
 128         my $patron = Koha::Patron->new( _to_model($body) )->store;
 129
 130         $c->res->headers->location( $c->req->url->to_string . '/' . $patron->borrowernumber );
 131         return $c->render(
 132             status  => 201,
 133             openapi => $patron->to_api
 134         );
 135     }
 136     catch {
 137         unless ( blessed $_ && $_->can('rethrow') ) {
 138             return $c->render(
 139                 status  => 500,
 140                 openapi => { error => "Something went wrong, check Koha logs for details." }
 141             );
 142         }
 143         if ( $_->isa('Koha::Exceptions::Object::DuplicateID') ) {
 144             return $c->render(
 145                 status  => 409,
 146                 openapi => { error => $_->error, conflict => $_->duplicate_id }
 147             );
 148         }
 149         elsif ( $_->isa('Koha::Exceptions::Object::FKConstraint') ) {
 150             return $c->render(
 151                 status  => 400,
 152                 openapi => {
 153                           error => "Given "
 154                         . $Koha::REST::V1::Patrons::to_api_mapping->{ $_->broken_fk }
 155                         . " does not exist"
 156                 }
 157             );
 158         }
 159         elsif ( $_->isa('Koha::Exceptions::BadParameter') ) {
 160             return $c->render(
 161                 status  => 400,
 162                 openapi => {
 163                           error => "Given "
 164                         . $Koha::REST::V1::Patrons::to_api_mapping->{ $_->parameter }
 165                         . " does not exist"
 166                 }
 167             );
 168         }
 169         else {
 170             return $c->render(
 171                 status  => 500,
 172                 openapi => { error => "Something went wrong, check Koha logs for details." }
 173             );
 174         }
 175     };
 176 }
 177
 178
 179 =head3 update
 180
 181 Controller function that handles updating a Koha::Patron object
 182
 183 =cut
 184
 185 sub update {
 186     my $c = shift->openapi->valid_input or return;
 187
 188     my $patron_id = $c->validation->param('patron_id');
 189     my $patron    = Koha::Patrons->find( $patron_id );
 190
 191     unless ($patron) {
 192          return $c->render(
 193              status  => 404,
 194              openapi => { error => "Patron not found" }
 195          );
 196      }
 197
 198     return try {
 199         my $body = _to_model($c->validation->param('body'));
 200
 201         $patron->set($body)->store;
 202         $patron->discard_changes;
 203         return $c->render( status => 200, openapi => $patron );
 204     }
 205     catch {
 206         unless ( blessed $_ && $_->can('rethrow') ) {
 207             return $c->render(
 208                 status  => 500,
 209                 openapi => {
 210                     error => "Something went wrong, check Koha logs for details."
 211                 }
 212             );
 213         }
 214         if ( $_->isa('Koha::Exceptions::Object::DuplicateID') ) {
 215             return $c->render(
 216                 status  => 409,
 217                 openapi => { error => $_->error, conflict => $_->duplicate_id }
 218             );
 219         }
 220         elsif ( $_->isa('Koha::Exceptions::Object::FKConstraint') ) {
 221             return $c->render(
 222                 status  => 400,
 223                 openapi => { error => "Given " .
 224                             $Koha::REST::V1::Patrons::to_api_mapping->{$_->broken_fk}
 225                             . " does not exist" }
 226             );
 227         }
 228         elsif ( $_->isa('Koha::Exceptions::MissingParameter') ) {
 229             return $c->render(
 230                 status  => 400,
 231                 openapi => {
 232                     error      => "Missing mandatory parameter(s)",
 233                     parameters => $_->parameter
 234                 }
 235             );
 236         }
 237         elsif ( $_->isa('Koha::Exceptions::BadParameter') ) {
 238             return $c->render(
 239                 status  => 400,
 240                 openapi => {
 241                     error      => "Invalid parameter(s)",
 242                     parameters => $_->parameter
 243                 }
 244             );
 245         }
 246         elsif ( $_->isa('Koha::Exceptions::NoChanges') ) {
 247             return $c->render(
 248                 status  => 204,
 249                 openapi => { error => "No changes have been made" }
 250             );
 251         }
 252         else {
 253             return $c->render(
 254                 status  => 500,
 255                 openapi => {
 256                     error =>
 257                       "Something went wrong, check Koha logs for details."
 258                 }
 259             );
 260         }
 261     };
 262 }
 263
 264 =head3 delete
 265
 266 Controller function that handles deleting a Koha::Patron object
 267
 268 =cut
 269
 270 sub delete {
 271     my $c = shift->openapi->valid_input or return;
 272
 273     my $patron;
 274
 275     return try {
 276         $patron = Koha::Patrons->find( $c->validation->param('patron_id') );
 277
 278         # check if loans, reservations, debarrment, etc. before deletion!
 279         $patron->delete;
 280         return $c->render( status => 200, openapi => {} );
 281     }
 282     catch {
 283         unless ($patron) {
 284             return $c->render(
 285                 status  => 404,
 286                 openapi => { error => "Patron not found" }
 287             );
 288         }
 289         else {
 290             return $c->render(
 291                 status  => 500,
 292                 openapi => {
 293                     error =>
 294                       "Something went wrong, check Koha logs for details."
 295                 }
 296             );
 297         }
 298     };
 299 }
 300
 301 =head3 guarantors_can_see_charges
 302
 303 Method for setting whether guarantors can see the patron's charges.
 304
 305 =cut
 306
 307 sub guarantors_can_see_charges {
 308     my $c = shift->openapi->valid_input or return;
 309
 310     return try {
 311         if ( C4::Context->preference('AllowPatronToSetFinesVisibilityForGuarantor') ) {
 312             my $patron = $c->stash( 'koha.user' );
 313             my $privacy_setting = ($c->req->json->{allowed}) ? 1 : 0;
 314
 315             $patron->privacy_guarantor_fines( $privacy_setting )->store;
 316
 317             return $c->render(
 318                 status  => 200,
 319                 openapi => {}
 320             );
 321         }
 322         else {
 323             return $c->render(
 324                 status  => 403,
 325                 openapi => {
 326                     error =>
 327                       'The current configuration doesn\'t allow the requested action.'
 328                 }
 329             );
 330         }
 331     }
 332     catch {
 333         return $c->render(
 334             status  => 500,
 335             openapi => {
 336                 error =>
 337                   "Something went wrong, check Koha logs for details. $_"
 338             }
 339         );
 340     };
 341 }
 342
 343 =head3 guarantors_can_see_checkouts
 344
 345 Method for setting whether guarantors can see the patron's checkouts.
 346
 347 =cut
 348
 349 sub guarantors_can_see_checkouts {
 350     my $c = shift->openapi->valid_input or return;
 351
 352     return try {
 353         if ( C4::Context->preference('AllowPatronToSetCheckoutsVisibilityForGuarantor') ) {
 354             my $patron = $c->stash( 'koha.user' );
 355             my $privacy_setting = ( $c->req->json->{allowed} ) ? 1 : 0;
 356
 357             $patron->privacy_guarantor_checkouts( $privacy_setting )->store;
 358
 359             return $c->render(
 360                 status  => 200,
 361                 openapi => {}
 362             );
 363         }
 364         else {
 365             return $c->render(
 366                 status  => 403,
 367                 openapi => {
 368                     error =>
 369                       'The current configuration doesn\'t allow the requested action.'
 370                 }
 371             );
 372         }
 373     }
 374     catch {
 375         return $c->render(
 376             status  => 500,
 377             openapi => {
 378                 error =>
 379                   "Something went wrong, check Koha logs for details. $_"
 380             }
 381         );
 382     };
 383 }
 384
 385 =head2 Internal methods
 386
 387 =head3 _to_api
 388
 389 Helper function that maps unblessed Koha::Patron objects into REST api
 390 attribute names.
 391
 392 =cut
 393
 394 sub _to_api {
 395     my $patron    = shift;
 396     my $patron_id = $patron->{ borrowernumber };
 397
 398     # Rename attributes
 399     foreach my $column ( keys %{ $Koha::REST::V1::Patrons::to_api_mapping } ) {
 400         my $mapped_column = $Koha::REST::V1::Patrons::to_api_mapping->{$column};
 401         if (    exists $patron->{ $column }
 402              && defined $mapped_column )
 403         {
 404             # key != undef
 405             $patron->{ $mapped_column } = delete $patron->{ $column };
 406         }
 407         elsif (    exists $patron->{ $column }
 408                 && !defined $mapped_column )
 409         {
 410             # key == undef
 411             delete $patron->{ $column };
 412         }
 413     }
 414
 415     # Calculate the 'restricted' field
 416     my $patron_obj = Koha::Patrons->find( $patron_id );
 417     $patron->{ restricted } = ($patron_obj->is_debarred) ? Mojo::JSON->true : Mojo::JSON->false;
 418
 419     return $patron;
 420 }
 421
 422 =head3 _to_model
 423
 424 Helper function that maps REST api objects into Koha::Patron
 425 attribute names.
 426
 427 =cut
 428
 429 sub _to_model {
 430     my $patron = shift;
 431
 432     foreach my $attribute ( keys %{ $Koha::REST::V1::Patrons::to_model_mapping } ) {
 433         my $mapped_attribute = $Koha::REST::V1::Patrons::to_model_mapping->{$attribute};
 434         if (    exists $patron->{ $attribute }
 435              && defined $mapped_attribute )
 436         {
 437             # key => !undef
 438             $patron->{ $mapped_attribute } = delete $patron->{ $attribute };
 439         }
 440         elsif (    exists $patron->{ $attribute }
 441                 && !defined $mapped_attribute )
 442         {
 443             # key => undef / to be deleted
 444             delete $patron->{ $attribute };
 445         }
 446     }
 447
 448     # TODO: Get rid of this once write operations are based on Koha::Patron
 449     if ( exists $patron->{lost} ) {
 450         $patron->{lost} = ($patron->{lost}) ? 1 : 0;
 451     }
 452
 453     if ( exists $patron->{ gonenoaddress} ) {
 454         $patron->{gonenoaddress} = ($patron->{gonenoaddress}) ? 1 : 0;
 455     }
 456
 457     if ( exists $patron->{lastseen} ) {
 458         $patron->{lastseen} = output_pref({ str => $patron->{lastseen}, dateformat => 'sql' });
 459     }
 460
 461     if ( exists $patron->{updated_on} ) {
 462         $patron->{updated_on} = output_pref({ str => $patron->{updated_on}, dateformat => 'sql' });
 463     }
 464
 465     return $patron;
 466 }
 467
 468 =head2 Global variables
 469
 470 =head3 $to_api_mapping
 471
 472 =cut
 473
 474 our $to_api_mapping = {
 475     borrowernotes       => 'staff_notes',
 476     borrowernumber      => 'patron_id',
 477     branchcode          => 'library_id',
 478     categorycode        => 'category_id',
 479     checkprevcheckout   => 'check_previous_checkout',
 480     contactfirstname    => undef, # Unused
 481     contactname         => undef, # Unused
 482     contactnote         => 'altaddress_notes',
 483     contacttitle        => undef, # Unused
 484     dateenrolled        => 'date_enrolled',
 485     dateexpiry          => 'expiry_date',
 486     dateofbirth         => 'date_of_birth',
 487     debarred            => undef, # replaced by 'restricted'
 488     debarredcomment     => undef, # calculated, API consumers will use /restrictions instead
 489     emailpro            => 'secondary_email',
 490     flags               => undef, # permissions manipulation handled in /permissions
 491     gonenoaddress       => 'incorrect_address',
 492     guarantorid         => 'guarantor_id',
 493     lastseen            => 'last_seen',
 494     lost                => 'patron_card_lost',
 495     opacnote            => 'opac_notes',
 496     othernames          => 'other_name',
 497     password            => undef, # password manipulation handled in /password
 498     phonepro            => 'secondary_phone',
 499     relationship        => 'relationship_type',
 500     sex                 => 'gender',
 501     smsalertnumber      => 'sms_number',
 502     sort1               => 'statistics_1',
 503     sort2               => 'statistics_2',
 504     streetnumber        => 'street_number',
 505     streettype          => 'street_type',
 506     zipcode             => 'postal_code',
 507     B_address           => 'altaddress_address',
 508     B_address2          => 'altaddress_address2',
 509     B_city              => 'altaddress_city',
 510     B_country           => 'altaddress_country',
 511     B_email             => 'altaddress_email',
 512     B_phone             => 'altaddress_phone',
 513     B_state             => 'altaddress_state',
 514     B_streetnumber      => 'altaddress_street_number',
 515     B_streettype        => 'altaddress_street_type',
 516     B_zipcode           => 'altaddress_postal_code',
 517     altcontactaddress1  => 'altcontact_address',
 518     altcontactaddress2  => 'altcontact_address2',
 519     altcontactaddress3  => 'altcontact_city',
 520     altcontactcountry   => 'altcontact_country',
 521     altcontactfirstname => 'altcontact_firstname',
 522     altcontactphone     => 'altcontact_phone',
 523     altcontactsurname   => 'altcontact_surname',
 524     altcontactstate     => 'altcontact_state',
 525     altcontactzipcode   => 'altcontact_postal_code'
 526 };
 527
 528 =head3 $to_model_mapping
 529
 530 =cut
 531
 532 our $to_model_mapping = {
 533     altaddress_notes         => 'contactnote',
 534     category_id              => 'categorycode',
 535     check_previous_checkout  => 'checkprevcheckout',
 536     date_enrolled            => 'dateenrolled',
 537     date_of_birth            => 'dateofbirth',
 538     expiry_date              => 'dateexpiry',
 539     gender                   => 'sex',
 540     guarantor_id             => 'guarantorid',
 541     incorrect_address        => 'gonenoaddress',
 542     last_seen                => 'lastseen',
 543     library_id               => 'branchcode',
 544     opac_notes               => 'opacnote',
 545     other_name               => 'othernames',
 546     patron_card_lost         => 'lost',
 547     patron_id                => 'borrowernumber',
 548     postal_code              => 'zipcode',
 549     relationship_type        => 'relationship',
 550     restricted               => undef,
 551     secondary_email          => 'emailpro',
 552     secondary_phone          => 'phonepro',
 553     sms_number               => 'smsalertnumber',
 554     staff_notes              => 'borrowernotes',
 555     statistics_1             => 'sort1',
 556     statistics_2             => 'sort2',
 557     street_number            => 'streetnumber',
 558     street_type              => 'streettype',
 559     altaddress_address       => 'B_address',
 560     altaddress_address2      => 'B_address2',
 561     altaddress_city          => 'B_city',
 562     altaddress_country       => 'B_country',
 563     altaddress_email         => 'B_email',
 564     altaddress_phone         => 'B_phone',
 565     altaddress_state         => 'B_state',
 566     altaddress_street_number => 'B_streetnumber',
 567     altaddress_street_type   => 'B_streettype',
 568     altaddress_postal_code   => 'B_zipcode',
 569     altcontact_firstname     => 'altcontactfirstname',
 570     altcontact_surname       => 'altcontactsurname',
 571     altcontact_address       => 'altcontactaddress1',
 572     altcontact_address2      => 'altcontactaddress2',
 573     altcontact_city          => 'altcontactaddress3',
 574     altcontact_state         => 'altcontactstate',
 575     altcontact_postal_code   => 'altcontactzipcode',
 576     altcontact_country       => 'altcontactcountry',
 577     altcontact_phone         => 'altcontactphone'
 578 };
 579
 580 1;