3 # This file is part of Koha.
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.
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.
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>.
21 use C4::Log qw(cronlogaction);
22 use Getopt::Long qw( GetOptions );
23 use Pod::Usage qw( pod2usage );
26 use Koha::Patron::Categories;
27 use Koha::DateUtils qw( dt_from_string );
28 use Koha::Script -cron;
32 update_patrons_category.pl - Given a set of parameters update selected patrons from one catgeory to another. Options are cumulative.
36 update_patrons_category.pl -f=categorycode -t=categorycode
37 [-b=branchcode] [--too_old] [--too_young] [-fo=X] [-fu=X]
38 [-rb=date] [-ra=date] [-v]
39 [--field column=value ...]
41 update_patrons_category.pl --help | --man
45 --help brief help message
46 --man full documentation
47 -too_old update if over maximum age for current category
48 -too_young update if under minimuum age current category
49 -fo=X --finesover=X update if fines over X amount
50 -fu=X --finesunder=X update if fines under X amount
51 -rb=date --regbefore update if registration date is before given date
52 -ra=date --regafter update if registration date is after a given date
53 -d --field name=value where <name> is a column in the borrowers table, patrons will be updated if the field is equal to given <value>
54 --where <conditions> where clause to add to the query
55 -v -verbose verbose mode
56 -c --confirm commit changes to db, no action will be taken unless this switch is included
57 -b --branch <branchname> only deal with patrons from this library/branch
58 -f --from <categorycode> change patron category from this category
59 -t --to <categorycode> change patron category to this category
67 Print a brief help message and exits.
71 Prints the manual page and exits.
73 =item B<--verbose | -v>
75 Verbose. Without this flag set, only fatal errors are reported.
77 =item B<--confirm | -c>
79 Commit changes. Unless this flag set is, the script will report changes but not actually execute them on the database.
81 =item B<--branch | -b>
83 Changes patrons for one specific branch. Use the value in the
84 branches.branchcode table.
88 *Required* Defines the category to update. Expects the code from categories.categorycode.
92 *Required* Defines the category patrons will be converted to. Expects the code from categories.categorycode.
96 Update patron only if they are above the maximum age range specified for the 'from' category.
100 Update patron only if they are below the minimum age range specified for the 'from' category.
102 =item B<--finesover=X | -fo=X>
104 Supply a number and only account with fines over this number will be updated.
106 =item B<--finesunder=X | -fu=X>
108 Supply a number and only account with fines under this number will be updated.
110 =item B<--regbefore=date | -rb=date>
112 Enter a date in ISO format YYYY-MM-DD and only patrons registered before this date wil be updated.
114 =item B<--regafter=date | -ra=date>
116 Enter a date in ISO format YYYY-MM-DD and only patrons registered after this date wil be updated.
118 =item B<--field column=value | -d column=value>
120 Use this flag to specify a column in the borrowers table and update only patrons whose value in that column equals the value supplied (repeatable)
121 A value of null will check for a field that is not set.
124 --field dateexpiry=2016-01-01
125 will update all patrons who expired on that date, useful for schools etc.
127 =item B<--where $conditions>
129 Use this option to specify a condition built with columns from the borrowers table
132 --where 'email IS NULL'
133 will update all patrons with no value for email
139 This script is designed to update patrons from one category to another.
141 =head1 USAGE EXAMPLES
143 C<update_patron_categories.pl> - Suggests that you read this help. :)
145 C<update_patron_categories.pl> -b=<branchcode> -f=<categorycode> -t=<categorycode> --confirm - Processes a single branch, and updates the patron categories from fromcat to tocat.
147 C<update_patron_categories.pl> -b=<branchcode> -f=<categorycode> -t=<categorycode> --too_old --confirm - Processes a single branch, and updates the patron categories from fromcat to tocat for patrons over the age range of fromcat.
149 C<update_patron_categories.pl> -f=<categorycode> -t=<categorycode> -v - Processes all branches, shows all messages, and reports the patrons who would be affected. Takes no action on the database.
153 # These variables are set by command line options.
154 # They are initially set to default values.
162 my $remove_guarantors = 0;
176 'v|verbose' => \$verbose,
177 'c|confirm' => \$doit,
178 'f|from=s' => \$fromcat,
180 'too_old' => \$ageover,
181 'too_young' => \$ageunder,
182 'fo|finesover=s' => \$fine_min,
183 'fu|finesunder=s' => \$fine_max,
184 'rb|regbefore=s' => \$reg_bef,
185 'ra|regafter=s' => \$reg_aft,
186 'b|branch=s' => \$branch_lim,
187 'd|field=s' => \%fields,
188 'where=s' => \@where,
191 pod2usage(1) if $help;
193 pod2usage( -verbose => 2 ) if $man;
195 if ( not $fromcat && $tocat ) { #make sure we've specified the info we need.
196 print "Must supply category from and to (-f & -t) please specify -help for usage tips.\n";
201 ( $verbose && !$doit ) and print "No actions will be taken (test mode)\n";
203 $verbose and print "Will update patrons from $fromcat to $tocat with conditions below (if any)\n";
209 if ( $reg_bef || $reg_aft ) {
212 if ( defined $reg_bef ) {
213 eval { $date_bef = dt_from_string( $reg_bef, 'iso' ); };
215 die "$reg_bef is not a valid date before, aborting! Use a date in format YYYY-MM-DD.$@"
217 if ( defined $reg_aft ) {
218 eval { $date_aft = dt_from_string( $reg_aft, 'iso' ); };
220 die "$reg_bef is not a valid date after, aborting! Use a date in format YYYY-MM-DD.$@"
222 $params{dateenrolled}{'<='} = $reg_bef if defined $date_bef;
223 $params{dateenrolled}{'>='} = $reg_aft if defined $date_aft;
226 my $cat_from = Koha::Patron::Categories->find($fromcat);
227 my $cat_to = Koha::Patron::Categories->find($tocat);
228 die "Categories not found" unless $cat_from && $cat_to;
230 $params{"me.categorycode"} = $fromcat;
231 $params{"me.branchcode"} = $branch_lim if $branch_lim;
234 print "Conditions:\n";
235 print " Registered before $reg_bef\n" if $reg_bef;
236 print " Registered after $reg_aft\n" if $reg_aft;
237 print " Total fines more than $fine_min\n" if $fine_min;
238 print " Total fines less than $fine_max\n" if $fine_max;
239 print " Age below minimum for " . $cat_from->description . "\n" if $ageunder;
240 print " Age above maximum for " . $cat_from->description . "\n" if $ageover;
241 if ( defined $branch_lim ) {
242 print " Branchcode of patron is $branch_lim\n";
246 while ( my ( $key, $value ) = each %fields ) {
247 $verbose and print " Borrower column $key is $value\n";
248 $value = undef if lc($value) eq 'null';
249 $params{ "me." . $key } = $value;
252 my $where_literal = join ' AND ', @where;
253 my $target_patrons = Koha::Patrons->search( \%params );
254 $target_patrons = $target_patrons->search( \$where_literal ) if @where;
255 $target_patrons = $target_patrons->search_patrons_to_update_category(
258 search_params => \%params,
259 too_young => $ageunder,
261 fine_min => $fine_min,
262 fine_max => $fine_max,
266 my $patrons_found = $target_patrons->count;
267 my $actually_updated = 0;
268 my $testdisplay = $doit ? "" : "WOULD HAVE ";
270 while ( my $target_patron = $target_patrons->next() ) {
271 $target_patron->discard_changes();
273 and print $testdisplay
275 . $target_patron->firstname() . " "
276 . $target_patron->surname()
277 . " from $fromcat to $tocat\n";
279 $target_patrons->reset;
282 $actually_updated = $target_patrons->update_category_to( { category => $tocat } );
285 $verbose and print "$patrons_found found, $actually_updated updated\n";