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 );
   6 use Data::Dumper;
   7 use Date::Format qw( time2str );
   8 use Locale::Country;
   9 use FS::UID qw( dbh driver_name );
  10 use FS::Record qw( qsearch qsearchs );
  11 use FS::Conf;
  12 use FS::prospect_main;
  13 use FS::cust_main;
  14 use FS::cust_main_county;
  15 use FS::part_export;
  16 use FS::GeocodeCache;
  17
  18 $import = 0;
  19
  20 $DEBUG = 0;
  21
  22 FS::UID->install_callback( sub {
  23   $conf = FS::Conf->new;
  24   $label_prefix = $conf->config('cust_location-label_prefix') || '';
  25 });
  26
  27 =head1 NAME
  28
  29 FS::cust_location - Object methods for cust_location records
  30
  31 =head1 SYNOPSIS
  32
  33   use FS::cust_location;
  34
  35   $record = new FS::cust_location \%hash;
  36   $record = new FS::cust_location { 'column' => 'value' };
  37
  38   $error = $record->insert;
  39
  40   $error = $new_record->replace($old_record);
  41
  42   $error = $record->delete;
  43
  44   $error = $record->check;
  45
  46 =head1 DESCRIPTION
  47
  48 An FS::cust_location object represents a customer location.  FS::cust_location
  49 inherits from FS::Record.  The following fields are currently supported:
  50
  51 =over 4
  52
  53 =item locationnum
  54
  55 primary key
  56
  57 =item custnum
  58
  59 custnum
  60
  61 =item address1
  62
  63 Address line one (required)
  64
  65 =item address2
  66
  67 Address line two (optional)
  68
  69 =item city
  70
  71 City
  72
  73 =item county
  74
  75 County (optional, see L<FS::cust_main_county>)
  76
  77 =item state
  78
  79 State (see L<FS::cust_main_county>)
  80
  81 =item zip
  82
  83 Zip
  84
  85 =item country
  86
  87 Country (see L<FS::cust_main_county>)
  88
  89 =item geocode
  90
  91 Geocode
  92
  93 =item district
  94
  95 Tax district code (optional)
  96
  97 =item incorporated
  98
  99 Incorporated city flag: set to 'Y' if the address is in the legal borders
 100 of an incorporated city.
 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   my @essential = (qw(custnum address1 address2 city county state zip country
 153     location_number location_type location_kind disabled));
 154
 155   # I don't think this is necessary
 156   #if ( !$self->coord_auto and $self->latitude and $self->longitude ) {
 157   #  push @essential, qw(latitude longitude);
 158   #  # but NOT coord_auto; if the latitude and longitude match the geocoded
 159   #  # values then that's good enough
 160   #}
 161
 162   # put nonempty, nonessential fields/values into this hash
 163   my %nonempty = map { $_ => $self->get($_) }
 164                  grep {$self->get($_)} $self->fields;
 165   delete @nonempty{@essential};
 166   delete $nonempty{'locationnum'};
 167
 168   my %hash = map { $_ => $self->get($_) } @essential;
 169   my @matches = qsearch('cust_location', \%hash);
 170
 171   # we no longer reject matches for having different values in nonessential
 172   # fields; we just alter the record to match
 173   if ( @matches ) {
 174     my $old = $matches[0];
 175     warn "found existing location #".$old->locationnum."\n" if $DEBUG;
 176     foreach my $field (keys %nonempty) {
 177       if ($old->get($field) ne $nonempty{$field}) {
 178         warn "altering $field to match requested location" if $DEBUG;
 179         $old->set($field, $nonempty{$field});
 180       }
 181     } # foreach $field
 182
 183     if ( $old->modified ) {
 184       warn "updating non-essential fields\n" if $DEBUG;
 185       my $error = $old->replace;
 186       return $error if $error;
 187     }
 188     # set $self equal to $old
 189     foreach ($self->fields) {
 190       $self->set($_, $old->get($_));
 191     }
 192     return "";
 193   }
 194
 195   # didn't find a match
 196   warn "not found; inserting new location\n" if $DEBUG;
 197   return $self->insert;
 198 }
 199
 200 =item insert
 201
 202 Adds this record to the database.  If there is an error, returns the error,
 203 otherwise returns false.
 204
 205 =cut
 206
 207 sub insert {
 208   my $self = shift;
 209
 210   if ( $self->censustract ) {
 211     $self->set('censusyear' => $conf->config('census_year') || 2012);
 212   }
 213
 214   my $oldAutoCommit = $FS::UID::AutoCommit;
 215   local $FS::UID::AutoCommit = 0;
 216   my $dbh = dbh;
 217
 218   my $error = $self->SUPER::insert(@_);
 219   if ( $error ) {
 220     $dbh->rollback if $oldAutoCommit;
 221     return $error;
 222   }
 223
 224   #false laziness with cust_main, will go away eventually
 225   if ( !$import and $conf->config('tax_district_method') ) {
 226
 227     my $queue = new FS::queue {
 228       'job' => 'FS::geocode_Mixin::process_district_update'
 229     };
 230     $error = $queue->insert( ref($self), $self->locationnum );
 231     if ( $error ) {
 232       $dbh->rollback if $oldAutoCommit;
 233       return $error;
 234     }
 235
 236   }
 237
 238   # cust_location exports
 239   #my $export_args = $options{'export_args'} || [];
 240
 241   my @part_export =
 242     map qsearch( 'part_export', {exportnum=>$_} ),
 243       $conf->config('cust_location-exports'); #, $agentnum
 244
 245   foreach my $part_export ( @part_export ) {
 246     my $error = $part_export->export_insert($self); #, @$export_args);
 247     if ( $error ) {
 248       $dbh->rollback if $oldAutoCommit;
 249       return "exporting to ". $part_export->exporttype.
 250              " (transaction rolled back): $error";
 251     }
 252   }
 253
 254
 255   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
 256   '';
 257 }
 258
 259 =item delete
 260
 261 Delete this record from the database.
 262
 263 =item replace OLD_RECORD
 264
 265 Replaces the OLD_RECORD with this one in the database.  If there is an error,
 266 returns the error, otherwise returns false.
 267
 268 =cut
 269
 270 sub replace {
 271   my $self = shift;
 272   my $old = shift;
 273   $old ||= $self->replace_old;
 274   # the following fields are immutable
 275   foreach (qw(address1 address2 city state zip country)) {
 276     if ( $self->$_ ne $old->$_ ) {
 277       return "can't change cust_location field $_";
 278     }
 279   }
 280
 281   my $oldAutoCommit = $FS::UID::AutoCommit;
 282   local $FS::UID::AutoCommit = 0;
 283   my $dbh = dbh;
 284
 285   my $error = $self->SUPER::replace($old);
 286   if ( $error ) {
 287     $dbh->rollback if $oldAutoCommit;
 288     return $error;
 289   }
 290
 291   # cust_location exports
 292   #my $export_args = $options{'export_args'} || [];
 293
 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_replace($self, $old); #, @$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
 313 =item check
 314
 315 Checks all fields to make sure this is a valid location.  If there is
 316 an error, returns the error, otherwise returns false.  Called by the insert
 317 and replace methods.
 318
 319 =cut
 320
 321 sub check {
 322   my $self = shift;
 323
 324   return '' if $self->disabled; # so that disabling locations never fails
 325
 326   my $error =
 327     $self->ut_numbern('locationnum')
 328     || $self->ut_foreign_keyn('prospectnum', 'prospect_main', 'prospectnum')
 329     || $self->ut_foreign_keyn('custnum', 'cust_main', 'custnum')
 330     || $self->ut_alphan('locationname')
 331     || $self->ut_text('address1')
 332     || $self->ut_textn('address2')
 333     || $self->ut_text('city')
 334     || $self->ut_textn('county')
 335     || $self->ut_textn('state')
 336     || $self->ut_country('country')
 337     || (!$import && $self->ut_zip('zip', $self->country))
 338     || $self->ut_coordn('latitude')
 339     || $self->ut_coordn('longitude')
 340     || $self->ut_enum('coord_auto', [ '', 'Y' ])
 341     || $self->ut_enum('addr_clean', [ '', 'Y' ])
 342     || $self->ut_alphan('location_type')
 343     || $self->ut_textn('location_number')
 344     || $self->ut_enum('location_kind', [ '', 'R', 'B' ] )
 345     || $self->ut_alphan('geocode')
 346     || $self->ut_alphan('district')
 347     || $self->ut_numbern('censusyear')
 348     || $self->ut_flag('incorporated')
 349   ;
 350   return $error if $error;
 351   if ( $self->censustract ne '' ) {
 352     $self->censustract =~ /^\s*(\d{9})\.?(\d{2})\s*$/
 353       or return "Illegal census tract: ". $self->censustract;
 354
 355     $self->censustract("$1.$2");
 356   }
 357
 358   if ( $conf->exists('cust_main-require_address2') and
 359        !$self->ship_address2 =~ /\S/ ) {
 360     return "Unit # is required";
 361   }
 362
 363   # tricky...we have to allow for the customer to not be inserted yet
 364   return "No prospect or customer!" unless $self->prospectnum
 365                                         || $self->custnum
 366                                         || $self->get('custnum_pending');
 367   return "Prospect and customer!"       if $self->prospectnum && $self->custnum;
 368
 369   return 'Location kind is required'
 370     if $self->prospectnum
 371     && $conf->exists('prospect_main-alt_address_format')
 372     && ! $self->location_kind;
 373
 374   unless ( $import or qsearch('cust_main_county', {
 375     'country' => $self->country,
 376     'state'   => '',
 377    } ) ) {
 378     return "Unknown state/county/country: ".
 379       $self->state. "/". $self->county. "/". $self->country
 380       unless qsearch('cust_main_county',{
 381         'state'   => $self->state,
 382         'county'  => $self->county,
 383         'country' => $self->country,
 384       } );
 385   }
 386
 387   # set coordinates, unless we already have them
 388   if (!$import and !$self->latitude and !$self->longitude) {
 389     $self->set_coord;
 390   }
 391
 392   $self->SUPER::check;
 393 }
 394
 395 =item country_full
 396
 397 Returns this locations's full country name
 398
 399 =cut
 400
 401 sub country_full {
 402   my $self = shift;
 403   code2country($self->country);
 404 }
 405
 406 =item line
 407
 408 Synonym for location_label
 409
 410 =cut
 411
 412 sub line {
 413   my $self = shift;
 414   $self->location_label(@_);
 415 }
 416
 417 =item has_ship_address
 418
 419 Returns false since cust_location objects do not have a separate shipping
 420 address.
 421
 422 =cut
 423
 424 sub has_ship_address {
 425   '';
 426 }
 427
 428 =item location_hash
 429
 430 Returns a list of key/value pairs, with the following keys: address1, address2,
 431 city, county, state, zip, country, geocode, location_type, location_number,
 432 location_kind.
 433
 434 =cut
 435
 436 =item disable_if_unused
 437
 438 Sets the "disabled" flag on the location if it is no longer in use as a
 439 prospect location, package location, or a customer's billing or default
 440 service address.
 441
 442 =cut
 443
 444 sub disable_if_unused {
 445
 446   my $self = shift;
 447   my $locationnum = $self->locationnum;
 448   return '' if FS::cust_main->count('bill_locationnum = '.$locationnum.' OR
 449                                      ship_locationnum = '.$locationnum)
 450             or FS::contact->count(      'locationnum  = '.$locationnum)
 451             or FS::cust_pkg->count('cancel IS NULL AND
 452                                          locationnum  = '.$locationnum)
 453           ;
 454   $self->disabled('Y');
 455   $self->replace;
 456
 457 }
 458
 459 =item move_to
 460
 461 Takes a new L<FS::cust_location> object.  Moves all packages that use the
 462 existing location to the new one, then sets the "disabled" flag on the old
 463 location.  Returns nothing on success, an error message on error.
 464
 465 =cut
 466
 467 sub move_to {
 468   my $old = shift;
 469   my $new = shift;
 470
 471   warn "move_to:\nFROM:".Dumper($old)."\nTO:".Dumper($new) if $DEBUG;
 472
 473   local $SIG{HUP} = 'IGNORE';
 474   local $SIG{INT} = 'IGNORE';
 475   local $SIG{QUIT} = 'IGNORE';
 476   local $SIG{TERM} = 'IGNORE';
 477   local $SIG{TSTP} = 'IGNORE';
 478   local $SIG{PIPE} = 'IGNORE';
 479
 480   my $oldAutoCommit = $FS::UID::AutoCommit;
 481   local $FS::UID::AutoCommit = 0;
 482   my $dbh = dbh;
 483   my $error = '';
 484
 485   # prevent this from failing because of pkg_svc quantity limits
 486   local( $FS::cust_svc::ignore_quantity ) = 1;
 487
 488   if ( !$new->locationnum ) {
 489     $error = $new->insert;
 490     if ( $error ) {
 491       $dbh->rollback if $oldAutoCommit;
 492       return "Error creating location: $error";
 493     }
 494   } elsif ( $new->locationnum == $old->locationnum ) {
 495     # then they're the same location; the normal result of doing a minor
 496     # location edit
 497     $dbh->commit if $oldAutoCommit;
 498     return '';
 499   }
 500
 501   # find all packages that have the old location as their service address,
 502   # and aren't canceled,
 503   # and aren't supplemental to another package.
 504   my @pkgs = qsearch('cust_pkg', {
 505       'locationnum' => $old->locationnum,
 506       'cancel'      => '',
 507       'main_pkgnum' => '',
 508     });
 509   foreach my $cust_pkg (@pkgs) {
 510     # don't move one-time charges that have already been charged
 511     next if $cust_pkg->part_pkg->freq eq '0'
 512             and ($cust_pkg->setup || 0) > 0;
 513
 514     $error = $cust_pkg->change(
 515       'locationnum' => $new->locationnum,
 516       'keep_dates'  => 1
 517     );
 518     if ( $error and not ref($error) ) {
 519       $dbh->rollback if $oldAutoCommit;
 520       return "Error moving pkgnum ".$cust_pkg->pkgnum.": $error";
 521     }
 522   }
 523
 524   $error = $old->disable_if_unused;
 525   if ( $error ) {
 526     $dbh->rollback if $oldAutoCommit;
 527     return "Error disabling old location: $error";
 528   }
 529
 530   $dbh->commit if $oldAutoCommit;
 531   '';
 532 }
 533
 534 =item alternize
 535
 536 Attempts to parse data for location_type and location_number from address1
 537 and address2.
 538
 539 =cut
 540
 541 sub alternize {
 542   my $self = shift;
 543
 544   return '' if $self->get('location_type')
 545             || $self->get('location_number');
 546
 547   my %parse;
 548   if ( 1 ) { #ikano, switch on via config
 549     { no warnings 'void';
 550       eval { 'use FS::part_export::ikano;' };
 551       die $@ if $@;
 552     }
 553     %parse = FS::part_export::ikano->location_types_parse;
 554   } else {
 555     %parse = (); #?
 556   }
 557
 558   foreach my $from ('address1', 'address2') {
 559     foreach my $parse ( keys %parse ) {
 560       my $value = $self->get($from);
 561       if ( $value =~ s/(^|\W+)$parse\W+(\w+)\W*$//i ) {
 562         $self->set('location_type', $parse{$parse});
 563         $self->set('location_number', $2);
 564         $self->set($from, $value);
 565         return '';
 566       }
 567     }
 568   }
 569
 570   #nothing matched, no changes
 571   $self->get('address2')
 572     ? "Can't parse unit type and number from address2"
 573     : '';
 574 }
 575
 576 =item dealternize
 577
 578 Moves data from location_type and location_number to the end of address1.
 579
 580 =cut
 581
 582 sub dealternize {
 583   my $self = shift;
 584
 585   #false laziness w/geocode_Mixin.pm::line
 586   my $lt = $self->get('location_type');
 587   if ( $lt ) {
 588
 589     my %location_type;
 590     if ( 1 ) { #ikano, switch on via config
 591       { no warnings 'void';
 592         eval { 'use FS::part_export::ikano;' };
 593         die $@ if $@;
 594       }
 595       %location_type = FS::part_export::ikano->location_types;
 596     } else {
 597       %location_type = (); #?
 598     }
 599
 600     $self->address1( $self->address1. ' '. $location_type{$lt} || $lt );
 601     $self->location_type('');
 602   }
 603
 604   if ( length($self->location_number) ) {
 605     $self->address1( $self->address1. ' '. $self->location_number );
 606     $self->location_number('');
 607   }
 608
 609   '';
 610 }
 611
 612 =item location_label
 613
 614 Returns the label of the location object.
 615
 616 Options:
 617
 618 =over 4
 619
 620 =item cust_main
 621
 622 Customer object (see L<FS::cust_main>)
 623
 624 =item prospect_main
 625
 626 Prospect object (see L<FS::prospect_main>)
 627
 628 =item join_string
 629
 630 String used to join location elements
 631
 632 =back
 633
 634 =cut
 635
 636 sub location_label {
 637   my( $self, %opt ) = @_;
 638
 639   my $prefix = $self->label_prefix;
 640   $prefix .= ($opt{join_string} ||  ': ') if $prefix;
 641
 642   $prefix . $self->SUPER::location_label(%opt);
 643 }
 644
 645 =item label_prefix
 646
 647 Returns the optional site ID string (based on the cust_location-label_prefix
 648 config option), "Default service location", or the empty string.
 649
 650 Options:
 651
 652 =over 4
 653
 654 =item cust_main
 655
 656 Customer object (see L<FS::cust_main>)
 657
 658 =item prospect_main
 659
 660 Prospect object (see L<FS::prospect_main>)
 661
 662 =back
 663
 664 =cut
 665
 666 sub label_prefix {
 667   my( $self, %opt ) = @_;
 668
 669   my $cust_or_prospect = $opt{cust_main} || $opt{prospect_main};
 670   unless ( $cust_or_prospect ) {
 671     if ( $self->custnum ) {
 672       $cust_or_prospect = FS::cust_main->by_key($self->custnum);
 673     } elsif ( $self->prospectnum ) {
 674       $cust_or_prospect = FS::prospect_main->by_key($self->prospectnum);
 675     }
 676   }
 677
 678   my $prefix = '';
 679   if ( $label_prefix eq 'CoStAg' ) {
 680     my $agent = $conf->config('cust_main-custnum-display_prefix',
 681                   $cust_or_prospect->agentnum)
 682                 || $cust_or_prospect->agent->agent;
 683     # else this location is invalid
 684     $prefix = uc( join('',
 685         $self->country,
 686         ($self->state =~ /^(..)/),
 687         ($agent =~ /^(..)/),
 688         sprintf('%05d', $self->locationnum)
 689     ) );
 690
 691   } elsif ( $label_prefix eq '_location' && $self->locationname ) {
 692     $prefix = $self->locationname;
 693
 694   } elsif (    ( $opt{'cust_main'} || $self->custnum )
 695           && $self->locationnum == $cust_or_prospect->ship_locationnum ) {
 696     $prefix = 'Default service location';
 697   }
 698
 699   $prefix;
 700 }
 701
 702 =item county_state_county
 703
 704 Returns a string consisting of just the county, state and country.
 705
 706 =cut
 707
 708 sub county_state_country {
 709   my $self = shift;
 710   my $label = $self->country;
 711   $label = $self->state.", $label" if $self->state;
 712   $label = $self->county." County, $label" if $self->county;
 713   $label;
 714 }
 715
 716 =back
 717
 718 =head1 CLASS METHODS
 719
 720 =item in_county_sql OPTIONS
 721
 722 Returns an SQL expression to test membership in a cust_main_county
 723 geographic area.  By default, this requires district, city, county,
 724 state, and country to match exactly.  Pass "ornull => 1" to allow
 725 partial matches where some fields are NULL in the cust_main_county
 726 record but not in the location.
 727
 728 Pass "param => 1" to receive a parameterized expression (rather than
 729 one that requires a join to cust_main_county) and a list of parameter
 730 names in order.
 731
 732 =cut
 733
 734 sub in_county_sql {
 735   # replaces FS::cust_pkg::location_sql
 736   my ($class, %opt) = @_;
 737   my $ornull = $opt{ornull} ? ' OR ? IS NULL' : '';
 738   my $x = $ornull ? 3 : 2;
 739   my @fields = (('district') x 3,
 740                 ('city') x 3,
 741                 ('county') x $x,
 742                 ('state') x $x,
 743                 'country');
 744
 745   my $text = (driver_name =~ /^mysql/i) ? 'char' : 'text';
 746
 747   my @where = (
 748     "cust_location.district = ? OR ? = '' OR CAST(? AS $text) IS NULL",
 749     "cust_location.city     = ? OR ? = '' OR CAST(? AS $text) IS NULL",
 750     "cust_location.county   = ? OR (? = '' AND cust_location.county IS NULL) $ornull",
 751     "cust_location.state    = ? OR (? = '' AND cust_location.state IS NULL ) $ornull",
 752     "cust_location.country = ?"
 753   );
 754   my $sql = join(' AND ', map "($_)\n", @where);
 755   if ( $opt{param} ) {
 756     return $sql, @fields;
 757   }
 758   else {
 759     # do the substitution here
 760     foreach (@fields) {
 761       $sql =~ s/\?/cust_main_county.$_/;
 762       $sql =~ s/cust_main_county.$_ = ''/cust_main_county.$_ IS NULL/;
 763     }
 764     return $sql;
 765   }
 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_year') or return;
 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 =head1 BUGS
 909
 910 =head1 SEE ALSO
 911
 912 L<FS::cust_main_county>, L<FS::cust_pkg>, L<FS::Record>,
 913 schema.html from the base documentation.
 914
 915 =cut
 916
 917 1;
 918