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 Getopt::Long qw( GetOptions );
22 use Pod::Usage qw( pod2usage );
25 use Koha::Patron::Categories;
26 use Koha::DateUtils qw( dt_from_string );
27 use Koha::Script -cron;
31 update_patrons_category.pl - Given a set of parameters update selected patrons from one catgeory to another. Options are cumulative.
35 update_patrons_category.pl -f=categorycode -t=categorycode
36 [-b=branchcode] [--too_old] [--too_young] [-fo=X] [-fu=X]
37 [-rb=date] [-ra=date] [-v]
38 [--field column=value ...]
40 update_patrons_category.pl --help | --man
44 --help brief help message
45 --man full documentation
46 -too_old update if over maximum age for current category
47 -too_young update if under minimuum age current category
48 -fo=X --fineover=X update if fines over X amount
49 -fu=X --fineunder=X update if fines under X amount
50 -rb=date --regbefore update if registration date is before given date
51 -ra=date --regafter update if registration date is after a given date
52 -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>
53 --where <conditions> where clause to add to the query
54 -v -verbose verbose mode
55 -c --confirm commit changes to db, no action will be taken unless this switch is included
56 -b --branch <branchname> only deal with patrons from this library/branch
57 -f --from <categorycode> change patron category from this category
58 -t --to <categorycode> change patron category to this category
66 Print a brief help message and exits.
70 Prints the manual page and exits.
72 =item B<--verbose | -v>
74 Verbose. Without this flag set, only fatal errors are reported.
76 =item B<--confirm | -c>
78 Commit changes. Unless this flag set is, the script will report changes but not actually execute them on the database.
80 =item B<--branch | -b>
82 changes patrons for one specific branch. Use the value in the
83 branches.branchcode table.
87 *required* defines the category to update. Expects the code from categories.categorycode.
91 *required* defines the category patrons will be converted to. Expects the code from categories.categorycode.
95 Update patron only if they are above the maximum age range specified for the 'from' category.
99 Update patron only if they are below the minimum age range specified for the 'from' category.
101 =item B<--fineover=X | -fo=X>
103 Supply a number and only account with fines over this number will be updated.
105 =item B<--fineunder=X | -fu=X>
107 Supply a number and only account with fines under this number will be updated.
109 =item B<--regbefore=date | -rb=date>
111 Enter a date in ISO format YYYY-MM-DD and only patrons registered before this date wil be updated.
113 =item B<--regafter=date | -ra=date>
115 Enter a date in ISO format YYYY-MM-DD and only patrons registered after this date wil be updated.
117 =item B<--field column=value | -d column=value>
119 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)
120 A value of null will check for a field that is not set.
123 --field dateexpiry=2016-01-01
124 will update all patrons who expired on that date, useful for schools etc.
126 =item B<--where $conditions>
128 Use this option to specify a condition built with columns from the borrowers table
131 --where 'email IS NULL'
132 will update all patrons with no value for email
138 This script is designed to update patrons from one category to another.
140 =head1 USAGE EXAMPLES
142 C<update_patron_categories.pl> - Suggests that you read this help. :)
144 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.
146 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.
148 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.
152 # These variables are set by command line options.
153 # They are initially set to default values.
161 my $remove_guarantors = 0;
175 'v|verbose' => \$verbose,
176 'c|confirm' => \$doit,
177 'f|from=s' => \$fromcat,
179 'too_old' => \$ageover,
180 'too_young' => \$ageunder,
181 'fo|finesover=s' => \$fine_min,
182 'fu|finesunder=s' => \$fine_max,
183 'rb|regbefore=s' => \$reg_bef,
184 'ra|regafter=s' => \$reg_aft,
185 'b|branch=s' => \$branch_lim,
186 'd|field=s' => \%fields,
187 'where=s' => \@where,
190 pod2usage(1) if $help;
192 pod2usage( -verbose => 2 ) if $man;
194 if ( not $fromcat && $tocat ) { #make sure we've specified the info we need.
195 print "Must supply category from and to (-f & -t) please specify -help for usage tips.\n";
200 ( $verbose && !$doit ) and print "No actions will be taken (test mode)\n";
202 $verbose and print "Will update patrons from $fromcat to $tocat with conditions below (if any)\n";
206 if ( $reg_bef || $reg_aft ) {
209 if ( defined $reg_bef ) {
210 eval { $date_bef = dt_from_string( $reg_bef, 'iso' ); };
212 die "$reg_bef is not a valid date before, aborting! Use a date in format YYYY-MM-DD.$@"
214 if ( defined $reg_aft ) {
215 eval { $date_aft = dt_from_string( $reg_aft, 'iso' ); };
217 die "$reg_bef is not a valid date after, aborting! Use a date in format YYYY-MM-DD.$@"
219 $params{dateenrolled}{'<='} = $reg_bef if defined $date_bef;
220 $params{dateenrolled}{'>='} = $reg_aft if defined $date_aft;
223 my $cat_from = Koha::Patron::Categories->find($fromcat);
224 my $cat_to = Koha::Patron::Categories->find($tocat);
225 die "Categories not found" unless $cat_from && $cat_to;
227 $params{"me.categorycode"} = $fromcat;
228 $params{"me.branchcode"} = $branch_lim if $branch_lim;
231 print "Conditions:\n";
232 print " Registered before $reg_bef\n" if $reg_bef;
233 print " Registered after $reg_aft\n" if $reg_aft;
234 print " Total fines more than $fine_min\n" if $fine_min;
235 print " Total fines less than $fine_max\n" if $fine_max;
236 print " Age below minimum for " . $cat_from->description . "\n" if $ageunder;
237 print " Age above maximum for " . $cat_from->description . "\n" if $ageover;
238 if ( defined $branch_lim ) {
239 print " Branchcode of patron is $branch_lim\n";
243 while ( my ( $key, $value ) = each %fields ) {
244 $verbose and print " Borrower column $key is $value\n";
245 $value = undef if lc($value) eq 'null';
246 $params{ "me." . $key } = $value;
249 my $where_literal = join ' AND ', @where;
250 my $target_patrons = Koha::Patrons->search( \%params );
251 $target_patrons = $target_patrons->search( \$where_literal ) if @where;
252 $target_patrons = $target_patrons->search_patrons_to_update_category(
255 search_params => \%params,
256 too_young => $ageunder,
258 fine_min => $fine_min,
259 fine_max => $fine_max,
263 my $patrons_found = $target_patrons->count;
264 my $actually_updated = 0;
265 my $testdisplay = $doit ? "" : "WOULD HAVE ";
267 while ( my $target_patron = $target_patrons->next() ) {
268 $target_patron->discard_changes();
270 and print $testdisplay
272 . $target_patron->firstname() . " "
273 . $target_patron->surname()
274 . " from $fromcat to $tocat\n";
276 $target_patrons->reset;
279 $actually_updated = $target_patrons->update_category_to( { category => $tocat } );
282 $verbose and print "$patrons_found found, $actually_updated updated\n";