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