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 # find Koha's Perl modules
22 # test carefully before changing this
24 eval { require "$FindBin::Bin/../kohalib.pl" };
28 use Getopt::Long qw( GetOptions );
29 use Pod::Usage qw( pod2usage );
32 use Koha::Patron::Categories;
33 use Koha::DateUtils qw( dt_from_string );
34 use Koha::Script -cron;
38 update_patrons_category.pl - Given a set of parameters update selected patrons from one catgeory to another. Options are cumulative.
42 update_patrons_category.pl -f=categorycode -t=categorycode
43 [-b=branchcode] [--too_old] [--too_young] [-fo=X] [-fu=X]
44 [-rb=date] [-ra=date] [-v]
45 [--field column=value ...]
47 update_patrons_category.pl --help | --man
51 --help brief help message
52 --man full documentation
53 -too_old update if over maximum age for current category
54 -too_young update if under minimuum age current category
55 -fo=X --fineover=X update if fines over X amount
56 -fu=X --fineunder=X update if fines under X amount
57 -rb=date --regbefore update if registration date is before given date
58 -ra=date --regafter update if registration date is after a given date
59 -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>
60 --where <conditions> where clause to add to the query
61 -v -verbose verbose mode
62 -c --confirm commit changes to db, no action will be taken unless this switch is included
63 -b --branch <branchname> only deal with patrons from this library/branch
64 -f --from <categorycode> change patron category from this category
65 -t --to <categorycode> change patron category to this category
73 Print a brief help message and exits.
77 Prints the manual page and exits.
79 =item B<--verbose | -v>
81 Verbose. Without this flag set, only fatal errors are reported.
83 =item B<--confirm | -c>
85 Commit changes. Unless this flag set is, the script will report changes but not actually execute them on the database.
87 =item B<--branch | -b>
89 changes patrons for one specific branch. Use the value in the
90 branches.branchcode table.
94 *required* defines the category to update. Expects the code from categories.categorycode.
98 *required* defines the category patrons will be converted to. Expects the code from categories.categorycode.
102 Update patron only if they are above the maximum age range specified for the 'from' category.
106 Update patron only if they are below the minimum age range specified for the 'from' category.
108 =item B<--fineover=X | -fo=X>
110 Supply a number and only account with fines over this number will be updated.
112 =item B<--fineunder=X | -fu=X>
114 Supply a number and only account with fines under this number will be updated.
116 =item B<--regbefore=date | -rb=date>
118 Enter a date in ISO format YYYY-MM-DD and only patrons registered before this date wil be updated.
120 =item B<--regafter=date | -ra=date>
122 Enter a date in ISO format YYYY-MM-DD and only patrons registered after this date wil be updated.
124 =item B<--field column=value | -d column=value>
126 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)
127 A value of null will check for a field that is not set.
130 --field dateexpiry=2016-01-01
131 will update all patrons who expired on that date, useful for schools etc.
133 =item B<--where $conditions>
135 Use this option to specify a condition built with columns from the borrowers table
138 --where 'email IS NULL'
139 will update all patrons with no value for email
141 --where 'categorycode LIKE "%CHILD"'
142 will update all patrons with a category ending in CHILD.
144 --where 'categorycode LIKE RESIDENT%'
145 will update all patrons whose category does not begin with RESIDENT.
151 This script is designed to update patrons from one category to another.
153 =head1 USAGE EXAMPLES
155 C<update_patron_categories.pl> - Suggests that you read this help. :)
157 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.
159 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.
161 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.
165 # These variables are set by command line options.
166 # They are initially set to default values.
174 my $remove_guarantors = 0;
188 'v|verbose' => \$verbose,
189 'c|confirm' => \$doit,
190 'f|from=s' => \$fromcat,
192 'too_old' => \$ageover,
193 'too_young' => \$ageunder,
194 'fo|finesover=s' => \$fine_min,
195 'fu|finesunder=s' => \$fine_max,
196 'rb|regbefore=s' => \$reg_bef,
197 'ra|regafter=s' => \$reg_aft,
198 'b|branch=s' => \$branch_lim,
199 'd|field=s' => \%fields,
200 'where=s' => \@where,
203 pod2usage(1) if $help;
205 pod2usage( -verbose => 2 ) if $man;
207 if ( not $fromcat && $tocat ) { #make sure we've specified the info we need.
208 print "Must supply category from and to (-f & -t) please specify -help for usage tips.\n";
213 ( $verbose && !$doit ) and print "No actions will be taken (test mode)\n";
215 $verbose and print "Will update patrons from $fromcat to $tocat with conditions below (if any)\n";
219 if ( $reg_bef || $reg_aft ) {
222 if ( defined $reg_bef ) {
223 eval { $date_bef = dt_from_string( $reg_bef, 'iso' ); };
225 die "$reg_bef is not a valid date before, aborting! Use a date in format YYYY-MM-DD.$@"
227 if ( defined $reg_aft ) {
228 eval { $date_aft = dt_from_string( $reg_aft, 'iso' ); };
230 die "$reg_bef is not a valid date after, aborting! Use a date in format YYYY-MM-DD.$@"
232 $params{dateenrolled}{'<='} = $reg_bef if defined $date_bef;
233 $params{dateenrolled}{'>='} = $reg_aft if defined $date_aft;
236 my $cat_from = Koha::Patron::Categories->find($fromcat);
237 my $cat_to = Koha::Patron::Categories->find($tocat);
238 die "Categories not found" unless $cat_from && $cat_to;
240 $params{"me.categorycode"} = $fromcat;
241 $params{"me.branchcode"} = $branch_lim if $branch_lim;
244 print "Conditions:\n";
245 print " Registered before $reg_bef\n" if $reg_bef;
246 print " Registered after $reg_aft\n" if $reg_aft;
247 print " Total fines more than $fine_min\n" if $fine_min;
248 print " Total fines less than $fine_max\n" if $fine_max;
249 print " Age below minimum for " . $cat_from->description . "\n" if $ageunder;
250 print " Age above maximum for " . $cat_from->description . "\n" if $ageover;
251 if ( defined $branch_lim ) {
252 print " Branchcode of patron is $branch_lim\n";
256 while ( my ( $key, $value ) = each %fields ) {
257 $verbose and print " Borrower column $key is $value\n";
258 $value = undef if lc($value) eq 'null';
259 $params{ "me." . $key } = $value;
262 my $where_literal = join ' AND ', @where;
263 my $target_patrons = Koha::Patrons->search( \%params );
264 $target_patrons = $target_patrons->search( \$where_literal ) if @where;
265 $target_patrons = $target_patrons->search_patrons_to_update_category(
268 search_params => \%params,
269 too_young => $ageunder,
271 fine_min => $fine_min,
272 fine_max => $fine_max,
276 my $patrons_found = $target_patrons->count;
277 my $actually_updated = 0;
278 my $testdisplay = $doit ? "" : "WOULD HAVE ";
280 while ( my $target_patron = $target_patrons->next() ) {
281 $target_patron->discard_changes();
283 and print $testdisplay
285 . $target_patron->firstname() . " "
286 . $target_patron->surname()
287 . " from $fromcat to $tocat\n";
289 $target_patrons->reset;
292 $actually_updated = $target_patrons->update_category_to( { category => $tocat } );
295 $verbose and print "$patrons_found found, $actually_updated updated\n";