Bug 24584: Rewrite optional/sample_creator_data to YAML
[koha.git] / C4 / Suggestions.pm
blob8157e590245c30337c5b6ffdf7d1ad6f6a463428
1 package C4::Suggestions;
3 # Copyright 2000-2002 Katipo Communications
4 # Parts Copyright Biblibre 2011
6 # This file is part of Koha.
8 # Koha is free software; you can redistribute it and/or modify it
9 # under the terms of the GNU General Public License as published by
10 # the Free Software Foundation; either version 3 of the License, or
11 # (at your option) any later version.
13 # Koha is distributed in the hope that it will be useful, but
14 # WITHOUT ANY WARRANTY; without even the implied warranty of
15 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 # GNU General Public License for more details.
18 # You should have received a copy of the GNU General Public License
19 # along with Koha; if not, see <http://www.gnu.org/licenses>.
21 use Modern::Perl;
22 use CGI qw ( -utf8 );
24 use C4::Context;
25 use C4::Output;
26 use C4::Debug;
27 use C4::Letters;
28 use C4::Biblio qw( GetMarcFromKohaField );
29 use Koha::DateUtils;
30 use Koha::Suggestions;
32 use List::MoreUtils qw(any);
33 use base qw(Exporter);
35 our @EXPORT = qw(
36 ConnectSuggestionAndBiblio
37 CountSuggestion
38 DelSuggestion
39 GetSuggestion
40 GetSuggestionByStatus
41 GetSuggestionFromBiblionumber
42 GetSuggestionInfoFromBiblionumber
43 GetSuggestionInfo
44 ModStatus
45 ModSuggestion
46 NewSuggestion
47 SearchSuggestion
48 DelSuggestionsOlderThan
49 GetUnprocessedSuggestions
50 MarcRecordFromNewSuggestion
53 =head1 NAME
55 C4::Suggestions - Some useful functions for dealings with aqorders.
57 =head1 SYNOPSIS
59 use C4::Suggestions;
61 =head1 DESCRIPTION
63 The functions in this module deal with the aqorders in OPAC and in librarian interface
65 A suggestion is done in the OPAC. It has the status "ASKED"
67 When a librarian manages the suggestion, they can set the status to "REJECTED" or "ACCEPTED".
69 When the book is ordered, the suggestion status becomes "ORDERED"
71 When a book is ordered and arrived in the library, the status becomes "AVAILABLE"
73 All aqorders of a borrower can be seen by the borrower itself.
74 Suggestions done by other borrowers can be seen when not "AVAILABLE"
76 =head1 FUNCTIONS
78 =head2 SearchSuggestion
80 (\@array) = &SearchSuggestion($suggestionhashref_to_search)
82 searches for a suggestion
84 return :
85 C<\@array> : the aqorders found. Array of hash.
86 Note the status is stored twice :
87 * in the status field
88 * as parameter ( for example ASKED => 1, or REJECTED => 1) . This is for template & translation purposes.
90 =cut
92 sub SearchSuggestion {
93 my ($suggestion) = @_;
94 my $dbh = C4::Context->dbh;
95 my @sql_params;
96 my @query = (
98 SELECT suggestions.*,
99 U1.branchcode AS branchcodesuggestedby,
100 B1.branchname AS branchnamesuggestedby,
101 U1.surname AS surnamesuggestedby,
102 U1.firstname AS firstnamesuggestedby,
103 U1.cardnumber AS cardnumbersuggestedby,
104 U1.email AS emailsuggestedby,
105 U1.borrowernumber AS borrnumsuggestedby,
106 U1.categorycode AS categorycodesuggestedby,
107 C1.description AS categorydescriptionsuggestedby,
108 U2.surname AS surnamemanagedby,
109 U2.firstname AS firstnamemanagedby,
110 B2.branchname AS branchnamesuggestedby,
111 U2.email AS emailmanagedby,
112 U2.branchcode AS branchcodemanagedby,
113 U2.borrowernumber AS borrnummanagedby,
114 BU.budget_name AS budget_name
115 FROM suggestions
116 LEFT JOIN borrowers AS U1 ON suggestedby=U1.borrowernumber
117 LEFT JOIN branches AS B1 ON B1.branchcode=U1.branchcode
118 LEFT JOIN categories AS C1 ON C1.categorycode=U1.categorycode
119 LEFT JOIN borrowers AS U2 ON managedby=U2.borrowernumber
120 LEFT JOIN branches AS B2 ON B2.branchcode=U2.branchcode
121 LEFT JOIN categories AS C2 ON C2.categorycode=U2.categorycode
122 LEFT JOIN aqbudgets AS BU ON budgetid=BU.budget_id
123 WHERE 1=1
127 # filter on biblio informations
128 foreach my $field (
129 qw( title author isbn publishercode copyrightdate collectiontitle ))
131 if ( $suggestion->{$field} ) {
132 push @sql_params, '%' . $suggestion->{$field} . '%';
133 push @query, qq{ AND suggestions.$field LIKE ? };
137 # filter on user branch
138 if ( C4::Context->preference('IndependentBranches')
139 && !C4::Context->IsSuperLibrarian() )
141 # If IndependentBranches is set and the logged in user is not superlibrarian
142 # Then we want to filter by the user's library (i.e. cannot see suggestions from other libraries)
143 my $userenv = C4::Context->userenv;
144 if ($userenv) {
146 push @sql_params, $$userenv{branch};
147 push @query, q{
148 AND (suggestions.branchcode=? OR suggestions.branchcode='')
153 elsif (defined $suggestion->{branchcode}
154 && $suggestion->{branchcode}
155 && $suggestion->{branchcode} ne '__ANY__' )
157 # If IndependentBranches is not set OR the logged in user is not superlibrarian
158 # AND the branchcode filter is passed and not '__ANY__'
159 # Then we want to filter using this parameter
160 push @sql_params, $suggestion->{branchcode};
161 push @query, qq{ AND suggestions.branchcode=? };
164 # filter on nillable fields
165 foreach my $field (
166 qw( STATUS itemtype suggestedby managedby acceptedby budgetid biblionumber )
169 if ( exists $suggestion->{$field}
170 and defined $suggestion->{$field}
171 and $suggestion->{$field} ne '__ANY__'
172 and (
173 $suggestion->{$field} ne q||
174 or $field eq 'STATUS'
177 if ( $suggestion->{$field} eq '__NONE__' ) {
178 push @query, qq{ AND (suggestions.$field = '' OR suggestions.$field IS NULL) };
180 else {
181 push @sql_params, $suggestion->{$field};
182 push @query, qq{ AND suggestions.$field = ? };
187 # filter on date fields
188 foreach my $field (qw( suggesteddate manageddate accepteddate )) {
189 my $from = $field . "_from";
190 my $to = $field . "_to";
191 my $from_dt;
192 $from_dt = eval { dt_from_string( $suggestion->{$from} ) } if ( $suggestion->{$from} );
193 my $from_sql = '0000-00-00';
194 $from_sql = output_pref({ dt => $from_dt, dateformat => 'iso', dateonly => 1 })
195 if ($from_dt);
196 $debug && warn "SQL for start date ($field): $from_sql";
197 if ( $suggestion->{$from} || $suggestion->{$to} ) {
198 push @query, qq{ AND suggestions.$field BETWEEN ? AND ? };
199 push @sql_params, $from_sql;
200 push @sql_params,
201 output_pref({ dt => dt_from_string( $suggestion->{$to} ), dateformat => 'iso', dateonly => 1 }) || output_pref({ dt => dt_from_string, dateformat => 'iso', dateonly => 1 });
205 $debug && warn "@query";
206 my $sth = $dbh->prepare("@query");
207 $sth->execute(@sql_params);
208 my @results;
210 # add status as field
211 while ( my $data = $sth->fetchrow_hashref ) {
212 $data->{ $data->{STATUS} } = 1;
213 push( @results, $data );
216 return ( \@results );
219 =head2 GetSuggestion
221 \%sth = &GetSuggestion($suggestionid)
223 this function get the detail of the suggestion $suggestionid (input arg)
225 return :
226 the result of the SQL query as a hash : $sth->fetchrow_hashref.
228 =cut
230 sub GetSuggestion {
231 my ($suggestionid) = @_;
232 my $dbh = C4::Context->dbh;
233 my $query = q{
234 SELECT *
235 FROM suggestions
236 WHERE suggestionid=?
238 my $sth = $dbh->prepare($query);
239 $sth->execute($suggestionid);
240 return ( $sth->fetchrow_hashref );
243 =head2 GetSuggestionFromBiblionumber
245 $ordernumber = &GetSuggestionFromBiblionumber($biblionumber)
247 Get a suggestion from it's biblionumber.
249 return :
250 the id of the suggestion which is related to the biblionumber given on input args.
252 =cut
254 sub GetSuggestionFromBiblionumber {
255 my ($biblionumber) = @_;
256 my $query = q{
257 SELECT suggestionid
258 FROM suggestions
259 WHERE biblionumber=? LIMIT 1
261 my $dbh = C4::Context->dbh;
262 my $sth = $dbh->prepare($query);
263 $sth->execute($biblionumber);
264 my ($suggestionid) = $sth->fetchrow;
265 return $suggestionid;
268 =head2 GetSuggestionInfoFromBiblionumber
270 Get a suggestion and borrower's informations from it's biblionumber.
272 return :
273 all informations (suggestion and borrower) of the suggestion which is related to the biblionumber given.
275 =cut
277 sub GetSuggestionInfoFromBiblionumber {
278 my ($biblionumber) = @_;
279 my $query = q{
280 SELECT suggestions.*,
281 U1.surname AS surnamesuggestedby,
282 U1.firstname AS firstnamesuggestedby,
283 U1.borrowernumber AS borrnumsuggestedby
284 FROM suggestions
285 LEFT JOIN borrowers AS U1 ON suggestedby=U1.borrowernumber
286 WHERE biblionumber=?
287 LIMIT 1
289 my $dbh = C4::Context->dbh;
290 my $sth = $dbh->prepare($query);
291 $sth->execute($biblionumber);
292 return $sth->fetchrow_hashref;
295 =head2 GetSuggestionInfo
297 Get a suggestion and borrower's informations from it's suggestionid
299 return :
300 all informations (suggestion and borrower) of the suggestion which is related to the suggestionid given.
302 =cut
304 sub GetSuggestionInfo {
305 my ($suggestionid) = @_;
306 my $query = q{
307 SELECT suggestions.*,
308 U1.surname AS surnamesuggestedby,
309 U1.firstname AS firstnamesuggestedby,
310 U1.borrowernumber AS borrnumsuggestedby
311 FROM suggestions
312 LEFT JOIN borrowers AS U1 ON suggestedby=U1.borrowernumber
313 WHERE suggestionid=?
314 LIMIT 1
316 my $dbh = C4::Context->dbh;
317 my $sth = $dbh->prepare($query);
318 $sth->execute($suggestionid);
319 return $sth->fetchrow_hashref;
322 =head2 GetSuggestionByStatus
324 $aqorders = &GetSuggestionByStatus($status,[$branchcode])
326 Get a suggestion from it's status
328 return :
329 all the suggestion with C<$status>
331 =cut
333 sub GetSuggestionByStatus {
334 my $status = shift;
335 my $branchcode = shift;
336 my $dbh = C4::Context->dbh;
337 my @sql_params = ($status);
338 my $query = q{
339 SELECT suggestions.*,
340 U1.surname AS surnamesuggestedby,
341 U1.firstname AS firstnamesuggestedby,
342 U1.branchcode AS branchcodesuggestedby,
343 B1.branchname AS branchnamesuggestedby,
344 U1.borrowernumber AS borrnumsuggestedby,
345 U1.categorycode AS categorycodesuggestedby,
346 C1.description AS categorydescriptionsuggestedby,
347 U2.surname AS surnamemanagedby,
348 U2.firstname AS firstnamemanagedby,
349 U2.borrowernumber AS borrnummanagedby
350 FROM suggestions
351 LEFT JOIN borrowers AS U1 ON suggestedby=U1.borrowernumber
352 LEFT JOIN borrowers AS U2 ON managedby=U2.borrowernumber
353 LEFT JOIN categories AS C1 ON C1.categorycode=U1.categorycode
354 LEFT JOIN branches AS B1 on B1.branchcode=U1.branchcode
355 WHERE status = ?
356 ORDER BY suggestionid
359 # filter on branch
360 if ( C4::Context->preference("IndependentBranches") || $branchcode ) {
361 my $userenv = C4::Context->userenv;
362 if ($userenv) {
363 unless ( C4::Context->IsSuperLibrarian() ) {
364 push @sql_params, $userenv->{branch};
365 $query .= q{ AND (U1.branchcode = ? OR U1.branchcode ='') };
368 if ($branchcode) {
369 push @sql_params, $branchcode;
370 $query .= q{ AND (U1.branchcode = ? OR U1.branchcode ='') };
374 my $sth = $dbh->prepare($query);
375 $sth->execute(@sql_params);
376 my $results;
377 $results = $sth->fetchall_arrayref( {} );
378 return $results;
381 =head2 CountSuggestion
383 &CountSuggestion($status)
385 Count the number of aqorders with the status given on input argument.
386 the arg status can be :
388 =over 2
390 =item * ASKED : asked by the user, not dealed by the librarian
392 =item * ACCEPTED : accepted by the librarian, but not yet ordered
394 =item * REJECTED : rejected by the librarian (definitive status)
396 =item * ORDERED : ordered by the librarian (acquisition module)
398 =back
400 return :
401 the number of suggestion with this status.
403 =cut
405 sub CountSuggestion {
406 my ($status) = @_;
407 my $dbh = C4::Context->dbh;
408 my $sth;
409 my $userenv = C4::Context->userenv;
410 if ( C4::Context->preference("IndependentBranches")
411 && !C4::Context->IsSuperLibrarian() )
413 my $query = q{
414 SELECT count(*)
415 FROM suggestions
416 LEFT JOIN borrowers ON borrowers.borrowernumber=suggestions.suggestedby
417 WHERE STATUS=?
418 AND (suggestions.branchcode='' OR suggestions.branchcode=?)
420 $sth = $dbh->prepare($query);
421 $sth->execute( $status, $userenv->{branch} );
423 else {
424 my $query = q{
425 SELECT count(*)
426 FROM suggestions
427 WHERE STATUS=?
429 $sth = $dbh->prepare($query);
430 $sth->execute($status);
432 my ($result) = $sth->fetchrow;
433 return $result;
436 =head2 NewSuggestion
439 &NewSuggestion($suggestion);
441 Insert a new suggestion on database with value given on input arg.
443 =cut
445 sub NewSuggestion {
446 my ($suggestion) = @_;
448 $suggestion->{STATUS} = "ASKED" unless $suggestion->{STATUS};
450 $suggestion->{suggesteddate} = dt_from_string unless $suggestion->{suggesteddate};
452 delete $suggestion->{branchcode} if $suggestion->{branchcode} eq '';
454 my $suggestion_object = Koha::Suggestion->new( $suggestion )->store;
455 my $suggestion_id = $suggestion_object->suggestionid;
457 my $emailpurchasesuggestions = C4::Context->preference("EmailPurchaseSuggestions");
458 if ($emailpurchasesuggestions) {
459 my $full_suggestion = GetSuggestion( $suggestion_id); # We should not need to refetch it!
460 if (
461 my $letter = C4::Letters::GetPreparedLetter(
462 module => 'suggestions',
463 letter_code => 'NEW_SUGGESTION',
464 tables => {
465 'branches' => $full_suggestion->{branchcode},
466 'borrowers' => $full_suggestion->{suggestedby},
467 'suggestions' => $full_suggestion,
472 my $toaddress;
473 if ( $emailpurchasesuggestions eq "BranchEmailAddress" ) {
474 my $library =
475 Koha::Libraries->find( $full_suggestion->{branchcode} );
476 $toaddress =
477 $library->branchreplyto
478 || $library->branchemail
479 || C4::Context->preference('ReplytoDefault')
480 || C4::Context->preference('KohaAdminEmailAddress');
482 elsif ( $emailpurchasesuggestions eq "KohaAdminEmailAddress" ) {
483 $toaddress = C4::Context->preference('ReplytoDefault')
484 || C4::Context->preference('KohaAdminEmailAddress');
486 else {
487 $toaddress =
488 C4::Context->preference($emailpurchasesuggestions)
489 || C4::Context->preference('ReplytoDefault')
490 || C4::Context->preference('KohaAdminEmailAddress');
493 C4::Letters::EnqueueLetter(
495 letter => $letter,
496 borrowernumber => $full_suggestion->{suggestedby},
497 suggestionid => $full_suggestion->{suggestionid},
498 to_address => $toaddress,
499 message_transport_type => 'email',
501 ) or warn "can't enqueue letter $letter";
505 return $suggestion_id;
508 =head2 ModSuggestion
510 &ModSuggestion($suggestion)
512 Modify the suggestion according to the hash passed by ref.
513 The hash HAS to contain suggestionid
514 Data not defined is not updated unless it is a note or sort1
515 Send a mail to notify the user that did the suggestion.
517 Note that there is no function to modify a suggestion.
519 =cut
521 sub ModSuggestion {
522 my ($suggestion) = @_;
523 return unless( $suggestion and defined($suggestion->{suggestionid}) );
525 my $suggestion_object = Koha::Suggestions->find( $suggestion->{suggestionid} );
526 eval { # FIXME Must raise an exception instead
527 $suggestion_object->set($suggestion)->store;
529 return 0 if $@;
531 if ( $suggestion->{STATUS} ) {
533 # fetch the entire updated suggestion so that we can populate the letter
534 my $full_suggestion = GetSuggestion( $suggestion->{suggestionid} );
535 my $patron = Koha::Patrons->find( $full_suggestion->{suggestedby} );
537 my $transport = (C4::Context->preference("FallbackToSMSIfNoEmail")) && ($patron->smsalertnumber) && (!$patron->email) ? 'sms' : 'email';
539 if (
540 my $letter = C4::Letters::GetPreparedLetter(
541 module => 'suggestions',
542 letter_code => $full_suggestion->{STATUS},
543 branchcode => $full_suggestion->{branchcode},
544 lang => $patron->lang,
545 tables => {
546 'branches' => $full_suggestion->{branchcode},
547 'borrowers' => $full_suggestion->{suggestedby},
548 'suggestions' => $full_suggestion,
549 'biblio' => $full_suggestion->{biblionumber},
554 C4::Letters::EnqueueLetter(
556 letter => $letter,
557 borrowernumber => $full_suggestion->{suggestedby},
558 suggestionid => $full_suggestion->{suggestionid},
559 LibraryName => C4::Context->preference("LibraryName"),
560 message_transport_type => $transport,
562 ) or warn "can't enqueue letter $letter";
565 return 1; # No useful if the exception is raised earlier
568 =head2 ConnectSuggestionAndBiblio
570 &ConnectSuggestionAndBiblio($ordernumber,$biblionumber)
572 connect a suggestion to an existing biblio
574 =cut
576 sub ConnectSuggestionAndBiblio {
577 my ( $suggestionid, $biblionumber ) = @_;
578 my $dbh = C4::Context->dbh;
579 my $query = q{
580 UPDATE suggestions
581 SET biblionumber=?
582 WHERE suggestionid=?
584 my $sth = $dbh->prepare($query);
585 $sth->execute( $biblionumber, $suggestionid );
588 =head2 DelSuggestion
590 &DelSuggestion($borrowernumber,$ordernumber)
592 Delete a suggestion. A borrower can delete a suggestion only if they are its owner.
594 =cut
596 sub DelSuggestion {
597 my ( $borrowernumber, $suggestionid, $type ) = @_;
598 my $dbh = C4::Context->dbh;
600 # check that the suggestion comes from the suggestor
601 my $query = q{
602 SELECT suggestedby
603 FROM suggestions
604 WHERE suggestionid=?
606 my $sth = $dbh->prepare($query);
607 $sth->execute($suggestionid);
608 my ($suggestedby) = $sth->fetchrow;
609 if ( $type eq 'intranet' || $suggestedby eq $borrowernumber ) {
610 my $queryDelete = q{
611 DELETE FROM suggestions
612 WHERE suggestionid=?
614 $sth = $dbh->prepare($queryDelete);
615 my $suggestiondeleted = $sth->execute($suggestionid);
616 return $suggestiondeleted;
620 =head2 DelSuggestionsOlderThan
621 &DelSuggestionsOlderThan($days)
623 Delete all suggestions older than TODAY-$days , that have be accepted or rejected.
624 We do now allow a negative number. If you want to delete all suggestions, just use Koha::Suggestions->delete or so.
626 =cut
628 sub DelSuggestionsOlderThan {
629 my ($days) = @_;
630 return unless $days && $days > 0;
631 my $dbh = C4::Context->dbh;
632 my $sth = $dbh->prepare(
634 DELETE FROM suggestions
635 WHERE STATUS<>'ASKED'
636 AND date < ADDDATE(NOW(), ?)
639 $sth->execute("-$days");
642 sub GetUnprocessedSuggestions {
643 my ( $number_of_days_since_the_last_modification ) = @_;
645 $number_of_days_since_the_last_modification ||= 0;
647 my $dbh = C4::Context->dbh;
649 my $s = $dbh->selectall_arrayref(q|
650 SELECT *
651 FROM suggestions
652 WHERE STATUS = 'ASKED'
653 AND budgetid IS NOT NULL
654 AND CAST(NOW() AS DATE) - INTERVAL ? DAY = CAST(suggesteddate AS DATE)
655 |, { Slice => {} }, $number_of_days_since_the_last_modification );
656 return $s;
659 =head2 MarcRecordFromNewSuggestion
661 $record = MarcRecordFromNewSuggestion ( $suggestion )
663 This function build a marc record object from a suggestion
665 =cut
667 sub MarcRecordFromNewSuggestion {
668 my ($suggestion) = @_;
669 my $record = MARC::Record->new();
671 my ($title_tag, $title_subfield) = GetMarcFromKohaField('biblio.title', '');
672 $record->append_fields(
673 MARC::Field->new($title_tag, ' ', ' ', $title_subfield => $suggestion->{title})
676 my ($author_tag, $author_subfield) = GetMarcFromKohaField('biblio.author', '');
677 if ($record->field( $author_tag )) {
678 $record->field( $author_tag )->add_subfields( $author_subfield => $suggestion->{author} );
680 else {
681 $record->append_fields(
682 MARC::Field->new($author_tag, ' ', ' ', $author_subfield => $suggestion->{author})
686 my ($it_tag, $it_subfield) = GetMarcFromKohaField('biblioitems.itemtype', '');
687 if ($record->field( $it_tag )) {
688 $record->field( $it_tag )->add_subfields( $it_subfield => $suggestion->{itemtype} );
690 else {
691 $record->append_fields(
692 MARC::Field->new($it_tag, ' ', ' ', $it_subfield => $suggestion->{itemtype})
696 return $record;
700 __END__
703 =head1 AUTHOR
705 Koha Development Team <http://koha-community.org/>
707 =cut