FS/FS/cust_location.pm

   1 package FS::cust_location;
   2 use base qw( FS::geocode_Mixin FS::Record );
   3
   4 use strict;
   5 use vars qw( $import $DEBUG $conf $label_prefix $allow_location_edit );
   6 use Data::Dumper;
   7 use Date::Format qw( time2str );
   8 use FS::UID qw( dbh driver_name );
   9 use FS::Record qw( qsearch qsearchs );
  10 use FS::Conf;
  11 use FS::prospect_main;
  12 use FS::cust_main;
  13 use FS::cust_main_county;
  14 use FS::part_export;
  15 use FS::GeocodeCache;
  16
  17 # Essential fields. Can't be modified in place, will be considered in
  18 # deciding if a location is "new", and (because of that) can't have
  19 # leading/trailing whitespace.
  20 my @essential = (qw(custnum address1 address2 city county state zip country
  21   location_number location_type location_kind disabled));
  22
  23 $import = 0;
  24
  25 $DEBUG = 0;
  26
  27 FS::UID->install_callback( sub {
  28   $conf = FS::Conf->new;
  29   $label_prefix = $conf->config('cust_location-label_prefix') || '';
  30 });
  31
  32 =head1 NAME
  33
  34 FS::cust_location - Object methods for cust_location records
  35
  36 =head1 SYNOPSIS
  37
  38   use FS::cust_location;
  39
  40   $record = new FS::cust_location \%hash;
  41   $record = new FS::cust_location { 'column' => 'value' };
  42
  43   $error = $record->insert;
  44
  45   $error = $new_record->replace($old_record);
  46
  47   $error = $record->delete;
  48
  49   $error = $record->check;
  50
  51 =head1 DESCRIPTION
  52
  53 An FS::cust_location object represents a customer location.  FS::cust_location
  54 inherits from FS::Record.  The following fields are currently supported:
  55
  56 =over 4
  57
  58 =item locationnum
  59
  60 primary key
  61
  62 =item custnum
  63
  64 custnum
  65
  66 =item address1
  67
  68 Address line one (required)
  69
  70 =item address2
  71
  72 Address line two (optional)
  73
  74 =item city
  75
  76 City (if cust_main-no_city_in_address config is set when inserting, this will be forced blank)
  77
  78 =item county
  79
  80 County (optional, see L<FS::cust_main_county>)
  81
  82 =item state
  83
  84 State (see L<FS::cust_main_county>)
  85
  86 =item zip
  87
  88 Zip
  89
  90 =item country
  91
  92 Country (see L<FS::cust_main_county>)
  93
  94 =item geocode
  95
  96 Geocode
  97
  98 =item district
  99
 100 Tax district code (optional)
 101
 102 =item disabled
 103
 104 Disabled flag; set to 'Y' to disable the location.
 105
 106 =back
 107
 108 =head1 METHODS
 109
 110 =over 4
 111
 112 =item new HASHREF
 113
 114 Creates a new location.  To add the location to the database, see L<"insert">.
 115
 116 Note that this stores the hash reference, not a distinct copy of the hash it
 117 points to.  You can ask the object for a copy with the I<hash> method.
 118
 119 =cut
 120
 121 sub table { 'cust_location'; }
 122
 123 =item find_or_insert
 124
 125 Finds an existing location matching the customer and address values in this
 126 location, if one exists, and sets the contents of this location equal to that
 127 one (including its locationnum).
 128
 129 If an existing location is not found, this one I<will> be inserted.  (This is a
 130 change from the "new_or_existing" method that this replaces.)
 131
 132 The following fields are considered "essential" and I<must> match: custnum,
 133 address1, address2, city, county, state, zip, country, location_number,
 134 location_type, location_kind.  Disabled locations will be found only if this
 135 location is set to disabled.
 136
 137 All other fields are considered "non-essential" and will be ignored in
 138 finding a matching location.  If the existing location doesn't match
 139 in these fields, it will be updated in-place to match.
 140
 141 Returns an error string if inserting or updating a location failed.
 142
 143 It is unfortunately hard to determine if this created a new location or not.
 144
 145 =cut
 146
 147 sub find_or_insert {
 148   my $self = shift;
 149
 150   warn "find_or_insert:\n".Dumper($self) if $DEBUG;
 151
 152   if ($conf->exists('cust_main-no_city_in_address')) {
 153     warn "Warning: passed city to find_or_insert when cust_main-no_city_in_address is configured, ignoring it"
 154       if $self->get('city');
 155     $self->set('city','');
 156   }
 157
 158   # I don't think this is necessary
 159   #if ( !$self->coord_auto and $self->latitude and $self->longitude ) {
 160   #  push @essential, qw(latitude longitude);
 161   #  # but NOT coord_auto; if the latitude and longitude match the geocoded
 162   #  # values then that's good enough
 163   #}
 164
 165   # put nonempty, nonessential fields/values into this hash
 166   my %nonempty = map { $_ => $self->get($_) }
 167                  grep {$self->get($_)} $self->fields;
 168   delete @nonempty{@essential};
 169   delete $nonempty{'locationnum'};
 170
 171   my %hash = map { $_ => $self->get($_) } @essential;
 172   foreach (values %hash) {
 173     s/^\s+//;
 174     s/\s+$//;
 175   }
 176   my @matches = qsearch('cust_location', \%hash);
 177
 178   # we no longer reject matches for having different values in nonessential
 179   # fields; we just alter the record to match
 180   if ( @matches ) {
 181     my $old = $matches[0];
 182     warn "found existing location #".$old->locationnum."\n" if $DEBUG;
 183     foreach my $field (keys %nonempty) {
 184       if ($old->get($field) ne $nonempty{$field}) {
 185         warn "altering $field to match requested location" if $DEBUG;
 186         $old->set($field, $nonempty{$field});
 187       }
 188     } # foreach $field
 189
 190     if ( $old->modified ) {
 191       warn "updating non-essential fields\n" if $DEBUG;
 192       my $error = $old->replace;
 193       return $error if $error;
 194     }
 195     # set $self equal to $old
 196     foreach ($self->fields) {
 197       $self->set($_, $old->get($_));
 198     }
 199     return "";
 200   }
 201
 202   # didn't find a match
 203   warn "not found; inserting new location\n" if $DEBUG;
 204   return $self->insert;
 205 }
 206
 207 =item insert
 208
 209 Adds this record to the database.  If there is an error, returns the error,
 210 otherwise returns false.
 211
 212 =cut
 213
 214 sub insert {
 215   my $self = shift;
 216
 217   if ($conf->exists('cust_main-no_city_in_address')) {
 218     warn "Warning: passed city to insert when cust_main-no_city_in_address is configured, ignoring it"
 219       if $self->get('city');
 220     $self->set('city','');
 221   }
 222
 223   if ( $self->censustract ) {
 224     $self->set('censusyear' => $conf->config('census_legacy') || 2020);
 225   }
 226
 227   my $oldAutoCommit = $FS::UID::AutoCommit;
 228   local $FS::UID::AutoCommit = 0;
 229   my $dbh = dbh;
 230
 231   my $error = $self->SUPER::insert(@_);
 232   if ( $error ) {
 233     $dbh->rollback if $oldAutoCommit;
 234     return $error;
 235   }
 236
 237   #false laziness with cust_main, will go away eventually
 238   if ( !$import and $conf->config('tax_district_method') ) {
 239
 240     my $queue = new FS::queue {
 241       'job' => 'FS::geocode_Mixin::process_district_update'
 242     };
 243     $error = $queue->insert( ref($self), $self->locationnum );
 244     if ( $error ) {
 245       $dbh->rollback if $oldAutoCommit;
 246       return $error;
 247     }
 248
 249   }
 250
 251   # cust_location exports
 252   #my $export_args = $options{'export_args'} || [];
 253
 254   # don't export custnum_pending cases, let follow-up replace handle that
 255   if ($self->custnum || $self->prospectnum) {
 256     my @part_export =
 257       map qsearch( 'part_export', {exportnum=>$_} ),
 258         $conf->config('cust_location-exports'); #, $agentnum
 259
 260     foreach my $part_export ( @part_export ) {
 261       my $error = $part_export->export_insert($self); #, @$export_args);
 262       if ( $error ) {
 263         $dbh->rollback if $oldAutoCommit;
 264         return "exporting to ". $part_export->exporttype.
 265                " (transaction rolled back): $error";
 266       }
 267     }
 268   }
 269
 270   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
 271   '';
 272 }
 273
 274 =item delete
 275
 276 Delete this record from the database.
 277
 278 =item replace OLD_RECORD
 279
 280 Replaces the OLD_RECORD with this one in the database.  If there is an error,
 281 returns the error, otherwise returns false.
 282
 283 =cut
 284
 285 sub replace {
 286   my $self = shift;
 287   my $old = shift;
 288   $old ||= $self->replace_old;
 289
 290   warn "Warning: passed city to replace when cust_main-no_city_in_address is configured"
 291     if $conf->exists('cust_main-no_city_in_address') && $self->get('city');
 292
 293   # the following fields are immutable if this is a customer location. if
 294   # it's a prospect location, then there are no active packages, no billing
 295   # history, no taxes, and in general no reason to keep the old location
 296   # around.
 297   if ( !$allow_location_edit and $self->custnum ) {
 298     foreach (qw(address1 address2 city state zip country)) {
 299       if ( $self->$_ ne $old->$_ ) {
 300         return "can't change cust_location field $_";
 301       }
 302     }
 303   }
 304
 305   my $oldAutoCommit = $FS::UID::AutoCommit;
 306   local $FS::UID::AutoCommit = 0;
 307   my $dbh = dbh;
 308
 309   my $error = $self->SUPER::replace($old);
 310   if ( $error ) {
 311     $dbh->rollback if $oldAutoCommit;
 312     return $error;
 313   }
 314
 315   # cust_location exports
 316   #my $export_args = $options{'export_args'} || [];
 317
 318   # don't export custnum_pending cases, let follow-up replace handle that
 319   if ($self->custnum || $self->prospectnum) {
 320     my @part_export =
 321       map qsearch( 'part_export', {exportnum=>$_} ),
 322         $conf->config('cust_location-exports'); #, $agentnum
 323
 324     foreach my $part_export ( @part_export ) {
 325       my $error = $part_export->export_replace($self, $old); #, @$export_args);
 326       if ( $error ) {
 327         $dbh->rollback if $oldAutoCommit;
 328         return "exporting to ". $part_export->exporttype.
 329                " (transaction rolled back): $error";
 330       }
 331     }
 332   }
 333
 334   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
 335   '';
 336 }
 337
 338
 339 =item check
 340
 341 Checks all fields to make sure this is a valid location.  If there is
 342 an error, returns the error, otherwise returns false.  Called by the insert
 343 and replace methods.
 344
 345 =cut
 346
 347 sub check {
 348   my $self = shift;
 349
 350   return '' if $self->disabled; # so that disabling locations never fails
 351
 352   # whitespace in essential fields leads to problems figuring out if a
 353   # record is "new"; get rid of it.
 354   $self->trim_whitespace(@essential);
 355
 356   my $error =
 357     $self->ut_numbern('locationnum')
 358     || $self->ut_foreign_keyn('prospectnum', 'prospect_main', 'prospectnum')
 359     || $self->ut_foreign_keyn('custnum', 'cust_main', 'custnum')
 360     || $self->ut_textn('locationname')
 361     || $self->ut_text('address1')
 362     || $self->ut_textn('address2')
 363     || ($conf->exists('cust_main-no_city_in_address')
 364         ? $self->ut_textn('city')
 365         : $self->ut_text('city'))
 366     || $self->ut_textn('county')
 367     || $self->ut_textn('state')
 368     || $self->ut_country('country')
 369     || (!$import && $self->ut_zip('zip', $self->country))
 370     || $self->ut_coordn('latitude')
 371     || $self->ut_coordn('longitude')
 372     || $self->ut_enum('coord_auto', [ '', 'Y' ])
 373     || $self->ut_enum('addr_clean', [ '', 'Y' ])
 374     || $self->ut_alphan('location_type')
 375     || $self->ut_textn('location_number')
 376     || $self->ut_enum('location_kind', [ '', 'R', 'B' ] )
 377     || $self->ut_alphan('geocode')
 378     || $self->ut_alphan('district')
 379     || $self->ut_numbern('censusyear')
 380   ;
 381   return $error if $error;
 382   if ( $self->censustract ne '' ) {
 383     if ( $self->censustract =~ /^\s*(\d{9})\.?(\d{2})\s*$/ ) { #old
 384       $self->censustract("$1.$2");
 385     } elsif ($self->censustract =~ /^\s*(\d{15})\s*$/ ) { #new
 386       $self->censustract($1);
 387     } else {
 388       return "Illegal census tract: ". $self->censustract;
 389     }
 390   }
 391
 392   #yikes... this is ancient, pre-dates cust_location and will be harder to
 393   # implement now... how do we know this location is a service location from
 394   # here and not a billing? we can't just check locationnums, we might be new :/
 395   return "Unit # is required"
 396     if $conf->exists('cust_main-require_address2')
 397     && ! $self->address2 =~ /\S/;
 398
 399   # tricky...we have to allow for the customer to not be inserted yet
 400   return "No prospect or customer!" unless $self->prospectnum
 401                                         || $self->custnum
 402                                         || $self->get('custnum_pending');
 403   return "Prospect and customer!"       if $self->prospectnum && $self->custnum;
 404
 405   return 'Location kind is required'
 406     if $self->prospectnum
 407     && $conf->exists('prospect_main-alt_address_format')
 408     && ! $self->location_kind;
 409
 410   unless ( $import or qsearch('cust_main_county', {
 411     'country' => $self->country,
 412     'state'   => '',
 413    } ) ) {
 414     return "Unknown state/county/country: ".
 415       $self->state. "/". $self->county. "/". $self->country
 416       unless qsearch('cust_main_county',{
 417         'state'   => $self->state,
 418         'county'  => $self->county,
 419         'country' => $self->country,
 420       } );
 421   }
 422
 423   # set coordinates, unless we already have them
 424   if (!$import and !$self->latitude and !$self->longitude) {
 425     $self->set_coord;
 426   }
 427
 428   $self->SUPER::check;
 429 }
 430
 431 =item country_full
 432
 433 Returns this location's full country name
 434
 435 =cut
 436
 437 #moved to geocode_Mixin.pm
 438
 439 =item line
 440
 441 Synonym for location_label
 442
 443 =cut
 444
 445 sub line {
 446   my $self = shift;
 447   $self->location_label(@_);
 448 }
 449
 450 =item has_ship_address
 451
 452 Returns false since cust_location objects do not have a separate shipping
 453 address.
 454
 455 =cut
 456
 457 sub has_ship_address {
 458   '';
 459 }
 460
 461 =item location_hash
 462
 463 Returns a list of key/value pairs, with the following keys: address1, address2,
 464 city, county, state, zip, country, geocode, location_type, location_number,
 465 location_kind.
 466
 467 =cut
 468
 469 =item disable_if_unused
 470
 471 Sets the "disabled" flag on the location if it is no longer in use as a
 472 prospect location, package location, or a customer's billing or default
 473 service address.
 474
 475 =cut
 476
 477 sub disable_if_unused {
 478
 479   my $self = shift;
 480   my $locationnum = $self->locationnum;
 481   return '' if FS::cust_main->count('bill_locationnum = '.$locationnum.' OR
 482                                      ship_locationnum = '.$locationnum)
 483             or FS::contact->count(      'locationnum  = '.$locationnum)
 484             or FS::cust_pkg->count('cancel IS NULL AND
 485                                          locationnum  = '.$locationnum)
 486           ;
 487   $self->disabled('Y');
 488   $self->replace;
 489
 490 }
 491
 492 =item move_to
 493
 494 Takes a new L<FS::cust_location> object.  Moves all packages that use the
 495 existing location to the new one, then sets the "disabled" flag on the old
 496 location.  Returns nothing on success, an error message on error.
 497
 498 =cut
 499
 500 sub move_to {
 501   my $old = shift;
 502   my $new = shift;
 503
 504   warn "move_to:\nFROM:".Dumper($old)."\nTO:".Dumper($new) if $DEBUG;
 505
 506   local $SIG{HUP} = 'IGNORE';
 507   local $SIG{INT} = 'IGNORE';
 508   local $SIG{QUIT} = 'IGNORE';
 509   local $SIG{TERM} = 'IGNORE';
 510   local $SIG{TSTP} = 'IGNORE';
 511   local $SIG{PIPE} = 'IGNORE';
 512
 513   my $oldAutoCommit = $FS::UID::AutoCommit;
 514   local $FS::UID::AutoCommit = 0;
 515   my $dbh = dbh;
 516   my $error = '';
 517
 518   # prevent this from failing because of pkg_svc quantity limits
 519   local( $FS::cust_svc::ignore_quantity ) = 1;
 520
 521   if ( !$new->locationnum ) {
 522     $error = $new->insert;
 523     if ( $error ) {
 524       $dbh->rollback if $oldAutoCommit;
 525       return "Error creating location: $error";
 526     }
 527   } elsif ( $new->locationnum == $old->locationnum ) {
 528     # then they're the same location; the normal result of doing a minor
 529     # location edit
 530     $dbh->commit if $oldAutoCommit;
 531     return '';
 532   }
 533
 534   # find all packages that have the old location as their service address,
 535   # and aren't canceled,
 536   # and aren't supplemental to another package.
 537   my @pkgs = qsearch('cust_pkg', {
 538       'locationnum' => $old->locationnum,
 539       'cancel'      => '',
 540       'main_pkgnum' => '',
 541     });
 542   foreach my $cust_pkg (@pkgs) {
 543     # don't move one-time charges that have already been charged
 544     next if $cust_pkg->part_pkg->freq eq '0'
 545             and ($cust_pkg->setup || 0) > 0;
 546
 547     $error = $cust_pkg->change(
 548       'locationnum' => $new->locationnum,
 549       'keep_dates'  => 1
 550     );
 551     if ( $error and not ref($error) ) {
 552       $dbh->rollback if $oldAutoCommit;
 553       return "Error moving pkgnum ".$cust_pkg->pkgnum.": $error";
 554     }
 555   }
 556
 557   $error = $old->disable_if_unused;
 558   if ( $error ) {
 559     $dbh->rollback if $oldAutoCommit;
 560     return "Error disabling old location: $error";
 561   }
 562
 563   $dbh->commit if $oldAutoCommit;
 564   '';
 565 }
 566
 567 =item alternize
 568
 569 Attempts to parse data for location_type and location_number from address1
 570 and address2.
 571
 572 =cut
 573
 574 sub alternize {
 575   my $self = shift;
 576
 577   return '' if $self->get('location_type')
 578             || $self->get('location_number');
 579
 580   my %parse;
 581   if ( 1 ) { #ikano, switch on via config
 582     { no warnings 'void';
 583       eval { 'use FS::part_export::ikano;' };
 584       die $@ if $@;
 585     }
 586     %parse = FS::part_export::ikano->location_types_parse;
 587   } else {
 588     %parse = (); #?
 589   }
 590
 591   foreach my $from ('address1', 'address2') {
 592     foreach my $parse ( keys %parse ) {
 593       my $value = $self->get($from);
 594       if ( $value =~ s/(^|\W+)$parse\W+(\w+)\W*$//i ) {
 595         $self->set('location_type', $parse{$parse});
 596         $self->set('location_number', $2);
 597         $self->set($from, $value);
 598         return '';
 599       }
 600     }
 601   }
 602
 603   #nothing matched, no changes
 604   $self->get('address2')
 605     ? "Can't parse unit type and number from address2"
 606     : '';
 607 }
 608
 609 =item dealternize
 610
 611 Moves data from location_type and location_number to the end of address1.
 612
 613 =cut
 614
 615 sub dealternize {
 616   my $self = shift;
 617
 618   #false laziness w/geocode_Mixin.pm::line
 619   my $lt = $self->get('location_type');
 620   if ( $lt ) {
 621
 622     my %location_type;
 623     if ( 1 ) { #ikano, switch on via config
 624       { no warnings 'void';
 625         eval { 'use FS::part_export::ikano;' };
 626         die $@ if $@;
 627       }
 628       %location_type = FS::part_export::ikano->location_types;
 629     } else {
 630       %location_type = (); #?
 631     }
 632
 633     $self->address1( $self->address1. ' '. $location_type{$lt} || $lt );
 634     $self->location_type('');
 635   }
 636
 637   if ( length($self->location_number) ) {
 638     $self->address1( $self->address1. ' '. $self->location_number );
 639     $self->location_number('');
 640   }
 641
 642   '';
 643 }
 644
 645 =item location_label
 646
 647 Returns the label of the location object.
 648
 649 Options:
 650
 651 =over 4
 652
 653 =item cust_main
 654
 655 Customer object (see L<FS::cust_main>)
 656
 657 =item prospect_main
 658
 659 Prospect object (see L<FS::prospect_main>)
 660
 661 =item join_string
 662
 663 String used to join location elements
 664
 665 =item no_prefix
 666
 667 Don't label the default service location as "Default service location".
 668 May become the default at some point.
 669
 670 =back
 671
 672 =cut
 673
 674 sub location_label {
 675   my( $self, %opt ) = @_;
 676
 677   my $prefix = $self->label_prefix;
 678   $prefix .= ($opt{join_string} ||  ': ') if $prefix;
 679   $prefix = '' if $opt{'no_prefix'};
 680
 681   $prefix . $self->SUPER::location_label(%opt);
 682 }
 683
 684 =item label_prefix
 685
 686 Returns the optional site ID string (based on the cust_location-label_prefix
 687 config option), "Default service location", or the empty string.
 688
 689 Options:
 690
 691 =over 4
 692
 693 =item cust_main
 694
 695 Customer object (see L<FS::cust_main>)
 696
 697 =item prospect_main
 698
 699 Prospect object (see L<FS::prospect_main>)
 700
 701 =back
 702
 703 =cut
 704
 705 sub label_prefix {
 706   my( $self, %opt ) = @_;
 707
 708   my $cust_or_prospect = $opt{cust_main} || $opt{prospect_main};
 709   unless ( $cust_or_prospect ) {
 710     if ( $self->custnum ) {
 711       $cust_or_prospect = FS::cust_main->by_key($self->custnum);
 712     } elsif ( $self->prospectnum ) {
 713       $cust_or_prospect = FS::prospect_main->by_key($self->prospectnum);
 714     }
 715   }
 716
 717   my $prefix = '';
 718   if ( $label_prefix eq 'CoStAg' ) {
 719     my $agent = $conf->config('cust_main-custnum-display_prefix',
 720                   $cust_or_prospect->agentnum)
 721                 || $cust_or_prospect->agent->agent;
 722     # else this location is invalid
 723     $prefix = uc( join('',
 724         $self->country,
 725         ($self->state =~ /^(..)/),
 726         ($agent =~ /^(..)/),
 727         sprintf('%05d', $self->locationnum)
 728     ) );
 729
 730   } elsif ( $label_prefix eq '_location' && $self->locationname ) {
 731     $prefix = $self->locationname;
 732
 733   #} elsif (    ( $opt{'cust_main'} || $self->custnum )
 734   #        && $self->locationnum == $cust_or_prospect->ship_locationnum ) {
 735   #  $prefix = 'Default service location';
 736   #}
 737   } else {
 738     $prefix = '';
 739   }
 740
 741   $prefix;
 742 }
 743
 744 =item county_state_country
 745
 746 Returns a string consisting of just the county, state and country.
 747
 748 =cut
 749
 750 sub county_state_country {
 751   my $self = shift;
 752   my $label = $self->country;
 753   $label = $self->state.", $label" if $self->state;
 754   $label = $self->county." County, $label" if $self->county;
 755   $label;
 756 }
 757
 758 =item cust_main
 759
 760 =cut
 761
 762 sub cust_main {
 763   my $self = shift;
 764   return '' unless $self->custnum;
 765   qsearchs('cust_main', { 'custnum' => $self->custnum } );
 766 }
 767
 768 =back
 769
 770 =head2 SUBROUTINES
 771
 772 =over 4
 773
 774 =item process_censustract_update LOCATIONNUM
 775
 776 Queueable function to update the census tract to the current year (as set in
 777 the 'census_year' configuration variable) and retrieve the new tract code.
 778
 779 =cut
 780
 781 sub process_censustract_update {
 782   eval "use FS::GeocodeCache";
 783   die $@ if $@;
 784   my $locationnum = shift;
 785   my $cust_location =
 786     qsearchs( 'cust_location', { locationnum => $locationnum })
 787       or die "locationnum '$locationnum' not found!\n";
 788
 789   my $new_year = $conf->config('census_legacy') || 2020;
 790   my $loc = FS::GeocodeCache->new( $cust_location->location_hash );
 791   $loc->set_censustract;
 792   my $error = $loc->get('censustract_error');
 793   die $error if $error;
 794   $cust_location->set('censustract', $loc->get('censustract'));
 795   $cust_location->set('censusyear',  $new_year);
 796   $error = $cust_location->replace;
 797   die $error if $error;
 798   return;
 799 }
 800
 801 =item process_set_coord
 802
 803 Queueable function to find and fill in coordinates for all locations that
 804 lack them.  Because this uses the Google Maps API, it's internally rate
 805 limited and must run in a single process.
 806
 807 =cut
 808
 809 sub process_set_coord {
 810   my $job = shift;
 811   # avoid starting multiple instances of this job
 812   my @others = qsearch('queue', {
 813       'status'  => 'locked',
 814       'job'     => $job->job,
 815       'jobnum'  => {op=>'!=', value=>$job->jobnum},
 816   });
 817   return if @others;
 818
 819   $job->update_statustext('finding locations to update');
 820   my @missing_coords = qsearch('cust_location', {
 821       'disabled'  => '',
 822       'latitude'  => '',
 823       'longitude' => '',
 824   });
 825   my $i = 0;
 826   my $n = scalar @missing_coords;
 827   for my $cust_location (@missing_coords) {
 828     $cust_location->set_coord;
 829     my $error = $cust_location->replace;
 830     if ( $error ) {
 831       warn "error geocoding location#".$cust_location->locationnum.": $error\n";
 832     } else {
 833       $i++;
 834       $job->update_statustext("updated $i / $n locations");
 835       dbh->commit; # so that we don't have to wait for the whole thing to finish
 836       # Rate-limit to stay under the Google Maps usage limit (2500/day).
 837       # 86,400 / 35 = 2,468 lookups per day.
 838     }
 839     sleep 35;
 840   }
 841   if ( $i < $n ) {
 842     die "failed to update ".$n-$i." locations\n";
 843   }
 844   return;
 845 }
 846
 847 =item process_standardize [ LOCATIONNUMS ]
 848
 849 Performs address standardization on locations with unclean addresses,
 850 using whatever method you have configured.  If the standardize_* method
 851 returns a I<clean> address match, the location will be updated.  This is
 852 always an in-place update (because the physical location is the same,
 853 and is just being referred to by a more accurate name).
 854
 855 Disabled locations will be skipped, as nobody cares.
 856
 857 If any LOCATIONNUMS are provided, only those locations will be updated.
 858
 859 =cut
 860
 861 sub process_standardize {
 862   my $job = shift;
 863   my @others = qsearch('queue', {
 864       'status'  => 'locked',
 865       'job'     => $job->job,
 866       'jobnum'  => {op=>'!=', value=>$job->jobnum},
 867   });
 868   return if @others;
 869   my @locationnums = grep /^\d+$/, @_;
 870   my $where = "AND locationnum IN(".join(',',@locationnums).")"
 871     if scalar(@locationnums);
 872   my @locations = qsearch({
 873       table     => 'cust_location',
 874       hashref   => { addr_clean => '', disabled => '' },
 875       extra_sql => $where,
 876   });
 877   my $n_todo = scalar(@locations);
 878   my $n_done = 0;
 879
 880   # special: log this
 881   my $log;
 882   eval "use Text::CSV";
 883   open $log, '>', "$FS::UID::cache_dir/process_standardize-" .
 884                   time2str('%Y%m%d',time) .
 885                   ".csv";
 886   my $csv = Text::CSV->new({binary => 1, eol => "\n"});
 887
 888   foreach my $cust_location (@locations) {
 889     $job->update_statustext( int(100 * $n_done/$n_todo) . ",$n_done / $n_todo locations" ) if $job;
 890     my $result = FS::GeocodeCache->standardize($cust_location);
 891     if ( $result->{addr_clean} and !$result->{error} ) {
 892       my @cols = ($cust_location->locationnum);
 893       foreach (keys %$result) {
 894         push @cols, $cust_location->get($_), $result->{$_};
 895         $cust_location->set($_, $result->{$_});
 896       }
 897       # bypass immutable field restrictions
 898       my $error = $cust_location->FS::Record::replace;
 899       warn "location ".$cust_location->locationnum.": $error\n" if $error;
 900       $csv->print($log, \@cols);
 901     }
 902     $n_done++;
 903     dbh->commit; # so that we can resume if interrupted
 904   }
 905   close $log;
 906 }
 907
 908 sub _upgrade_data {
 909   my $class = shift;
 910
 911   # are we going to need to update tax districts?
 912   my $use_districts = $conf->config('tax_district_method') ? 1 : 0;
 913
 914   # trim whitespace on records that need it
 915   local $allow_location_edit = 1;
 916   foreach my $field (@essential) {
 917     next if $field eq 'custnum';
 918     next if $field eq 'disabled';
 919     foreach my $location (qsearch({
 920       table => 'cust_location',
 921       extra_sql => " WHERE disabled IS NULL AND ($field LIKE ' %' OR $field LIKE '% ')"
 922     })) {
 923       my $error = $location->replace;
 924       die "$error (fixing whitespace in $field, locationnum ".$location->locationnum.')'
 925         if $error;
 926
 927       if ( $use_districts ) {
 928         my $queue = new FS::queue {
 929           'job' => 'FS::geocode_Mixin::process_district_update'
 930         };
 931         $error = $queue->insert( 'FS::cust_location' => $location->locationnum );
 932         die $error if $error;
 933       }
 934     } # foreach $location
 935   } # foreach $field
 936   '';
 937 }
 938
 939 =head1 BUGS
 940
 941 =head1 SEE ALSO
 942
 943 L<FS::cust_main_county>, L<FS::cust_pkg>, L<FS::Record>,
 944 schema.html from the base documentation.
 945
 946 =cut
 947
 948 1;
 949