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         return $c->render( status => 201, openapi => $patron->to_api );
 131     }
 132     catch {
 133         unless ( blessed $_ && $_->can('rethrow') ) {
 134             return $c->render(
 135                 status  => 500,
 136                 openapi => { error => "Something went wrong, check Koha logs for details." }
 137             );
 138         }
 139         if ( $_->isa('Koha::Exceptions::Object::DuplicateID') ) {
 140             return $c->render(
 141                 status  => 409,
 142                 openapi => { error => $_->error, conflict => $_->duplicate_id }
 143             );
 144         }
 145         elsif ( $_->isa('Koha::Exceptions::Object::FKConstraint') ) {
 146             return $c->render(
 147                 status  => 400,
 148                 openapi => {
 149                           error => "Given "
 150                         . $Koha::REST::V1::Patrons::to_api_mapping->{ $_->broken_fk }
 151                         . " does not exist"
 152                 }
 153             );
 154         }
 155         elsif ( $_->isa('Koha::Exceptions::BadParameter') ) {
 156             return $c->render(
 157                 status  => 400,
 158                 openapi => {
 159                           error => "Given "
 160                         . $Koha::REST::V1::Patrons::to_api_mapping->{ $_->parameter }
 161                         . " does not exist"
 162                 }
 163             );
 164         }
 165         else {
 166             return $c->render(
 167                 status  => 500,
 168                 openapi => { error => "Something went wrong, check Koha logs for details." }
 169             );
 170         }
 171     };
 172 }
 173
 174
 175 =head3 update
 176
 177 Controller function that handles updating a Koha::Patron object
 178
 179 =cut
 180
 181 sub update {
 182     my $c = shift->openapi->valid_input or return;
 183
 184     my $patron_id = $c->validation->param('patron_id');
 185     my $patron    = Koha::Patrons->find( $patron_id );
 186
 187     unless ($patron) {
 188          return $c->render(
 189              status  => 404,
 190              openapi => { error => "Patron not found" }
 191          );
 192      }
 193
 194     return try {
 195         my $body = _to_model($c->validation->param('body'));
 196
 197         $patron->set($body)->store;
 198         $patron->discard_changes;
 199         return $c->render( status => 200, openapi => $patron );
 200     }
 201     catch {
 202         unless ( blessed $_ && $_->can('rethrow') ) {
 203             return $c->render(
 204                 status  => 500,
 205                 openapi => {
 206                     error => "Something went wrong, check Koha logs for details."
 207                 }
 208             );
 209         }
 210         if ( $_->isa('Koha::Exceptions::Object::DuplicateID') ) {
 211             return $c->render(
 212                 status  => 409,
 213                 openapi => { error => $_->error, conflict => $_->duplicate_id }
 214             );
 215         }
 216         elsif ( $_->isa('Koha::Exceptions::Object::FKConstraint') ) {
 217             return $c->render(
 218                 status  => 400,
 219                 openapi => { error => "Given " .
 220                             $Koha::REST::V1::Patrons::to_api_mapping->{$_->broken_fk}
 221                             . " does not exist" }
 222             );
 223         }
 224         elsif ( $_->isa('Koha::Exceptions::MissingParameter') ) {
 225             return $c->render(
 226                 status  => 400,
 227                 openapi => {
 228                     error      => "Missing mandatory parameter(s)",
 229                     parameters => $_->parameter
 230                 }
 231             );
 232         }
 233         elsif ( $_->isa('Koha::Exceptions::BadParameter') ) {
 234             return $c->render(
 235                 status  => 400,
 236                 openapi => {
 237                     error      => "Invalid parameter(s)",
 238                     parameters => $_->parameter
 239                 }
 240             );
 241         }
 242         elsif ( $_->isa('Koha::Exceptions::NoChanges') ) {
 243             return $c->render(
 244                 status  => 204,
 245                 openapi => { error => "No changes have been made" }
 246             );
 247         }
 248         else {
 249             return $c->render(
 250                 status  => 500,
 251                 openapi => {
 252                     error =>
 253                       "Something went wrong, check Koha logs for details."
 254                 }
 255             );
 256         }
 257     };
 258 }
 259
 260 =head3 delete
 261
 262 Controller function that handles deleting a Koha::Patron object
 263
 264 =cut
 265
 266 sub delete {
 267     my $c = shift->openapi->valid_input or return;
 268
 269     my $patron;
 270
 271     return try {
 272         $patron = Koha::Patrons->find( $c->validation->param('patron_id') );
 273
 274         # check if loans, reservations, debarrment, etc. before deletion!
 275         my $res = $patron->delete;
 276         return $c->render( status => 200, openapi => {} );
 277     }
 278     catch {
 279         unless ($patron) {
 280             return $c->render(
 281                 status  => 404,
 282                 openapi => { error => "Patron not found" }
 283             );
 284         }
 285         else {
 286             return $c->render(
 287                 status  => 500,
 288                 openapi => {
 289                     error =>
 290                       "Something went wrong, check Koha logs for details."
 291                 }
 292             );
 293         }
 294     };
 295 }
 296
 297 =head3 guarantors_can_see_charges
 298
 299 Method for setting whether guarantors can see the patron's charges.
 300
 301 =cut
 302
 303 sub guarantors_can_see_charges {
 304     my $c = shift->openapi->valid_input or return;
 305
 306     return try {
 307         if ( C4::Context->preference('AllowPatronToSetFinesVisibilityForGuarantor') ) {
 308             my $patron = $c->stash( 'koha.user' );
 309             my $privacy_setting = ($c->req->json->{allowed}) ? 1 : 0;
 310
 311             $patron->privacy_guarantor_fines( $privacy_setting )->store;
 312
 313             return $c->render(
 314                 status  => 200,
 315                 openapi => {}
 316             );
 317         }
 318         else {
 319             return $c->render(
 320                 status  => 403,
 321                 openapi => {
 322                     error =>
 323                       'The current configuration doesn\'t allow the requested action.'
 324                 }
 325             );
 326         }
 327     }
 328     catch {
 329         return $c->render(
 330             status  => 500,
 331             openapi => {
 332                 error =>
 333                   "Something went wrong, check Koha logs for details. $_"
 334             }
 335         );
 336     };
 337 }
 338
 339 =head3 guarantors_can_see_checkouts
 340
 341 Method for setting whether guarantors can see the patron's checkouts.
 342
 343 =cut
 344
 345 sub guarantors_can_see_checkouts {
 346     my $c = shift->openapi->valid_input or return;
 347
 348     return try {
 349         if ( C4::Context->preference('AllowPatronToSetCheckoutsVisibilityForGuarantor') ) {
 350             my $patron = $c->stash( 'koha.user' );
 351             my $privacy_setting = ( $c->req->json->{allowed} ) ? 1 : 0;
 352
 353             $patron->privacy_guarantor_checkouts( $privacy_setting )->store;
 354
 355             return $c->render(
 356                 status  => 200,
 357                 openapi => {}
 358             );
 359         }
 360         else {
 361             return $c->render(
 362                 status  => 403,
 363                 openapi => {
 364                     error =>
 365                       'The current configuration doesn\'t allow the requested action.'
 366                 }
 367             );
 368         }
 369     }
 370     catch {
 371         return $c->render(
 372             status  => 500,
 373             openapi => {
 374                 error =>
 375                   "Something went wrong, check Koha logs for details. $_"
 376             }
 377         );
 378     };
 379 }
 380
 381 =head2 Internal methods
 382
 383 =head3 _to_api
 384
 385 Helper function that maps unblessed Koha::Patron objects into REST api
 386 attribute names.
 387
 388 =cut
 389
 390 sub _to_api {
 391     my $patron    = shift;
 392     my $patron_id = $patron->{ borrowernumber };
 393
 394     # Rename attributes
 395     foreach my $column ( keys %{ $Koha::REST::V1::Patrons::to_api_mapping } ) {
 396         my $mapped_column = $Koha::REST::V1::Patrons::to_api_mapping->{$column};
 397         if (    exists $patron->{ $column }
 398              && defined $mapped_column )
 399         {
 400             # key != undef
 401             $patron->{ $mapped_column } = delete $patron->{ $column };
 402         }
 403         elsif (    exists $patron->{ $column }
 404                 && !defined $mapped_column )
 405         {
 406             # key == undef
 407             delete $patron->{ $column };
 408         }
 409     }
 410
 411     # Calculate the 'restricted' field
 412     my $patron_obj = Koha::Patrons->find( $patron_id );
 413     $patron->{ restricted } = ($patron_obj->is_debarred) ? Mojo::JSON->true : Mojo::JSON->false;
 414
 415     return $patron;
 416 }
 417
 418 =head3 _to_model
 419
 420 Helper function that maps REST api objects into Koha::Patron
 421 attribute names.
 422
 423 =cut
 424
 425 sub _to_model {
 426     my $patron = shift;
 427
 428     foreach my $attribute ( keys %{ $Koha::REST::V1::Patrons::to_model_mapping } ) {
 429         my $mapped_attribute = $Koha::REST::V1::Patrons::to_model_mapping->{$attribute};
 430         if (    exists $patron->{ $attribute }
 431              && defined $mapped_attribute )
 432         {
 433             # key => !undef
 434             $patron->{ $mapped_attribute } = delete $patron->{ $attribute };
 435         }
 436         elsif (    exists $patron->{ $attribute }
 437                 && !defined $mapped_attribute )
 438         {
 439             # key => undef / to be deleted
 440             delete $patron->{ $attribute };
 441         }
 442     }
 443
 444     # TODO: Get rid of this once write operations are based on Koha::Patron
 445     if ( exists $patron->{lost} ) {
 446         $patron->{lost} = ($patron->{lost}) ? 1 : 0;
 447     }
 448
 449     if ( exists $patron->{ gonenoaddress} ) {
 450         $patron->{gonenoaddress} = ($patron->{gonenoaddress}) ? 1 : 0;
 451     }
 452
 453     if ( exists $patron->{lastseen} ) {
 454         $patron->{lastseen} = output_pref({ str => $patron->{lastseen}, dateformat => 'sql' });
 455     }
 456
 457     if ( exists $patron->{updated_on} ) {
 458         $patron->{updated_on} = output_pref({ str => $patron->{updated_on}, dateformat => 'sql' });
 459     }
 460
 461     return $patron;
 462 }
 463
 464 =head2 Global variables
 465
 466 =head3 $to_api_mapping
 467
 468 =cut
 469
 470 our $to_api_mapping = {
 471     borrowernotes       => 'staff_notes',
 472     borrowernumber      => 'patron_id',
 473     branchcode          => 'library_id',
 474     categorycode        => 'category_id',
 475     checkprevcheckout   => 'check_previous_checkout',
 476     contactfirstname    => undef, # Unused
 477     contactname         => undef, # Unused
 478     contactnote         => 'altaddress_notes',
 479     contacttitle        => undef, # Unused
 480     dateenrolled        => 'date_enrolled',
 481     dateexpiry          => 'expiry_date',
 482     dateofbirth         => 'date_of_birth',
 483     debarred            => undef, # replaced by 'restricted'
 484     debarredcomment     => undef, # calculated, API consumers will use /restrictions instead
 485     emailpro            => 'secondary_email',
 486     flags               => undef, # permissions manipulation handled in /permissions
 487     gonenoaddress       => 'incorrect_address',
 488     guarantorid         => 'guarantor_id',
 489     lastseen            => 'last_seen',
 490     lost                => 'patron_card_lost',
 491     opacnote            => 'opac_notes',
 492     othernames          => 'other_name',
 493     password            => undef, # password manipulation handled in /password
 494     phonepro            => 'secondary_phone',
 495     relationship        => 'relationship_type',
 496     sex                 => 'gender',
 497     smsalertnumber      => 'sms_number',
 498     sort1               => 'statistics_1',
 499     sort2               => 'statistics_2',
 500     streetnumber        => 'street_number',
 501     streettype          => 'street_type',
 502     zipcode             => 'postal_code',
 503     B_address           => 'altaddress_address',
 504     B_address2          => 'altaddress_address2',
 505     B_city              => 'altaddress_city',
 506     B_country           => 'altaddress_country',
 507     B_email             => 'altaddress_email',
 508     B_phone             => 'altaddress_phone',
 509     B_state             => 'altaddress_state',
 510     B_streetnumber      => 'altaddress_street_number',
 511     B_streettype        => 'altaddress_street_type',
 512     B_zipcode           => 'altaddress_postal_code',
 513     altcontactaddress1  => 'altcontact_address',
 514     altcontactaddress2  => 'altcontact_address2',
 515     altcontactaddress3  => 'altcontact_city',
 516     altcontactcountry   => 'altcontact_country',
 517     altcontactfirstname => 'altcontact_firstname',
 518     altcontactphone     => 'altcontact_phone',
 519     altcontactsurname   => 'altcontact_surname',
 520     altcontactstate     => 'altcontact_state',
 521     altcontactzipcode   => 'altcontact_postal_code'
 522 };
 523
 524 =head3 $to_model_mapping
 525
 526 =cut
 527
 528 our $to_model_mapping = {
 529     altaddress_notes         => 'contactnote',
 530     category_id              => 'categorycode',
 531     check_previous_checkout  => 'checkprevcheckout',
 532     date_enrolled            => 'dateenrolled',
 533     date_of_birth            => 'dateofbirth',
 534     expiry_date              => 'dateexpiry',
 535     gender                   => 'sex',
 536     guarantor_id             => 'guarantorid',
 537     incorrect_address        => 'gonenoaddress',
 538     last_seen                => 'lastseen',
 539     library_id               => 'branchcode',
 540     opac_notes               => 'opacnote',
 541     other_name               => 'othernames',
 542     patron_card_lost         => 'lost',
 543     patron_id                => 'borrowernumber',
 544     postal_code              => 'zipcode',
 545     relationship_type        => 'relationship',
 546     restricted               => undef,
 547     secondary_email          => 'emailpro',
 548     secondary_phone          => 'phonepro',
 549     sms_number               => 'smsalertnumber',
 550     staff_notes              => 'borrowernotes',
 551     statistics_1             => 'sort1',
 552     statistics_2             => 'sort2',
 553     street_number            => 'streetnumber',
 554     street_type              => 'streettype',
 555     altaddress_address       => 'B_address',
 556     altaddress_address2      => 'B_address2',
 557     altaddress_city          => 'B_city',
 558     altaddress_country       => 'B_country',
 559     altaddress_email         => 'B_email',
 560     altaddress_phone         => 'B_phone',
 561     altaddress_state         => 'B_state',
 562     altaddress_street_number => 'B_streetnumber',
 563     altaddress_street_type   => 'B_streettype',
 564     altaddress_postal_code   => 'B_zipcode',
 565     altcontact_firstname     => 'altcontactfirstname',
 566     altcontact_surname       => 'altcontactsurname',
 567     altcontact_address       => 'altcontactaddress1',
 568     altcontact_address2      => 'altcontactaddress2',
 569     altcontact_city          => 'altcontactaddress3',
 570     altcontact_state         => 'altcontactstate',
 571     altcontact_postal_code   => 'altcontactzipcode',
 572     altcontact_country       => 'altcontactcountry',
 573     altcontact_phone         => 'altcontactphone'
 574 };
 575
 576 1;