misc/cronjobs/holds/holds_reminder.pl

   1 #!/usr/bin/perl
   2
   3 # This file is part of Koha.
   4 #
   5 # Koha is free software; you can redistribute it and/or modify it
   6 # under the terms of the GNU General Public License as published by
   7 # the Free Software Foundation; either version 3 of the License, or
   8 # (at your option) any later version.
   9 #
  10 # Koha is distributed in the hope that it will be useful, but
  11 # WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13 # GNU General Public License for more details.
  14 #
  15 # You should have received a copy of the GNU General Public License
  16 # along with Koha; if not, see <http://www.gnu.org/licenses>.
  17
  18 use Modern::Perl;
  19
  20 use Getopt::Long qw( GetOptions );
  21 use Pod::Usage qw( pod2usage );
  22 use DateTime;
  23 use DateTime::Duration;
  24
  25 use C4::Context;
  26 use C4::Letters;
  27 use C4::Log qw( cronlogaction );
  28 use Koha::DateUtils qw( dt_from_string );
  29 use Koha::Calendar;
  30 use Koha::Libraries;
  31 use Koha::Notice::Templates;
  32 use Koha::Patrons;
  33 use Koha::Script -cron;
  34
  35 =head1 NAME
  36
  37 holds_reminder.pl - prepare reminder messages to be sent to patrons with waiting holds
  38
  39 =head1 SYNOPSIS
  40
  41 holds_reminder.pl
  42   -lettercode <notice to send>
  43   [ -c ][ -v ][ -library <branchcode> ][ -library <branchcode> ... ]
  44   [ -days <number of days> ][ -mtt <transport type> ... ][ -holidays ]
  45   [ -date <YYYY-MM-DD> ]
  46
  47  Options:
  48    -help                          brief help message
  49    -man                           full documentation
  50    -v                             verbose
  51    -c --confirm                   confirm, if not set no email will be sent
  52    -days          <days>          days waiting to deal with
  53    -t --triggered                 include only holds <days> days waiting, and not longer
  54    -lettercode   <lettercode>     predefined notice to use, default is HOLD_REMINDER
  55    -library      <branchname>     only deal with holds from this library (repeatable : several libraries can be given)
  56    -holidays                      use the calendar to not count holidays as waiting days
  57    -mtt          <message_transport_type> type of messages to send, default is to use patrons messaging preferences for Hold reminder
  58                                   populating this will force send even if patron has not chosen to receive hold notices
  59                                   email and sms will fallback to print if borrower does not have an address/phone
  60    -date                          Send notices as would have been sent on a specific date
  61
  62 =head1 OPTIONS
  63
  64 =over 8
  65
  66 =item B<-help>
  67
  68 Print a brief help message and exits.
  69
  70 =item B<-man>
  71
  72 Prints the manual page and exits.
  73
  74 =item B<-v>
  75
  76 Verbose. Without this flag set, only fatal errors are reported.
  77
  78 =item B<--confirm | -c>
  79
  80 Confirm. Unless set this script does not send any email (test-mode).
  81 If verbose and not confirm a list of notices that would have been sent to
  82 the patrons are printed to standard out.
  83
  84 =item B<-days>
  85
  86 Optional parameter, number of days an items has been 'waiting' on hold
  87 to send a message for. If not included a notice will be sent to all
  88 patrons with waiting holds.
  89
  90 =item B<-triggered>
  91
  92 Optional parameter, only send notices for holds exactly <days> waiting.
  93 If not included a notice will be sent to all patrons with waiting holds
  94 equal to OR greater than <days>. This option is useful if the cron is
  95 being run daily to avoid spamming the patrons.
  96
  97 =item B<-lettercode>
  98
  99 Optional parameter, choose a notice to use. Default is 'HOLD_REMINDER'.
 100
 101 =item B<-library>
 102
 103 select notices for one specific library. Use the value in the
 104 branches.branchcode table. This option can be repeated in order
 105 to select notices for a group of libraries.
 106
 107 =item B<-holidays>
 108
 109 This option determines whether library holidays are used when calculating how
 110 long an item has been waiting. If enabled the count will skip closed days.
 111
 112 =item B<-date>
 113
 114 use it in order to send notices on a specific date and not Now. Format: YYYY-MM-DD.
 115
 116 =item B<-mtt>
 117
 118 send a notices via a specific transport, this can be repeated to send various notices.
 119 If omitted the patron's messaging preferences for Hold notices will be used.
 120 If supplied the notice types will be force sent even if patron has not selected hold notices
 121 Email and SMS will fall back to print if there is no valid info in the patron's account
 122
 123
 124 =back
 125
 126 =head1 DESCRIPTION
 127
 128 This script is designed to alert patrons of waiting
 129 holds.
 130
 131 =head2 Configuration
 132
 133 This script sends reminders to patrons with waiting holds using a notice
 134 defined in the Tools > Notices and slips module within Koha. The lettercode
 135 is passed into this script and, along with other options, determine the content
 136 of the notices sent to patrons.
 137
 138
 139 =head1 USAGE EXAMPLES
 140
 141 C<holds_reminder.pl> - With no arguments the simple help is printed
 142
 143 C<holds_reminder.pl > In this most basic usage all
 144 libraries are processed individually, and notices are prepared for
 145 all patrons with waiting holds for whom we have email addresses.
 146 Messages for those patrons for whom we have no email
 147 address are sent in a single attachment to the library administrator's
 148 email address, or to the address in the KohaAdminEmailAddress system
 149 preference.
 150
 151 C<holds_reminder.pl -n -csv /tmp/holds_reminder.csv> - sends no email and
 152 populates F</tmp/holds_reminder.csv> with information about all waiting holds
 153 items.
 154
 155 C<holds_reminder.pl -library MAIN -days 14> - prepare notices of
 156 holds waiting for 2 weeks for the MAIN library.
 157
 158 C<holds_reminder.pl -lettercode LATE_HOLDS -library MAIN -days 14> - prepare notices of
 159 holds waiting for 2 weeks for the MAIN library. Use lettercode 'LATE_HOLDS'
 160
 161 =cut
 162
 163 # These variables are set by command line options.
 164 # They are initially set to default values.
 165 my $dbh = C4::Context->dbh();
 166 my $help    = 0;
 167 my $man     = 0;
 168 my $verbose = 0;
 169 my $confirm  = 0;
 170 my $days    ;
 171 my $triggered  = 0;
 172 my $lettercode;
 173 my @branchcodes; # Branch(es) passed as parameter
 174 my $use_calendar = 0;
 175 my $date_input;
 176 my $opt_out = 0;
 177 my @mtts;
 178
 179 my $command_line_options = join(" ",@ARGV);
 180
 181 GetOptions(
 182     'help|?'         => \$help,
 183     'man'            => \$man,
 184     'v'              => \$verbose,
 185     'c|confirm'      => \$confirm,
 186     'days=s'         => \$days,
 187     'triggered'      => \$triggered,
 188     'lettercode=s'   => \$lettercode,
 189     'library=s'      => \@branchcodes,
 190     'date=s'         => \$date_input,
 191     'holidays'       => \$use_calendar,
 192     'mtt=s'          => \@mtts
 193 );
 194 pod2usage(1) if $help;
 195 pod2usage( -verbose => 2 ) if $man;
 196
 197 $lettercode ||= 'HOLD_REMINDER';
 198
 199 cronlogaction({ info => $command_line_options });
 200
 201 # Unless a delay is specified by the user we target all waiting holds
 202 unless (defined $days) {
 203     $days=0;
 204 }
 205
 206 # Unless one ore more branchcodes are passed we use all the branches
 207 if (scalar @branchcodes > 0) {
 208     my $branchcodes_word = scalar @branchcodes > 1 ? 'branches' : 'branch';
 209     $verbose and warn "$branchcodes_word @branchcodes passed on parameter\n";
 210 }
 211 else {
 212     @branchcodes = Koha::Libraries->search()->get_column('branchcode');
 213 }
 214
 215 # If provided we run the report as if it had run on a specified date
 216 my $date_to_run;
 217 if ( $date_input ){
 218     eval {
 219         $date_to_run = dt_from_string( $date_input, 'iso' );
 220     };
 221     die "$date_input is not a valid date, aborting! Use a date in format YYYY-MM-DD."
 222         if $@ or not $date_to_run;
 223 }
 224 else {
 225     $date_to_run = dt_from_string();
 226 }
 227
 228 my $waiting_date_static = $date_to_run->clone->subtract( days => $days );
 229
 230 # Loop through each branch
 231 foreach my $branchcode (@branchcodes) { #BEGIN BRANCH LOOP
 232     # Check that this branch has the letter code specified or skip this branch
 233
 234     # FIXME What if we don't want to default if the translated template does not exist?
 235     my $template_exists = Koha::Notice::Templates->find_effective_template(
 236         {
 237             module     => 'reserves',
 238             code       => $lettercode,
 239             branchcode => $branchcode,
 240             lang       => 'default',
 241         }
 242     );
 243     unless ($template_exists) {
 244         $verbose and print qq|Message '$lettercode' content not found for $branchcode\n|;
 245         next;
 246     }
 247
 248     # If respecting calendar get the correct waiting since date
 249     my $waiting_date;
 250     if( $use_calendar ){
 251         my $calendar = Koha::Calendar->new( branchcode => $branchcode, days_mode => 'Calendar' );
 252         my $duration = DateTime::Duration->new( days => -$days );
 253         $waiting_date = $calendar->addDays($date_to_run,$duration); #Add negative of days
 254     } else {
 255         $waiting_date = $waiting_date_static;
 256     }
 257
 258     # Find all the holds waiting since this date for the current branch
 259     my $dtf = Koha::Database->new->schema->storage->datetime_parser;
 260     my $waiting_since = $dtf->format_date( $waiting_date );
 261     my $comparator = $triggered ? '=' : '<=';
 262     my $reserves = Koha::Holds->search({
 263         waitingdate => {$comparator => $waiting_since },
 264         'me.branchcode'  => $branchcode,
 265         '-or' => [ expirationdate => undef, expirationdate => { '>' => \'CURDATE()' } ]
 266     },{ prefetch => 'patron' });
 267
 268     $verbose and warn "No reserves found for $branchcode\n" unless $reserves->count;
 269     next unless $reserves->count;
 270     $verbose and warn $reserves->count . " reserves waiting since $waiting_since for $branchcode\n";
 271
 272     # We only want to send one notice per patron per branch - this variable will hold the completed borrowers
 273     my %done;
 274
 275     # If passed message transports we force use those, otherwise we will use the patrons preferences
 276     # for the 'Hold_Reminder' notice
 277     my $sending_params = @mtts ? { message_transports => \@mtts } : { message_name => "Hold_Reminder" };
 278
 279
 280     my %patrons;
 281     while ( my $reserve = $reserves->next ) {
 282         $patrons{$reserve->borrowernumber}->{patron} = $reserve->patron unless exists $patrons{$reserve->borrowernumber};
 283         push @{$patrons{$reserve->borrowernumber}->{reserves}}, $reserve->reserve_id;
 284     }
 285
 286     foreach my $borrowernumber (keys %patrons){
 287
 288         my $patron = $patrons{$borrowernumber}->{patron};
 289         $verbose and print "  borrower " . $patron->surname . ", " . $patron->firstname . " has " . scalar @{$patrons{$borrowernumber}->{reserves}}  . " holds triggering notice.\n";
 290
 291         # Setup the notice information
 292         my $letter_params = {
 293             module          => 'reserves',
 294             letter_code     => $lettercode,
 295             borrowernumber  => $patron->borrowernumber,
 296             branchcode      => $branchcode,
 297             tables          => {
 298                  borrowers  => $patron->borrowernumber,
 299                  branches   => $branchcode,
 300             },
 301             loops           => {
 302                 reserves    => $patrons{$borrowernumber}->{reserves}
 303             },
 304         };
 305         $sending_params->{letter_params} = $letter_params;
 306         $sending_params->{test_mode} = !$confirm;
 307         my $result_text = $confirm ? "was sent" : "would have been sent";
 308         # queue_notice queues the notices, falling back to print for email or SMS, and ignores phone (they are handled by Itiva)
 309         my $result = $patron->queue_notice( $sending_params );
 310         $verbose and print "   borrower " . $patron->surname . ", " . $patron->firstname . " $result_text notices via: @{$result->{sent}}\n" if defined $result->{sent};
 311         $verbose and print "   borrower " . $patron->surname . ", " . $patron->firstname . " $result_text print fallback for: @{$result->{fallback}}\n" if defined $result->{fallback};
 312         # Mark this borrower as completed
 313         $done{$patron->borrowernumber} = 1;
 314     }
 315
 316
 317 } #END BRANCH LOOP
 318
 319 cronlogaction({ action => 'End', info => "COMPLETED" });