koha-dev.rot13.org Git - srvgit/blob - 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 C4::Members qw( ModMember );
  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         my @patrons = $patrons->as_list;
  77         @patrons = map { _to_api( $_->TO_JSON ) } @patrons;
  78         return $c->render( status => 200, openapi => \@patrons );
  79     }
  80     catch {
  81         if ( $_->isa('DBIx::Class::Exception') ) {
  82             return $c->render(
  83                 status  => 500,
  84                 openapi => { error => $_->{msg} }
  85             );
  86         }
  87         else {
  88             return $c->render(
  89                 status  => 500,
  90                 openapi => { error => "Something went wrong, check the logs." }
  91             );
  92         }
  93     };
  94 }
  95
  96
  97 =head3 get
  98
  99 Controller function that handles retrieving a single Koha::Patron object
 100
 101 =cut
 102
 103 sub get {
 104     my $c = shift->openapi->valid_input or return;
 105
 106     my $patron_id = $c->validation->param('patron_id');
 107     my $patron    = Koha::Patrons->find($patron_id);
 108
 109     unless ($patron) {
 110         return $c->render( status => 404, openapi => { error => "Patron not found." } );
 111     }
 112
 113     return $c->render( status => 200, openapi => _to_api( $patron->TO_JSON ) );
 114 }
 115
 116 =head3 add
 117
 118 Controller function that handles adding a new Koha::Patron object
 119
 120 =cut
 121
 122 sub add {
 123     my $c = shift->openapi->valid_input or return;
 124
 125     return try {
 126
 127         my $body = _to_model( $c->validation->param('body') );
 128
 129         my $patron = Koha::Patron->new( _to_model($body) )->store;
 130         $patron    = _to_api( $patron->TO_JSON );
 131
 132         return $c->render( status => 201, openapi => $patron );
 133     }
 134     catch {
 135         unless ( blessed $_ && $_->can('rethrow') ) {
 136             return $c->render(
 137                 status  => 500,
 138                 openapi => { error => "Something went wrong, check Koha logs for details." }
 139             );
 140         }
 141         if ( $_->isa('Koha::Exceptions::Object::DuplicateID') ) {
 142             return $c->render(
 143                 status  => 409,
 144                 openapi => { error => $_->error, conflict => $_->duplicate_id }
 145             );
 146         }
 147         elsif ( $_->isa('Koha::Exceptions::Object::FKConstraint') ) {
 148             return $c->render(
 149                 status  => 400,
 150                 openapi => {
 151                           error => "Given "
 152                         . $Koha::REST::V1::Patrons::to_api_mapping->{ $_->broken_fk }
 153                         . " does not exist"
 154                 }
 155             );
 156         }
 157         elsif ( $_->isa('Koha::Exceptions::BadParameter') ) {
 158             return $c->render(
 159                 status  => 400,
 160                 openapi => {
 161                           error => "Given "
 162                         . $Koha::REST::V1::Patrons::to_api_mapping->{ $_->parameter }
 163                         . " does not exist"
 164                 }
 165             );
 166         }
 167         else {
 168             return $c->render(
 169                 status  => 500,
 170                 openapi => { error => "Something went wrong, check Koha logs for details." }
 171             );
 172         }
 173     };
 174 }
 175
 176
 177 =head3 update
 178
 179 Controller function that handles updating a Koha::Patron object
 180
 181 =cut
 182
 183 sub update {
 184     my $c = shift->openapi->valid_input or return;
 185
 186     my $patron_id = $c->validation->param('patron_id');
 187     my $patron    = Koha::Patrons->find( $patron_id );
 188
 189     unless ($patron) {
 190          return $c->render(
 191              status  => 404,
 192              openapi => { error => "Patron not found" }
 193          );
 194      }
 195
 196     return try {
 197         my $body = _to_model($c->validation->param('body'));
 198
 199         ## TODO: Use ModMember until it has been moved to Koha-namespace
 200         # Add borrowernumber to $body, as required by ModMember
 201         $body->{borrowernumber} = $patron_id;
 202
 203         if ( ModMember(%$body) ) {
 204             # Fetch the updated Koha::Patron object
 205             $patron->discard_changes;
 206             return $c->render( status => 200, openapi => $patron );
 207         }
 208         else {
 209             return $c->render(
 210                 status  => 500,
 211                 openapi => {
 212                     error => 'Something went wrong, check Koha logs for details.'
 213                 }
 214             );
 215         }
 216     }
 217     catch {
 218         unless ( blessed $_ && $_->can('rethrow') ) {
 219             return $c->render(
 220                 status  => 500,
 221                 openapi => {
 222                     error => "Something went wrong, check Koha logs for details."
 223                 }
 224             );
 225         }
 226         if ( $_->isa('Koha::Exceptions::Object::DuplicateID') ) {
 227             return $c->render(
 228                 status  => 409,
 229                 openapi => { error => $_->error, conflict => $_->duplicate_id }
 230             );
 231         }
 232         elsif ( $_->isa('Koha::Exceptions::Object::FKConstraint') ) {
 233             return $c->render(
 234                 status  => 400,
 235                 openapi => { error => "Given " .
 236                             $Koha::REST::V1::Patrons::to_api_mapping->{$_->broken_fk}
 237                             . " does not exist" }
 238             );
 239         }
 240         elsif ( $_->isa('Koha::Exceptions::MissingParameter') ) {
 241             return $c->render(
 242                 status  => 400,
 243                 openapi => {
 244                     error      => "Missing mandatory parameter(s)",
 245                     parameters => $_->parameter
 246                 }
 247             );
 248         }
 249         elsif ( $_->isa('Koha::Exceptions::BadParameter') ) {
 250             return $c->render(
 251                 status  => 400,
 252                 openapi => {
 253                     error      => "Invalid parameter(s)",
 254                     parameters => $_->parameter
 255                 }
 256             );
 257         }
 258         elsif ( $_->isa('Koha::Exceptions::NoChanges') ) {
 259             return $c->render(
 260                 status  => 204,
 261                 openapi => { error => "No changes have been made" }
 262             );
 263         }
 264         else {
 265             return $c->render(
 266                 status  => 500,
 267                 openapi => {
 268                     error =>
 269                       "Something went wrong, check Koha logs for details."
 270                 }
 271             );
 272         }
 273     };
 274 }
 275
 276 =head3 delete
 277
 278 Controller function that handles deleting a Koha::Patron object
 279
 280 =cut
 281
 282 sub delete {
 283     my $c = shift->openapi->valid_input or return;
 284
 285     my $patron;
 286
 287     return try {
 288         $patron = Koha::Patrons->find( $c->validation->param('patron_id') );
 289
 290         # check if loans, reservations, debarrment, etc. before deletion!
 291         my $res = $patron->delete;
 292         return $c->render( status => 200, openapi => {} );
 293     }
 294     catch {
 295         unless ($patron) {
 296             return $c->render(
 297                 status  => 404,
 298                 openapi => { error => "Patron not found" }
 299             );
 300         }
 301         else {
 302             return $c->render(
 303                 status  => 500,
 304                 openapi => {
 305                     error =>
 306                       "Something went wrong, check Koha logs for details."
 307                 }
 308             );
 309         }
 310     };
 311 }
 312
 313 =head3 _to_api
 314
 315 Helper function that maps unblessed Koha::Patron objects into REST api
 316 attribute names.
 317
 318 =cut
 319
 320 sub _to_api {
 321     my $patron    = shift;
 322     my $patron_id = $patron->{ borrowernumber };
 323
 324     # Rename attributes
 325     foreach my $column ( keys %{ $Koha::REST::V1::Patrons::to_api_mapping } ) {
 326         my $mapped_column = $Koha::REST::V1::Patrons::to_api_mapping->{$column};
 327         if (    exists $patron->{ $column }
 328              && defined $mapped_column )
 329         {
 330             # key != undef
 331             $patron->{ $mapped_column } = delete $patron->{ $column };
 332         }
 333         elsif (    exists $patron->{ $column }
 334                 && !defined $mapped_column )
 335         {
 336             # key == undef
 337             delete $patron->{ $column };
 338         }
 339     }
 340
 341     # Calculate the 'restricted' field
 342     my $patron_obj = Koha::Patrons->find( $patron_id );
 343     $patron->{ restricted } = ($patron_obj->is_debarred) ? Mojo::JSON->true : Mojo::JSON->false;
 344
 345     return $patron;
 346 }
 347
 348 =head3 _to_model
 349
 350 Helper function that maps REST api objects into Koha::Patron
 351 attribute names.
 352
 353 =cut
 354
 355 sub _to_model {
 356     my $patron = shift;
 357
 358     foreach my $attribute ( keys %{ $Koha::REST::V1::Patrons::to_model_mapping } ) {
 359         my $mapped_attribute = $Koha::REST::V1::Patrons::to_model_mapping->{$attribute};
 360         if (    exists $patron->{ $attribute }
 361              && defined $mapped_attribute )
 362         {
 363             # key => !undef
 364             $patron->{ $mapped_attribute } = delete $patron->{ $attribute };
 365         }
 366         elsif (    exists $patron->{ $attribute }
 367                 && !defined $mapped_attribute )
 368         {
 369             # key => undef / to be deleted
 370             delete $patron->{ $attribute };
 371         }
 372     }
 373
 374     # TODO: Get rid of this once write operations are based on Koha::Patron
 375     if ( exists $patron->{lost} ) {
 376         $patron->{lost} = ($patron->{lost}) ? 1 : 0;
 377     }
 378
 379     if ( exists $patron->{ gonenoaddress} ) {
 380         $patron->{gonenoaddress} = ($patron->{gonenoaddress}) ? 1 : 0;
 381     }
 382
 383     return $patron;
 384 }
 385
 386 =head2 Global variables
 387
 388 =head3 $to_api_mapping
 389
 390 =cut
 391
 392 our $to_api_mapping = {
 393     borrowernotes       => 'staff_notes',
 394     borrowernumber      => 'patron_id',
 395     branchcode          => 'library_id',
 396     categorycode        => 'category_id',
 397     checkprevcheckout   => 'check_previous_checkout',
 398     contactfirstname    => undef, # Unused
 399     contactname         => undef, # Unused
 400     contactnote         => 'altaddress_notes',
 401     contacttitle        => undef, # Unused
 402     dateenrolled        => 'date_enrolled',
 403     dateexpiry          => 'expiry_date',
 404     dateofbirth         => 'date_of_birth',
 405     debarred            => undef, # replaced by 'restricted'
 406     debarredcomment     => undef, # calculated, API consumers will use /restrictions instead
 407     emailpro            => 'secondary_email',
 408     flags               => undef, # permissions manipulation handled in /permissions
 409     gonenoaddress       => 'incorrect_address',
 410     guarantorid         => 'guarantor_id',
 411     lastseen            => 'last_seen',
 412     lost                => 'patron_card_lost',
 413     opacnote            => 'opac_notes',
 414     othernames          => 'other_name',
 415     password            => undef, # password manipulation handled in /password
 416     phonepro            => 'secondary_phone',
 417     relationship        => 'relationship_type',
 418     sex                 => 'gender',
 419     smsalertnumber      => 'sms_number',
 420     sort1               => 'statistics_1',
 421     sort2               => 'statistics_2',
 422     streetnumber        => 'street_number',
 423     streettype          => 'street_type',
 424     zipcode             => 'postal_code',
 425     B_address           => 'altaddress_address',
 426     B_address2          => 'altaddress_address2',
 427     B_city              => 'altaddress_city',
 428     B_country           => 'altaddress_country',
 429     B_email             => 'altaddress_email',
 430     B_phone             => 'altaddress_phone',
 431     B_state             => 'altaddress_state',
 432     B_streetnumber      => 'altaddress_street_number',
 433     B_streettype        => 'altaddress_street_type',
 434     B_zipcode           => 'altaddress_postal_code',
 435     altcontactaddress1  => 'altcontact_address',
 436     altcontactaddress2  => 'altcontact_address2',
 437     altcontactaddress3  => 'altcontact_city',
 438     altcontactcountry   => 'altcontact_country',
 439     altcontactfirstname => 'altcontact_firstname',
 440     altcontactphone     => 'altcontact_phone',
 441     altcontactsurname   => 'altcontact_surname',
 442     altcontactstate     => 'altcontact_state',
 443     altcontactzipcode   => 'altcontact_postal_code'
 444 };
 445
 446 =head3 $to_model_mapping
 447
 448 =cut
 449
 450 our $to_model_mapping = {
 451     altaddress_notes         => 'contactnote',
 452     category_id              => 'categorycode',
 453     check_previous_checkout  => 'checkprevcheckout',
 454     date_enrolled            => 'dateenrolled',
 455     date_of_birth            => 'dateofbirth',
 456     expiry_date              => 'dateexpiry',
 457     gender                   => 'sex',
 458     guarantor_id             => 'guarantorid',
 459     incorrect_address        => 'gonenoaddress',
 460     last_seen                => 'lastseen',
 461     library_id               => 'branchcode',
 462     opac_notes               => 'opacnote',
 463     other_name               => 'othernames',
 464     patron_card_lost         => 'lost',
 465     patron_id                => 'borrowernumber',
 466     postal_code              => 'zipcode',
 467     relationship_type        => 'relationship',
 468     restricted               => undef,
 469     secondary_email          => 'emailpro',
 470     secondary_phone          => 'phonepro',
 471     sms_number               => 'smsalertnumber',
 472     staff_notes              => 'borrowernotes',
 473     statistics_1             => 'sort1',
 474     statistics_2             => 'sort2',
 475     street_number            => 'streetnumber',
 476     street_type              => 'streettype',
 477     altaddress_address       => 'B_address',
 478     altaddress_address2      => 'B_address2',
 479     altaddress_city          => 'B_city',
 480     altaddress_country       => 'B_country',
 481     altaddress_email         => 'B_email',
 482     altaddress_phone         => 'B_phone',
 483     altaddress_state         => 'B_state',
 484     altaddress_street_number => 'B_streetnumber',
 485     altaddress_street_type   => 'B_streettype',
 486     altaddress_postal_code   => 'B_zipcode',
 487     altcontact_firstname     => 'altcontactfirstname',
 488     altcontact_surname       => 'altcontactsurname',
 489     altcontact_address       => 'altcontactaddress1',
 490     altcontact_address2      => 'altcontactaddress2',
 491     altcontact_city          => 'altcontactaddress3',
 492     altcontact_state         => 'altcontactstate',
 493     altcontact_postal_code   => 'altcontactzipcode',
 494     altcontact_country       => 'altcontactcountry',
 495     altcontact_phone         => 'altcontactphone'
 496 };
 497
 498 1;