1 package FS::cust_location;
2 use base qw( FS::geocode_Mixin FS::Record );
5 use vars qw( $import $DEBUG $conf $label_prefix $allow_location_edit );
7 use Date::Format qw( time2str );
8 use FS::UID qw( dbh driver_name );
9 use FS::Record qw( qsearch qsearchs );
11 use FS::prospect_main;
13 use FS::cust_main_county;
21 FS::UID->install_callback( sub {
22 $conf = FS::Conf->new;
23 $label_prefix = $conf->config('cust_location-label_prefix') || '';
28 FS::cust_location - Object methods for cust_location records
32 use FS::cust_location;
34 $record = new FS::cust_location \%hash;
35 $record = new FS::cust_location { 'column' => 'value' };
37 $error = $record->insert;
39 $error = $new_record->replace($old_record);
41 $error = $record->delete;
43 $error = $record->check;
47 An FS::cust_location object represents a customer (or prospect) location.
48 FS::cust_location inherits from FS::Record. The following fields are currently
59 Customer (see L<FS::cust_main>).
63 Prospect (see L<FS::prospect_main>).
67 Optional location name.
71 Address line one (required)
75 Address line two (optional)
79 City (if cust_main-no_city_in_address config is set when inserting, this will be forced blank)
83 County (optional, see L<FS::cust_main_county>)
87 State (see L<FS::cust_main_county>)
95 Country (see L<FS::cust_main_county>)
107 Flag indicating whether coordinates were obtained automatically or manually
112 Flag indicating whether address has been normalized
120 Tax district code (optional)
124 Incorporated city flag: set to 'Y' if the address is in the legal borders
125 of an incorporated city.
129 Disabled flag; set to 'Y' to disable the location.
139 Creates a new location. To add the location to the database, see L<"insert">.
141 Note that this stores the hash reference, not a distinct copy of the hash it
142 points to. You can ask the object for a copy with the I<hash> method.
146 sub table { 'cust_location'; }
150 Finds an existing location matching the customer and address values in this
151 location, if one exists, and sets the contents of this location equal to that
152 one (including its locationnum).
154 If an existing location is not found, this one I<will> be inserted. (This is a
155 change from the "new_or_existing" method that this replaces.)
157 The following fields are considered "essential" and I<must> match: custnum,
158 address1, address2, city, county, state, zip, country, location_number,
159 location_type, location_kind. Disabled locations will be found only if this
160 location is set to disabled.
162 All other fields are considered "non-essential" and will be ignored in
163 finding a matching location. If the existing location doesn't match
164 in these fields, it will be updated in-place to match.
166 Returns an error string if inserting or updating a location failed.
168 It is unfortunately hard to determine if this created a new location or not.
175 warn "find_or_insert:\n".Dumper($self) if $DEBUG;
177 my @essential = (qw(custnum address1 address2 city county state zip country
178 location_number location_type location_kind disabled));
180 if ($conf->exists('cust_main-no_city_in_address')) {
181 warn "Warning: passed city to find_or_insert when cust_main-no_city_in_address is configured, ignoring it"
182 if $self->get('city');
183 $self->set('city','');
186 # I don't think this is necessary
187 #if ( !$self->coord_auto and $self->latitude and $self->longitude ) {
188 # push @essential, qw(latitude longitude);
189 # # but NOT coord_auto; if the latitude and longitude match the geocoded
190 # # values then that's good enough
193 # put nonempty, nonessential fields/values into this hash
194 my %nonempty = map { $_ => $self->get($_) }
195 grep {$self->get($_)} $self->fields;
196 delete @nonempty{@essential};
197 delete $nonempty{'locationnum'};
199 my %hash = map { $_ => $self->get($_) } @essential;
200 foreach (values %hash) {
204 my @matches = qsearch('cust_location', \%hash);
206 # we no longer reject matches for having different values in nonessential
207 # fields; we just alter the record to match
209 my $old = $matches[0];
210 warn "found existing location #".$old->locationnum."\n" if $DEBUG;
211 foreach my $field (keys %nonempty) {
212 if ($old->get($field) ne $nonempty{$field}) {
213 warn "altering $field to match requested location" if $DEBUG;
214 $old->set($field, $nonempty{$field});
218 if ( $old->modified ) {
219 warn "updating non-essential fields\n" if $DEBUG;
220 my $error = $old->replace;
221 return $error if $error;
223 # set $self equal to $old
224 foreach ($self->fields) {
225 $self->set($_, $old->get($_));
230 # didn't find a match
231 warn "not found; inserting new location\n" if $DEBUG;
232 return $self->insert;
237 Adds this record to the database. If there is an error, returns the error,
238 otherwise returns false.
245 if ($conf->exists('cust_main-no_city_in_address')) {
246 warn "Warning: passed city to insert when cust_main-no_city_in_address is configured, ignoring it"
247 if $self->get('city');
248 $self->set('city','');
251 if ( $self->censustract ) {
252 $self->set('censusyear' => $conf->config('census_year') || 2012);
255 my $oldAutoCommit = $FS::UID::AutoCommit;
256 local $FS::UID::AutoCommit = 0;
259 my $error = $self->SUPER::insert(@_);
261 $dbh->rollback if $oldAutoCommit;
265 #false laziness with cust_main, will go away eventually
266 if ( !$import and $conf->config('tax_district_method') ) {
268 my $queue = new FS::queue {
269 'job' => 'FS::geocode_Mixin::process_district_update'
271 $error = $queue->insert( ref($self), $self->locationnum );
273 $dbh->rollback if $oldAutoCommit;
279 # cust_location exports
280 #my $export_args = $options{'export_args'} || [];
282 # don't export custnum_pending cases, let follow-up replace handle that
283 if ($self->custnum || $self->prospectnum) {
285 map qsearch( 'part_export', {exportnum=>$_} ),
286 $conf->config('cust_location-exports'); #, $agentnum
288 foreach my $part_export ( @part_export ) {
289 my $error = $part_export->export_insert($self); #, @$export_args);
291 $dbh->rollback if $oldAutoCommit;
292 return "exporting to ". $part_export->exporttype.
293 " (transaction rolled back): $error";
298 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
304 Delete this record from the database.
306 =item replace OLD_RECORD
308 Replaces the OLD_RECORD with this one in the database. If there is an error,
309 returns the error, otherwise returns false.
316 $old ||= $self->replace_old;
318 warn "Warning: passed city to replace when cust_main-no_city_in_address is configured"
319 if $conf->exists('cust_main-no_city_in_address') && $self->get('city');
321 # the following fields are immutable if this is a customer location. if
322 # it's a prospect location, then there are no active packages, no billing
323 # history, no taxes, and in general no reason to keep the old location
325 if ( !$allow_location_edit and $self->custnum ) {
326 foreach (qw(address1 address2 city state zip country)) {
327 if ( $self->$_ ne $old->$_ ) {
328 return "can't change cust_location field $_";
333 my $oldAutoCommit = $FS::UID::AutoCommit;
334 local $FS::UID::AutoCommit = 0;
337 my $error = $self->SUPER::replace($old);
339 $dbh->rollback if $oldAutoCommit;
343 # cust_location exports
344 #my $export_args = $options{'export_args'} || [];
346 # don't export custnum_pending cases, let follow-up replace handle that
347 if ($self->custnum || $self->prospectnum) {
349 map qsearch( 'part_export', {exportnum=>$_} ),
350 $conf->config('cust_location-exports'); #, $agentnum
352 foreach my $part_export ( @part_export ) {
353 my $error = $part_export->export_replace($self, $old); #, @$export_args);
355 $dbh->rollback if $oldAutoCommit;
356 return "exporting to ". $part_export->exporttype.
357 " (transaction rolled back): $error";
362 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
369 Checks all fields to make sure this is a valid location. If there is
370 an error, returns the error, otherwise returns false. Called by the insert
378 return '' if $self->disabled; # so that disabling locations never fails
380 # maybe should just do all fields in the table?
382 $self->trim_whitespace(qw(district city county state country));
385 $self->ut_numbern('locationnum')
386 || $self->ut_foreign_keyn('prospectnum', 'prospect_main', 'prospectnum')
387 || $self->ut_foreign_keyn('custnum', 'cust_main', 'custnum')
388 || $self->ut_textn('locationname')
389 || $self->ut_text('address1')
390 || $self->ut_textn('address2')
391 || ($conf->exists('cust_main-no_city_in_address')
392 ? $self->ut_textn('city')
393 : $self->ut_text('city'))
394 || $self->ut_textn('county')
395 || $self->ut_textn('state')
396 || $self->ut_country('country')
397 || (!$import && $self->ut_zip('zip', $self->country))
398 || $self->ut_coordn('latitude')
399 || $self->ut_coordn('longitude')
400 || $self->ut_enum('coord_auto', [ '', 'Y' ])
401 || $self->ut_enum('addr_clean', [ '', 'Y' ])
402 || $self->ut_alphan('location_type')
403 || $self->ut_textn('location_number')
404 || $self->ut_enum('location_kind', [ '', 'R', 'B' ] )
405 || $self->ut_alphan('geocode')
406 || $self->ut_alphan('district')
407 || $self->ut_numbern('censusyear')
408 || $self->ut_flag('incorporated')
410 return $error if $error;
411 if ( $self->censustract ne '' ) {
412 $self->censustract =~ /^\s*(\d{9})\.?(\d{2})\s*$/
413 or return "Illegal census tract: ". $self->censustract;
415 $self->censustract("$1.$2");
418 #yikes... this is ancient, pre-dates cust_location and will be harder to
419 # implement now... how do we know this location is a service location from
420 # here and not a billing? we can't just check locationnums, we might be new :/
421 return "Unit # is required"
422 if $conf->exists('cust_main-require_address2')
423 && ! $self->address2 =~ /\S/;
425 # tricky...we have to allow for the customer to not be inserted yet
426 return "No prospect or customer!" unless $self->prospectnum
428 || $self->get('custnum_pending');
429 return "Prospect and customer!" if $self->prospectnum && $self->custnum;
431 return 'Location kind is required'
432 if $self->prospectnum
433 && $conf->exists('prospect_main-alt_address_format')
434 && ! $self->location_kind;
436 unless ( $import or qsearch('cust_main_county', {
437 'country' => $self->country,
440 return "Unknown state/county/country: ".
441 $self->state. "/". $self->county. "/". $self->country
442 unless qsearch('cust_main_county',{
443 'state' => $self->state,
444 'county' => $self->county,
445 'country' => $self->country,
449 # set coordinates, unless we already have them
450 if (!$import and !$self->latitude and !$self->longitude) {
459 Returns this location's full country name
463 #moved to geocode_Mixin.pm
467 Synonym for location_label
473 $self->location_label(@_);
476 =item has_ship_address
478 Returns false since cust_location objects do not have a separate shipping
483 sub has_ship_address {
489 Returns a list of key/value pairs, with the following keys: address1, address2,
490 city, county, state, zip, country, geocode, location_type, location_number,
495 =item disable_if_unused
497 Sets the "disabled" flag on the location if it is no longer in use as a
498 prospect location, package location, or a customer's billing or default
503 sub disable_if_unused {
506 my $locationnum = $self->locationnum;
507 return '' if FS::cust_main->count('bill_locationnum = '.$locationnum.' OR
508 ship_locationnum = '.$locationnum)
509 or FS::contact->count( 'locationnum = '.$locationnum)
510 or FS::cust_pkg->count('cancel IS NULL AND
511 locationnum = '.$locationnum)
513 $self->disabled('Y');
520 Takes a new L<FS::cust_location> object. Moves all packages that use the
521 existing location to the new one, then sets the "disabled" flag on the old
522 location. Returns nothing on success, an error message on error.
530 warn "move_to:\nFROM:".Dumper($old)."\nTO:".Dumper($new) if $DEBUG;
532 local $SIG{HUP} = 'IGNORE';
533 local $SIG{INT} = 'IGNORE';
534 local $SIG{QUIT} = 'IGNORE';
535 local $SIG{TERM} = 'IGNORE';
536 local $SIG{TSTP} = 'IGNORE';
537 local $SIG{PIPE} = 'IGNORE';
539 my $oldAutoCommit = $FS::UID::AutoCommit;
540 local $FS::UID::AutoCommit = 0;
544 # prevent this from failing because of pkg_svc quantity limits
545 local( $FS::cust_svc::ignore_quantity ) = 1;
547 if ( !$new->locationnum ) {
548 $error = $new->insert;
550 $dbh->rollback if $oldAutoCommit;
551 return "Error creating location: $error";
553 } elsif ( $new->locationnum == $old->locationnum ) {
554 # then they're the same location; the normal result of doing a minor
556 $dbh->commit if $oldAutoCommit;
560 # find all packages that have the old location as their service address,
561 # and aren't canceled,
562 # and aren't supplemental to another package.
563 my @pkgs = qsearch('cust_pkg', {
564 'locationnum' => $old->locationnum,
568 foreach my $cust_pkg (@pkgs) {
569 # don't move one-time charges that have already been charged
570 next if $cust_pkg->part_pkg->freq eq '0'
571 and ($cust_pkg->setup || 0) > 0;
573 $error = $cust_pkg->change(
574 'locationnum' => $new->locationnum,
577 if ( $error and not ref($error) ) {
578 $dbh->rollback if $oldAutoCommit;
579 return "Error moving pkgnum ".$cust_pkg->pkgnum.": $error";
583 $error = $old->disable_if_unused;
585 $dbh->rollback if $oldAutoCommit;
586 return "Error disabling old location: $error";
589 $dbh->commit if $oldAutoCommit;
595 Attempts to parse data for location_type and location_number from address1
603 return '' if $self->get('location_type')
604 || $self->get('location_number');
607 if ( 1 ) { #ikano, switch on via config
608 { no warnings 'void';
609 eval { 'use FS::part_export::ikano;' };
612 %parse = FS::part_export::ikano->location_types_parse;
617 foreach my $from ('address1', 'address2') {
618 foreach my $parse ( keys %parse ) {
619 my $value = $self->get($from);
620 if ( $value =~ s/(^|\W+)$parse\W+(\w+)\W*$//i ) {
621 $self->set('location_type', $parse{$parse});
622 $self->set('location_number', $2);
623 $self->set($from, $value);
629 #nothing matched, no changes
630 $self->get('address2')
631 ? "Can't parse unit type and number from address2"
637 Moves data from location_type and location_number to the end of address1.
644 #false laziness w/geocode_Mixin.pm::line
645 my $lt = $self->get('location_type');
649 if ( 1 ) { #ikano, switch on via config
650 { no warnings 'void';
651 eval { 'use FS::part_export::ikano;' };
654 %location_type = FS::part_export::ikano->location_types;
656 %location_type = (); #?
659 $self->address1( $self->address1. ' '. $location_type{$lt} || $lt );
660 $self->location_type('');
663 if ( length($self->location_number) ) {
664 $self->address1( $self->address1. ' '. $self->location_number );
665 $self->location_number('');
673 Returns the label of the location object.
681 Customer object (see L<FS::cust_main>)
685 Prospect object (see L<FS::prospect_main>)
689 String used to join location elements
693 Don't label the default service location as "Default service location".
694 May become the default at some point.
701 my( $self, %opt ) = @_;
703 my $prefix = $self->label_prefix(%opt);
704 $prefix .= ($opt{join_string} || ': ') if $prefix;
705 $prefix = '' if $opt{'no_prefix'};
707 $prefix . $self->SUPER::location_label(%opt);
712 Returns the optional site ID string (based on the cust_location-label_prefix
713 config option), "Default service location", or the empty string.
721 Customer object (see L<FS::cust_main>)
725 Prospect object (see L<FS::prospect_main>)
732 my( $self, %opt ) = @_;
734 my $cust_or_prospect = $opt{cust_main} || $opt{prospect_main};
735 unless ( $cust_or_prospect ) {
736 if ( $self->custnum ) {
737 $cust_or_prospect = FS::cust_main->by_key($self->custnum);
738 } elsif ( $self->prospectnum ) {
739 $cust_or_prospect = FS::prospect_main->by_key($self->prospectnum);
744 if ( $label_prefix eq 'CoStAg' ) {
745 my $agent = $conf->config('cust_main-custnum-display_prefix',
746 $cust_or_prospect->agentnum)
747 || $cust_or_prospect->agent->agent;
748 # else this location is invalid
749 $prefix = uc( join('',
751 ($self->state =~ /^(..)/),
753 sprintf('%05d', $self->locationnum)
756 } elsif ( $label_prefix eq '_location' && $self->locationname ) {
757 $prefix = $self->locationname;
759 #} elsif ( ( $opt{'cust_main'} || $self->custnum )
760 # && $self->locationnum == $cust_or_prospect->ship_locationnum ) {
761 # $prefix = 'Default service location';
770 =item county_state_country
772 Returns a string consisting of just the county, state and country.
776 sub county_state_country {
778 my $label = $self->country;
779 $label = $self->state.", $label" if $self->state;
780 $label = $self->county." County, $label" if $self->county;
790 =item process_censustract_update LOCATIONNUM
792 Queueable function to update the census tract to the current year (as set in
793 the 'census_year' configuration variable) and retrieve the new tract code.
797 sub process_censustract_update {
798 eval "use FS::GeocodeCache";
800 my $locationnum = shift;
802 qsearchs( 'cust_location', { locationnum => $locationnum })
803 or die "locationnum '$locationnum' not found!\n";
805 my $new_year = $conf->config('census_year') or return;
806 my $loc = FS::GeocodeCache->new( $cust_location->location_hash );
807 $loc->set_censustract;
808 my $error = $loc->get('censustract_error');
809 die $error if $error;
810 $cust_location->set('censustract', $loc->get('censustract'));
811 $cust_location->set('censusyear', $new_year);
812 $error = $cust_location->replace;
813 die $error if $error;
817 =item process_set_coord
819 Queueable function to find and fill in coordinates for all locations that
820 lack them. Because this uses the Google Maps API, it's internally rate
821 limited and must run in a single process.
825 sub process_set_coord {
827 # avoid starting multiple instances of this job
828 my @others = qsearch('queue', {
829 'status' => 'locked',
831 'jobnum' => {op=>'!=', value=>$job->jobnum},
835 $job->update_statustext('finding locations to update');
836 my @missing_coords = qsearch('cust_location', {
842 my $n = scalar @missing_coords;
843 for my $cust_location (@missing_coords) {
844 $cust_location->set_coord;
845 my $error = $cust_location->replace;
847 warn "error geocoding location#".$cust_location->locationnum.": $error\n";
850 $job->update_statustext("updated $i / $n locations");
851 dbh->commit; # so that we don't have to wait for the whole thing to finish
852 # Rate-limit to stay under the Google Maps usage limit (2500/day).
853 # 86,400 / 35 = 2,468 lookups per day.
858 die "failed to update ".$n-$i." locations\n";
863 =item process_standardize [ LOCATIONNUMS ]
865 Performs address standardization on locations with unclean addresses,
866 using whatever method you have configured. If the standardize_* method
867 returns a I<clean> address match, the location will be updated. This is
868 always an in-place update (because the physical location is the same,
869 and is just being referred to by a more accurate name).
871 Disabled locations will be skipped, as nobody cares.
873 If any LOCATIONNUMS are provided, only those locations will be updated.
877 sub process_standardize {
879 my @others = qsearch('queue', {
880 'status' => 'locked',
882 'jobnum' => {op=>'!=', value=>$job->jobnum},
885 my @locationnums = grep /^\d+$/, @_;
886 my $where = "AND locationnum IN(".join(',',@locationnums).")"
887 if scalar(@locationnums);
888 my @locations = qsearch({
889 table => 'cust_location',
890 hashref => { addr_clean => '', disabled => '' },
893 my $n_todo = scalar(@locations);
898 eval "use Text::CSV";
899 open $log, '>', "$FS::UID::cache_dir/process_standardize-" .
900 time2str('%Y%m%d',time) .
902 my $csv = Text::CSV->new({binary => 1, eol => "\n"});
904 foreach my $cust_location (@locations) {
905 $job->update_statustext( int(100 * $n_done/$n_todo) . ",$n_done / $n_todo locations" ) if $job;
906 my $result = FS::GeocodeCache->standardize($cust_location);
907 if ( $result->{addr_clean} and !$result->{error} ) {
908 my @cols = ($cust_location->locationnum);
909 foreach (keys %$result) {
910 push @cols, $cust_location->get($_), $result->{$_};
911 $cust_location->set($_, $result->{$_});
913 # bypass immutable field restrictions
914 my $error = $cust_location->FS::Record::replace;
915 warn "location ".$cust_location->locationnum.": $error\n" if $error;
916 $csv->print($log, \@cols);
919 dbh->commit; # so that we can resume if interrupted
927 # are we going to need to update tax districts?
928 my $use_districts = $conf->config('tax_district_method') ? 1 : 0;
930 # trim whitespace on records that need it
931 local $allow_location_edit = 1;
932 foreach my $field (qw(city county state country district)) {
933 foreach my $location (qsearch({
934 table => 'cust_location',
935 extra_sql => " WHERE $field LIKE ' %' OR $field LIKE '% '"
937 my $error = $location->replace;
938 die "$error (fixing whitespace in $field, locationnum ".$location->locationnum.')'
941 if ( $use_districts ) {
942 my $queue = new FS::queue {
943 'job' => 'FS::geocode_Mixin::process_district_update'
945 $error = $queue->insert( 'FS::cust_location' => $location->locationnum );
946 die $error if $error;
948 } # foreach $location
957 L<FS::cust_main_county>, L<FS::cust_pkg>, L<FS::Record>,
958 schema.html from the base documentation.