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 --finesover=X update if fines over X amount
56 -fu=X --finesunder=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<--finesover=X | -fo=X>
110 Supply a number and only account with fines over this number will be updated.
112 =item B<--finesunder=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
145 This script is designed to update patrons from one category to another.
147 =head1 USAGE EXAMPLES
149 C<update_patron_categories.pl> - Suggests that you read this help. :)
151 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.
153 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.
155 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.
159 # These variables are set by command line options.
160 # They are initially set to default values.
168 my $remove_guarantors = 0;
182 'v|verbose' => \$verbose,
183 'c|confirm' => \$doit,
184 'f|from=s' => \$fromcat,
186 'too_old' => \$ageover,
187 'too_young' => \$ageunder,
188 'fo|finesover=s' => \$fine_min,
189 'fu|finesunder=s' => \$fine_max,
190 'rb|regbefore=s' => \$reg_bef,
191 'ra|regafter=s' => \$reg_aft,
192 'b|branch=s' => \$branch_lim,
193 'd|field=s' => \%fields,
194 'where=s' => \@where,
197 pod2usage(1) if $help;
199 pod2usage( -verbose => 2 ) if $man;
201 if ( not $fromcat && $tocat ) { #make sure we've specified the info we need.
202 print "Must supply category from and to (-f & -t) please specify -help for usage tips.\n";
207 ( $verbose && !$doit ) and print "No actions will be taken (test mode)\n";
209 $verbose and print "Will update patrons from $fromcat to $tocat with conditions below (if any)\n";
213 if ( $reg_bef || $reg_aft ) {
216 if ( defined $reg_bef ) {
217 eval { $date_bef = dt_from_string( $reg_bef, 'iso' ); };
219 die "$reg_bef is not a valid date before, aborting! Use a date in format YYYY-MM-DD.$@"
221 if ( defined $reg_aft ) {
222 eval { $date_aft = dt_from_string( $reg_aft, 'iso' ); };
224 die "$reg_bef is not a valid date after, aborting! Use a date in format YYYY-MM-DD.$@"
226 $params{dateenrolled}{'<='} = $reg_bef if defined $date_bef;
227 $params{dateenrolled}{'>='} = $reg_aft if defined $date_aft;
230 my $cat_from = Koha::Patron::Categories->find($fromcat);
231 my $cat_to = Koha::Patron::Categories->find($tocat);
232 die "Categories not found" unless $cat_from && $cat_to;
234 $params{"me.categorycode"} = $fromcat;
235 $params{"me.branchcode"} = $branch_lim if $branch_lim;
238 print "Conditions:\n";
239 print " Registered before $reg_bef\n" if $reg_bef;
240 print " Registered after $reg_aft\n" if $reg_aft;
241 print " Total fines more than $fine_min\n" if $fine_min;
242 print " Total fines less than $fine_max\n" if $fine_max;
243 print " Age below minimum for " . $cat_from->description . "\n" if $ageunder;
244 print " Age above maximum for " . $cat_from->description . "\n" if $ageover;
245 if ( defined $branch_lim ) {
246 print " Branchcode of patron is $branch_lim\n";
250 while ( my ( $key, $value ) = each %fields ) {
251 $verbose and print " Borrower column $key is $value\n";
252 $value = undef if lc($value) eq 'null';
253 $params{ "me." . $key } = $value;
256 my $where_literal = join ' AND ', @where;
257 my $target_patrons = Koha::Patrons->search( \%params );
258 $target_patrons = $target_patrons->search( \$where_literal ) if @where;
259 $target_patrons = $target_patrons->search_patrons_to_update_category(
262 search_params => \%params,
263 too_young => $ageunder,
265 fine_min => $fine_min,
266 fine_max => $fine_max,
270 my $patrons_found = $target_patrons->count;
271 my $actually_updated = 0;
272 my $testdisplay = $doit ? "" : "WOULD HAVE ";
274 while ( my $target_patron = $target_patrons->next() ) {
275 $target_patron->discard_changes();
277 and print $testdisplay
279 . $target_patron->firstname() . " "
280 . $target_patron->surname()
281 . " from $fromcat to $tocat\n";
283 $target_patrons->reset;
286 $actually_updated = $target_patrons->update_category_to( { category => $tocat } );
289 $verbose and print "$patrons_found found, $actually_updated updated\n";