misc/cronjobs/stockrotation.pl

   1 #!/usr/bin/perl
   2
   3 # Copyright 2016 PTFS Europe
   4 #
   5 # This file is part of Koha.
   6 #
   7 # Koha is free software; you can redistribute it and/or modify it under the
   8 # terms of the GNU General Public License as published by the Free Software
   9 # Foundation; either version 3 of the License, or (at your option) any later
  10 # version.
  11 #
  12 # Koha is distributed in the hope that it will be useful, but WITHOUT ANY
  13 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  14 # A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License along
  17 # with Koha; if not, write to the Free Software Foundation, Inc.,
  18 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  19
  20 =head1 NAME
  21
  22 stockrotation.pl
  23
  24 =head1 SYNOPSIS
  25
  26     --[a]dmin-email    An address to which email reports should also be sent
  27     --[b]ranchcode     Select branch to report on for 'email' reports (default: all)
  28     --e[x]ecute        Actually perform stockrotation housekeeping
  29     --[r]eport         Select either 'full' or 'email'
  30     --[S]end-all       Send email reports even if the report body is empty
  31     --[s]end-email     Send reports by email
  32     --[h]elp           Display this help message
  33
  34 Cron script implementing scheduled stockrotation functionality.
  35
  36 By default this script merely reports on the current status of the
  37 stockrotation subsystem.  In order to actually place items in transit, the
  38 script must be run with the `execute` argument.
  39
  40 `report` allows you to select the type of report that will be emitted. It's
  41 set to 'full' by default.  If the `email` report is selected, you can use the
  42 `branchcode` parameter to specify which branch's report you would like to see.
  43 The default is 'all'.
  44
  45 `admin-email` is an additional email address to which we will send all email
  46 reports in addition to sending them to branch email addresses.
  47
  48 `send-email` will cause the script to send reports by email, and `send-all`
  49 will cause even reports with an empty body to be sent.
  50
  51 =head1 DESCRIPTION
  52
  53 This script is used to move items from one stockrotationstage to the next,
  54 if they are elible for processing.
  55
  56 it should be run from cron like:
  57
  58    stockrotation.pl --report email --send-email --execute
  59
  60 Prior to that you can run the script from the command line without the
  61 --execute and --send-email parameters to see what reports the script would
  62 generate in 'production' mode.  This is immensely useful for testing, or for
  63 getting to understand how the stockrotation module works: you can set up
  64 different scenarios, and then "query" the system on what it would do.
  65
  66 Normally you would want to run this script once per day, probably around
  67 midnight-ish to move any stockrotationitems along their rotas and to generate
  68 the email reports for branch libraries.
  69
  70 Each library will receive a report with "items of interest" for them for
  71 today's rota checks.  Each item there will be an item that should, according
  72 to Koha, be located on the shelves of that branch, and which should be picked
  73 up and checked in.  The item will either:
  74 - have been placed in transit to their new stage library;
  75 - have been placed in transit to be returned to their current stage library;
  76 - have just been added to a rota and will already be at the correct library;
  77
  78 In the last case the item will be checked in and no message will pop up.  In
  79 the other cases a message will pop up requesting the item be posted to their
  80 new branch.
  81
  82 =head2 What does the --execute flag do?
  83
  84 To understand this, you will need to know a little bit about the design of
  85 this script and the stockrotation modules.
  86
  87 This script operates in 3 phases: first it walks the graph of rotas, stages
  88 and items.  For each active rota, it investigates the items in each stage and
  89 determines whether action is required.  It does not perform any actions, it
  90 just "sieves" all items on active rotas into "actionable" and "non-actionable"
  91 baskets.  We can use these baskets to perform actions against the items, or to
  92 generate reports.
  93
  94 During the second phase this script then loops through the actionable baskets,
  95 and performs the relevant action (initiate, repatriate, advance) on each item.
  96
  97 Finally, during the third phase we revisit the original baskets and we compile
  98 reports (for instance per branch email reports).
  99
 100 When the script is run without the "--execute" flag, we perform phase 1, skip
 101 phase 2 and move straight onto phase 3.
 102
 103 With the "--execute" flag we also perform the database operations.
 104
 105 So with or without the flag, the report will look the same (except for the "No
 106 database updates have been performed.").
 107
 108 =cut
 109
 110 use Modern::Perl;
 111 use Getopt::Long qw/HelpMessage :config gnu_getopt/;
 112 use C4::Context;
 113 use C4::Letters;
 114 use Koha::StockRotationRotas;
 115
 116 my $admin_email = '';
 117 my $branch      = 0;
 118 my $execute     = 0;
 119 my $report      = 'full';
 120 my $send_all    = 0;
 121 my $send_email  = 0;
 122
 123 my $ok = GetOptions(
 124     'admin-email|a=s' => \$admin_email,
 125     'branchcode|b=s'  => sub {
 126         my ( $opt_name, $opt_value ) = @_;
 127         my $branches = Koha::Libraries->search( {},
 128             { order_by => { -asc => 'branchname' } } );
 129         my $brnch = $branches->find($opt_value);
 130         if ($brnch) {
 131             $branch = $brnch;
 132             return $brnch;
 133         }
 134         else {
 135             printf("Option $opt_name should be one of (name -> code):\n");
 136             while ( my $candidate = $branches->next ) {
 137                 printf( "  %-40s  ->  %s\n",
 138                     $candidate->branchname, $candidate->branchcode );
 139             }
 140             exit 1;
 141         }
 142     },
 143     'execute|x'  => \$execute,
 144     'report|r=s' => sub {
 145         my ( $opt_name, $opt_value ) = @_;
 146         if ( $opt_value eq 'full' || $opt_value eq 'email' ) {
 147             $report = $opt_value;
 148         }
 149         else {
 150             printf("Option $opt_name should be either 'email' or 'full'.\n");
 151             exit 1;
 152         }
 153     },
 154     'send-all|S'   => \$send_all,
 155     'send-email|s' => \$send_email,
 156     'help|h|?'     => sub { HelpMessage }
 157 );
 158 exit 1 unless ($ok);
 159
 160 $send_email++ if ($send_all);    # if we send all, then we must want emails.
 161
 162 =head2 Helpers
 163
 164 =head3 execute
 165
 166   undef = execute($report);
 167
 168 Perform the database updates, within a transaction, that are reported as
 169 needing to be performed by $REPORT.
 170
 171 $REPORT should be the return value of an invocation of `investigate`.
 172
 173 This procedure WILL mess with your database.
 174
 175 =cut
 176
 177 sub execute {
 178     my ($data) = @_;
 179
 180     # Begin transaction
 181     my $schema = Koha::Database->new->schema;
 182     $schema->storage->txn_begin;
 183
 184     # Carry out db updates
 185     foreach my $item ( @{ $data->{items} } ) {
 186         my $reason = $item->{reason};
 187         if ( $reason eq 'repatriation' ) {
 188             $item->{object}->repatriate;
 189         }
 190         elsif ( grep { $reason eq $_ } qw/in-demand advancement initiation/ ) {
 191             $item->{object}->advance;
 192         }
 193     }
 194
 195     # End transaction
 196     $schema->storage->txn_commit;
 197 }
 198
 199 =head3 report_full
 200
 201   my $full_report = report_full($report);
 202
 203 Return an arrayref containing a string containing a detailed report about the
 204 current state of the stockrotation subsystem.
 205
 206 $REPORT should be the return value of `investigate`.
 207
 208 No data in the database is manipulated by this procedure.
 209
 210 =cut
 211
 212 sub report_full {
 213     my ($data) = @_;
 214
 215     my $header = "";
 216     my $body   = "";
 217
 218     # Summary
 219     $header .= sprintf "
 220 STOCKROTATION REPORT
 221 --------------------\n";
 222     $body .= sprintf "
 223   Total number of rotas:         %5u
 224     Inactive rotas:              %5u
 225     Active rotas:                %5u
 226   Total number of items:         %5u
 227     Inactive items:              %5u
 228     Stationary items:            %5u
 229     Actionable items:            %5u
 230   Total items to be initiated:   %5u
 231   Total items to be repatriated: %5u
 232   Total items to be advanced:    %5u
 233   Total items in demand:         %5u\n\n",
 234       $data->{sum_rotas},  $data->{rotas_inactive}, $data->{rotas_active},
 235       $data->{sum_items},  $data->{items_inactive}, $data->{stationary},
 236       $data->{actionable}, $data->{initiable},      $data->{repatriable},
 237       $data->{advanceable}, $data->{indemand};
 238
 239     if ( @{ $data->{rotas} } ) {    # Per Rota details
 240         $body .= sprintf "ROTAS DETAIL\n------------\n\n";
 241         foreach my $rota ( @{ $data->{rotas} } ) {
 242             $body .= sprintf "Details for %s [%s]:\n",
 243               $rota->{name}, $rota->{id};
 244             $body .= sprintf "\n  Items:";    # Rota item details
 245             if ( @{ $rota->{items} } ) {
 246                 $body .=
 247                   join( "", map { _print_item($_) } @{ $rota->{items} } );
 248             }
 249             else {
 250                 $body .=
 251                   sprintf "\n    No items to be processed for this rota.\n";
 252             }
 253             $body .= sprintf "\n  Log:";      # Rota log details
 254             if ( @{ $rota->{log} } ) {
 255                 $body .= join( "", map { _print_item($_) } @{ $rota->{log} } );
 256             }
 257             else {
 258                 $body .= sprintf "\n    No items in log for this rota.\n\n";
 259             }
 260         }
 261     }
 262     return [
 263         $header,
 264         {
 265             letter => {
 266                 title   => 'Stockrotation Report',
 267                 content => $body                     # The body of the report
 268             },
 269             status          => 1,    # We have a meaningful report
 270             no_branch_email => 1,    # We don't expect branch email in report
 271         }
 272     ];
 273 }
 274
 275 =head3 report_email
 276
 277   my $email_report = report_email($report);
 278
 279 Returns an arrayref containing a header string, with basic report information,
 280 and any number of 'per_branch' strings, containing a detailed report about the
 281 current state of the stockrotation subsystem, from the perspective of those
 282 individual branches.
 283
 284 $REPORT should be the return value of `investigate`, and $BRANCH should be
 285 either 0 (to indicate 'all'), or a specific Koha::Library object.
 286
 287 No data in the database is manipulated by this procedure.
 288
 289 =cut
 290
 291 sub report_email {
 292     my ( $data, $branch ) = @_;
 293
 294     my $out    = [];
 295     my $header = "";
 296
 297     # Summary
 298     my $branched = $data->{branched};
 299     my $flag     = 0;
 300
 301     $header .= sprintf "
 302 BRANCH-BASED STOCKROTATION REPORT
 303 ---------------------------------\n";
 304     push @{$out}, $header;
 305
 306     if ($branch) {    # Branch limited report
 307         push @{$out}, _report_per_branch( $branched->{ $branch->branchcode } );
 308     }
 309     elsif ( $data->{actionable} ) {    # Full email report
 310         while ( my ( $branchcode_id, $details ) = each %{$branched} ) {
 311             push @{$out}, _report_per_branch($details)
 312               if ( @{ $details->{items} } );
 313         }
 314     }
 315     else {
 316         push @{$out}, {
 317             body => sprintf "
 318 No actionable items at any libraries.\n\n",    # The body of the report
 319             no_branch_email => 1,    # We don't expect branch email in report
 320         };
 321     }
 322     return $out;
 323 }
 324
 325 =head3 _report_per_branch
 326
 327   my $branch_string = _report_per_branch($branch_details, $branchcode, $branchname);
 328
 329 return a string containing details about the stockrotation items and their
 330 status for the branch identified by $BRANCHCODE.
 331
 332 This helper procedure is only used from within `report_email`.
 333
 334 No data in the database is manipulated by this procedure.
 335
 336 =cut
 337
 338 sub _report_per_branch {
 339     my ($branch) = @_;
 340
 341     my $status = 0;
 342     if ( $branch && @{ $branch->{items} } ) {
 343         $status = 1;
 344     }
 345
 346     if (
 347         my $letter = C4::Letters::GetPreparedLetter(
 348             module                 => 'circulation',
 349             letter_code            => "SR_SLIP",
 350             message_transport_type => 'email',
 351             substitute             => $branch
 352         )
 353       )
 354     {
 355         return {
 356             letter        => $letter,
 357             email_address => $branch->{email},
 358             $status
 359         };
 360     }
 361     return;
 362 }
 363
 364 =head3 _print_item
 365
 366   my $string = _print_item($item_section);
 367
 368 Return a string containing an overview about $ITEM_SECTION.
 369
 370 This helper procedure is only used from within `report_full`.
 371
 372 No data in the database is manipulated by this procedure.
 373
 374 =cut
 375
 376 sub _print_item {
 377     my ($item) = @_;
 378     return sprintf "
 379     Title:           %s
 380     Author:          %s
 381     Callnumber:      %s
 382     Location:        %s
 383     Barcode:         %s
 384     On loan?:        %s
 385     Status:          %s
 386     Current Library: %s [%s]\n\n",
 387       $item->{title}      || "N/A", $item->{author}   || "N/A",
 388       $item->{callnumber} || "N/A", $item->{location} || "N/A",
 389       $item->{barcode} || "N/A", $item->{onloan} ? 'Yes' : 'No',
 390       $item->{reason} || "N/A", $item->{branch}->branchname,
 391       $item->{branch}->branchcode;
 392 }
 393
 394 =head3 emit
 395
 396   undef = emit($params);
 397
 398 $PARAMS should be a hashref of the following format:
 399   admin_email: the address to which a copy of all reports should be sent.
 400   execute: the flag indicating whether we performed db updates
 401   send_all: the flag indicating whether we should send even empty reports
 402   send_email: the flag indicating whether we want to emit to stdout or email
 403   report: the data structure returned from one of the report procedures
 404
 405 No data in the database is manipulated by this procedure.
 406
 407 The return value is unspecified: we simply emit a message as a side-effect or
 408 die.
 409
 410 =cut
 411
 412 sub emit {
 413     my ($params) = @_;
 414
 415 # REPORT is an arrayref of at least 2 elements:
 416 #   - The header for the report, which will be repeated for each part
 417 #   - a "part" for each report we want to emit
 418 # PARTS are hashrefs:
 419 #   - part->{status}: a boolean indicating whether the reported part is empty or not
 420 #   - part->{email_address}: the email address to send the report to
 421 #   - part->{no_branch_email}: a boolean indicating that we are missing a branch email
 422 #   - part->{letter}: a GetPreparedLetter hash as returned by the C4::Letters module
 423     my $report = $params->{report};
 424     my $header = shift @{$report};
 425     my $parts  = $report;
 426
 427     my @emails;
 428     foreach my $part ( @{$parts} ) {
 429
 430         if ( $part->{status} || $params->{send_all} ) {
 431
 432             # We have a report to send, or we want to send even empty
 433             # reports.
 434
 435             # Send to branch
 436             my $addressee;
 437             if ( $part->{email_address} ) {
 438                 $addressee = $part->{email_address};
 439             }
 440             elsif ( !$part->{no_branch_email} ) {
 441
 442 #push @emails, "***We tried to send a branch report, but we have no email address for this branch.***\n\n";
 443                 $addressee = C4::Context->preference('KohaAdminEmailAddress')
 444                   if ( C4::Context->preference('KohaAdminEmailAddress') );
 445             }
 446
 447             if ( $params->{send_email} ) {    # Only email if emails requested
 448                 if ( defined($addressee) ) {
 449                     C4::Letters::EnqueueLetter(
 450                         {
 451                             letter                 => $part->{letter},
 452                             to_address             => $addressee,
 453                             message_transport_type => 'email',
 454                         }
 455                       )
 456                       or warn
 457                       "can't enqueue letter $part->{letter} for $addressee";
 458                 }
 459
 460                 # Copy to admin?
 461                 if ( $params->{admin_email} ) {
 462                     C4::Letters::EnqueueLetter(
 463                         {
 464                             letter                 => $part->{letter},
 465                             to_address             => $params->{admin_email},
 466                             message_transport_type => 'email',
 467                         }
 468                       )
 469                       or warn
 470 "can't enqueue letter $part->{letter} for $params->{admin_email}";
 471                 }
 472             }
 473             else {
 474                 my $email =
 475                   "-------- Email message --------" . "\n\n" . "To: "
 476                   . defined($addressee)               ? $addressee
 477                   : defined( $params->{admin_email} ) ? $params->{admin_email}
 478                   : '' . "\n"
 479                   . "Subject: "
 480                   . $part->{letter}->{title} . "\n\n"
 481                   . $part->{letter}->{content};
 482                 push @emails, $email;
 483             }
 484         }
 485     }
 486
 487     # Emit to stdout instead of email?
 488     if ( !$params->{send_email} ) {
 489
 490         # The final message is the header + body of this part.
 491         my $msg = $header;
 492         $msg .= "No database updates have been performed.\n\n"
 493           unless ( $params->{execute} );
 494
 495         # Append email reports to message
 496         $msg .= join( "\n\n", @emails );
 497         printf $msg;
 498     }
 499 }
 500
 501 #### Main Code
 502
 503 # Compile Stockrotation Report data
 504 my $rotas = Koha::StockRotationRotas->search(undef,{ order_by => { '-asc' => 'title' }});
 505 my $data  = $rotas->investigate;
 506
 507 # Perform db updates if requested
 508 execute($data) if ($execute);
 509
 510 # Emit Reports
 511 my $out_report = {};
 512 $out_report = report_email( $data, $branch ) if $report eq 'email';
 513 $out_report = report_full( $data, $branch ) if $report eq 'full';
 514 emit(
 515     {
 516         admin_email => $admin_email,
 517         execute     => $execute,
 518         report      => $out_report,
 519         send_all    => $send_all,
 520         send_email  => $send_email,
 521     }
 522 );
 523
 524 =head1 AUTHOR
 525
 526 Alex Sassmannshausen <alex.sassmannshausen@ptfs-europe.com>
 527
 528 =cut