1 package Koha::REST::V1::Patrons;
3 # This file is part of Koha.
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
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.
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.
20 use Mojo::Base 'Mojolicious::Controller';
25 use Scalar::Util qw(blessed);
30 Koha::REST::V1::Patrons
38 Controller function that handles listing Koha::Patron objects
43 my $c = shift->openapi->valid_input or return;
47 my $args = $c->validation->output;
48 my ( $params, $reserved_params ) = $c->extract_reserved_params( $args );
50 # Merge sorting into query attributes
51 $c->dbic_merge_sorting({ attributes => $attributes, params => $reserved_params });
53 # Merge pagination into query attributes
54 $c->dbic_merge_pagination({ filter => $attributes, params => $reserved_params });
56 my $restricted = $args->{restricted};
58 $params = _to_model($params)
60 # deal with string params
61 $params = $c->build_query_params( $params, $reserved_params );
63 # translate 'restricted' => 'debarred'
64 $params->{debarred} = { '!=' => undef }
67 my $patrons = Koha::Patrons->search( $params, $attributes );
68 if ( $patrons->is_paged ) {
69 $c->add_pagination_headers(
71 total => $patrons->pager->total_entries,
77 return $c->render( status => 200, openapi => $patrons->to_api );
80 if ( $_->isa('DBIx::Class::Exception') ) {
83 openapi => { error => $_->{msg} }
89 openapi => { error => "Something went wrong, check the logs." }
98 Controller function that handles retrieving a single Koha::Patron object
103 my $c = shift->openapi->valid_input or return;
105 my $patron_id = $c->validation->param('patron_id');
106 my $patron = Koha::Patrons->find($patron_id);
109 return $c->render( status => 404, openapi => { error => "Patron not found." } );
112 return $c->render( status => 200, openapi => $patron->to_api );
117 Controller function that handles adding a new Koha::Patron object
122 my $c = shift->openapi->valid_input or return;
126 my $body = _to_model( $c->validation->param('body') );
128 my $patron = Koha::Patron->new( _to_model($body) )->store;
130 $c->res->headers->location( $c->req->url->to_string . '/' . $patron->borrowernumber );
133 openapi => $patron->to_api
137 unless ( blessed $_ && $_->can('rethrow') ) {
140 openapi => { error => "Something went wrong, check Koha logs for details." }
143 if ( $_->isa('Koha::Exceptions::Object::DuplicateID') ) {
146 openapi => { error => $_->error, conflict => $_->duplicate_id }
149 elsif ( $_->isa('Koha::Exceptions::Object::FKConstraint') ) {
154 . $Koha::REST::V1::Patrons::to_api_mapping->{ $_->broken_fk }
159 elsif ( $_->isa('Koha::Exceptions::BadParameter') ) {
164 . $Koha::REST::V1::Patrons::to_api_mapping->{ $_->parameter }
172 openapi => { error => "Something went wrong, check Koha logs for details." }
181 Controller function that handles updating a Koha::Patron object
186 my $c = shift->openapi->valid_input or return;
188 my $patron_id = $c->validation->param('patron_id');
189 my $patron = Koha::Patrons->find( $patron_id );
194 openapi => { error => "Patron not found" }
199 my $body = _to_model($c->validation->param('body'));
201 $patron->set($body)->store;
202 $patron->discard_changes;
203 return $c->render( status => 200, openapi => $patron );
206 unless ( blessed $_ && $_->can('rethrow') ) {
210 error => "Something went wrong, check Koha logs for details."
214 if ( $_->isa('Koha::Exceptions::Object::DuplicateID') ) {
217 openapi => { error => $_->error, conflict => $_->duplicate_id }
220 elsif ( $_->isa('Koha::Exceptions::Object::FKConstraint') ) {
223 openapi => { error => "Given " .
224 $Koha::REST::V1::Patrons::to_api_mapping->{$_->broken_fk}
225 . " does not exist" }
228 elsif ( $_->isa('Koha::Exceptions::MissingParameter') ) {
232 error => "Missing mandatory parameter(s)",
233 parameters => $_->parameter
237 elsif ( $_->isa('Koha::Exceptions::BadParameter') ) {
241 error => "Invalid parameter(s)",
242 parameters => $_->parameter
246 elsif ( $_->isa('Koha::Exceptions::NoChanges') ) {
249 openapi => { error => "No changes have been made" }
257 "Something went wrong, check Koha logs for details."
266 Controller function that handles deleting a Koha::Patron object
271 my $c = shift->openapi->valid_input or return;
276 $patron = Koha::Patrons->find( $c->validation->param('patron_id') );
278 # check if loans, reservations, debarrment, etc. before deletion!
279 my $res = $patron->delete;
280 return $c->render( status => 200, openapi => {} );
286 openapi => { error => "Patron not found" }
294 "Something went wrong, check Koha logs for details."
301 =head3 guarantors_can_see_charges
303 Method for setting whether guarantors can see the patron's charges.
307 sub guarantors_can_see_charges {
308 my $c = shift->openapi->valid_input or return;
311 if ( C4::Context->preference('AllowPatronToSetFinesVisibilityForGuarantor') ) {
312 my $patron = $c->stash( 'koha.user' );
313 my $privacy_setting = ($c->req->json->{allowed}) ? 1 : 0;
315 $patron->privacy_guarantor_fines( $privacy_setting )->store;
327 'The current configuration doesn\'t allow the requested action.'
337 "Something went wrong, check Koha logs for details. $_"
343 =head3 guarantors_can_see_checkouts
345 Method for setting whether guarantors can see the patron's checkouts.
349 sub guarantors_can_see_checkouts {
350 my $c = shift->openapi->valid_input or return;
353 if ( C4::Context->preference('AllowPatronToSetCheckoutsVisibilityForGuarantor') ) {
354 my $patron = $c->stash( 'koha.user' );
355 my $privacy_setting = ( $c->req->json->{allowed} ) ? 1 : 0;
357 $patron->privacy_guarantor_checkouts( $privacy_setting )->store;
369 'The current configuration doesn\'t allow the requested action.'
379 "Something went wrong, check Koha logs for details. $_"
385 =head2 Internal methods
389 Helper function that maps unblessed Koha::Patron objects into REST api
396 my $patron_id = $patron->{ borrowernumber };
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 )
405 $patron->{ $mapped_column } = delete $patron->{ $column };
407 elsif ( exists $patron->{ $column }
408 && !defined $mapped_column )
411 delete $patron->{ $column };
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;
424 Helper function that maps REST api objects into Koha::Patron
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 )
438 $patron->{ $mapped_attribute } = delete $patron->{ $attribute };
440 elsif ( exists $patron->{ $attribute }
441 && !defined $mapped_attribute )
443 # key => undef / to be deleted
444 delete $patron->{ $attribute };
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;
453 if ( exists $patron->{ gonenoaddress} ) {
454 $patron->{gonenoaddress} = ($patron->{gonenoaddress}) ? 1 : 0;
457 if ( exists $patron->{lastseen} ) {
458 $patron->{lastseen} = output_pref({ str => $patron->{lastseen}, dateformat => 'sql' });
461 if ( exists $patron->{updated_on} ) {
462 $patron->{updated_on} = output_pref({ str => $patron->{updated_on}, dateformat => 'sql' });
468 =head2 Global variables
470 =head3 $to_api_mapping
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',
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'
528 =head3 $to_model_mapping
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',
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',
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'