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;
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));
27 FS::UID->install_callback( sub {
28 $conf = FS::Conf->new;
29 $label_prefix = $conf->config('cust_location-label_prefix') || '';
34 FS::cust_location - Object methods for cust_location records
38 use FS::cust_location;
40 $record = new FS::cust_location \%hash;
41 $record = new FS::cust_location { 'column' => 'value' };
43 $error = $record->insert;
45 $error = $new_record->replace($old_record);
47 $error = $record->delete;
49 $error = $record->check;
53 An FS::cust_location object represents a customer location. FS::cust_location
54 inherits from FS::Record. The following fields are currently supported:
68 Address line one (required)
72 Address line two (optional)
76 City (if cust_main-no_city_in_address config is set when inserting, this will be forced blank)
80 County (optional, see L<FS::cust_main_county>)
84 State (see L<FS::cust_main_county>)
92 Country (see L<FS::cust_main_county>)
100 Tax district code (optional)
104 Disabled flag; set to 'Y' to disable the location.
114 Creates a new location. To add the location to the database, see L<"insert">.
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.
121 sub table { 'cust_location'; }
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).
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.)
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.
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.
141 Returns an error string if inserting or updating a location failed.
143 It is unfortunately hard to determine if this created a new location or not.
150 warn "find_or_insert:\n".Dumper($self) if $DEBUG;
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','');
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
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'};
171 my %hash = map { $_ => $self->get($_) } @essential;
172 foreach (values %hash) {
176 my @matches = qsearch('cust_location', \%hash);
178 # we no longer reject matches for having different values in nonessential
179 # fields; we just alter the record to match
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});
190 if ( $old->modified ) {
191 warn "updating non-essential fields\n" if $DEBUG;
192 my $error = $old->replace;
193 return $error if $error;
195 # set $self equal to $old
196 foreach ($self->fields) {
197 $self->set($_, $old->get($_));
202 # didn't find a match
203 warn "not found; inserting new location\n" if $DEBUG;
204 return $self->insert;
209 Adds this record to the database. If there is an error, returns the error,
210 otherwise returns false.
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','');
223 if ( $self->censustract ) {
224 $self->set('censusyear' => $conf->config('census_legacy') || 2020);
227 my $oldAutoCommit = $FS::UID::AutoCommit;
228 local $FS::UID::AutoCommit = 0;
231 my $error = $self->SUPER::insert(@_);
233 $dbh->rollback if $oldAutoCommit;
237 #false laziness with cust_main, will go away eventually
238 if ( !$import and $conf->config('tax_district_method') ) {
240 my $queue = new FS::queue {
241 'job' => 'FS::geocode_Mixin::process_district_update'
243 $error = $queue->insert( ref($self), $self->locationnum );
245 $dbh->rollback if $oldAutoCommit;
251 # cust_location exports
252 #my $export_args = $options{'export_args'} || [];
254 # don't export custnum_pending cases, let follow-up replace handle that
255 if ($self->custnum || $self->prospectnum) {
257 map qsearch( 'part_export', {exportnum=>$_} ),
258 $conf->config('cust_location-exports'); #, $agentnum
260 foreach my $part_export ( @part_export ) {
261 my $error = $part_export->export_insert($self); #, @$export_args);
263 $dbh->rollback if $oldAutoCommit;
264 return "exporting to ". $part_export->exporttype.
265 " (transaction rolled back): $error";
270 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
276 Delete this record from the database.
278 =item replace OLD_RECORD
280 Replaces the OLD_RECORD with this one in the database. If there is an error,
281 returns the error, otherwise returns false.
288 $old ||= $self->replace_old;
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');
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
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 $_";
305 my $oldAutoCommit = $FS::UID::AutoCommit;
306 local $FS::UID::AutoCommit = 0;
309 my $error = $self->SUPER::replace($old);
311 $dbh->rollback if $oldAutoCommit;
315 # cust_location exports
316 #my $export_args = $options{'export_args'} || [];
318 # don't export custnum_pending cases, let follow-up replace handle that
319 if ($self->custnum || $self->prospectnum) {
321 map qsearch( 'part_export', {exportnum=>$_} ),
322 $conf->config('cust_location-exports'); #, $agentnum
324 foreach my $part_export ( @part_export ) {
325 my $error = $part_export->export_replace($self, $old); #, @$export_args);
327 $dbh->rollback if $oldAutoCommit;
328 return "exporting to ". $part_export->exporttype.
329 " (transaction rolled back): $error";
334 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
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
350 return '' if $self->disabled; # so that disabling locations never fails
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);
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')
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);
388 return "Illegal census tract: ". $self->censustract;
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/;
399 # tricky...we have to allow for the customer to not be inserted yet
400 return "No prospect or customer!" unless $self->prospectnum
402 || $self->get('custnum_pending');
403 return "Prospect and customer!" if $self->prospectnum && $self->custnum;
405 return 'Location kind is required'
406 if $self->prospectnum
407 && $conf->exists('prospect_main-alt_address_format')
408 && ! $self->location_kind;
410 unless ( $import or qsearch('cust_main_county', {
411 'country' => $self->country,
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,
423 # set coordinates, unless we already have them
424 if (!$import and !$self->latitude and !$self->longitude) {
433 Returns this location's full country name
437 #moved to geocode_Mixin.pm
441 Synonym for location_label
447 $self->location_label(@_);
450 =item has_ship_address
452 Returns false since cust_location objects do not have a separate shipping
457 sub has_ship_address {
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,
469 =item disable_if_unused
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
477 sub disable_if_unused {
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)
487 $self->disabled('Y');
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.
504 warn "move_to:\nFROM:".Dumper($old)."\nTO:".Dumper($new) if $DEBUG;
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';
513 my $oldAutoCommit = $FS::UID::AutoCommit;
514 local $FS::UID::AutoCommit = 0;
518 # prevent this from failing because of pkg_svc quantity limits
519 local( $FS::cust_svc::ignore_quantity ) = 1;
521 if ( !$new->locationnum ) {
522 $error = $new->insert;
524 $dbh->rollback if $oldAutoCommit;
525 return "Error creating location: $error";
527 } elsif ( $new->locationnum == $old->locationnum ) {
528 # then they're the same location; the normal result of doing a minor
530 $dbh->commit if $oldAutoCommit;
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,
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;
547 $error = $cust_pkg->change(
548 'locationnum' => $new->locationnum,
551 if ( $error and not ref($error) ) {
552 $dbh->rollback if $oldAutoCommit;
553 return "Error moving pkgnum ".$cust_pkg->pkgnum.": $error";
557 $error = $old->disable_if_unused;
559 $dbh->rollback if $oldAutoCommit;
560 return "Error disabling old location: $error";
563 $dbh->commit if $oldAutoCommit;
569 Attempts to parse data for location_type and location_number from address1
577 return '' if $self->get('location_type')
578 || $self->get('location_number');
581 if ( 1 ) { #ikano, switch on via config
582 { no warnings 'void';
583 eval { 'use FS::part_export::ikano;' };
586 %parse = FS::part_export::ikano->location_types_parse;
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);
603 #nothing matched, no changes
604 $self->get('address2')
605 ? "Can't parse unit type and number from address2"
611 Moves data from location_type and location_number to the end of address1.
618 #false laziness w/geocode_Mixin.pm::line
619 my $lt = $self->get('location_type');
623 if ( 1 ) { #ikano, switch on via config
624 { no warnings 'void';
625 eval { 'use FS::part_export::ikano;' };
628 %location_type = FS::part_export::ikano->location_types;
630 %location_type = (); #?
633 $self->address1( $self->address1. ' '. $location_type{$lt} || $lt );
634 $self->location_type('');
637 if ( length($self->location_number) ) {
638 $self->address1( $self->address1. ' '. $self->location_number );
639 $self->location_number('');
647 Returns the label of the location object.
655 Customer object (see L<FS::cust_main>)
659 Prospect object (see L<FS::prospect_main>)
663 String used to join location elements
667 Don't label the default service location as "Default service location".
668 May become the default at some point.
675 my( $self, %opt ) = @_;
677 my $prefix = $self->label_prefix;
678 $prefix .= ($opt{join_string} || ': ') if $prefix;
679 $prefix = '' if $opt{'no_prefix'};
681 $prefix . $self->SUPER::location_label(%opt);
686 Returns the optional site ID string (based on the cust_location-label_prefix
687 config option), "Default service location", or the empty string.
695 Customer object (see L<FS::cust_main>)
699 Prospect object (see L<FS::prospect_main>)
706 my( $self, %opt ) = @_;
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);
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('',
725 ($self->state =~ /^(..)/),
727 sprintf('%05d', $self->locationnum)
730 } elsif ( $label_prefix eq '_location' && $self->locationname ) {
731 $prefix = $self->locationname;
733 #} elsif ( ( $opt{'cust_main'} || $self->custnum )
734 # && $self->locationnum == $cust_or_prospect->ship_locationnum ) {
735 # $prefix = 'Default service location';
744 =item county_state_country
746 Returns a string consisting of just the county, state and country.
750 sub county_state_country {
752 my $label = $self->country;
753 $label = $self->state.", $label" if $self->state;
754 $label = $self->county." County, $label" if $self->county;
764 return '' unless $self->custnum;
765 qsearchs('cust_main', { 'custnum' => $self->custnum } );
774 =item process_censustract_update LOCATIONNUM
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.
781 sub process_censustract_update {
782 eval "use FS::GeocodeCache";
784 my $locationnum = shift;
786 qsearchs( 'cust_location', { locationnum => $locationnum })
787 or die "locationnum '$locationnum' not found!\n";
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;
801 =item process_set_coord
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.
809 sub process_set_coord {
811 # avoid starting multiple instances of this job
812 my @others = qsearch('queue', {
813 'status' => 'locked',
815 'jobnum' => {op=>'!=', value=>$job->jobnum},
819 $job->update_statustext('finding locations to update');
820 my @missing_coords = qsearch('cust_location', {
826 my $n = scalar @missing_coords;
827 for my $cust_location (@missing_coords) {
828 $cust_location->set_coord;
829 my $error = $cust_location->replace;
831 warn "error geocoding location#".$cust_location->locationnum.": $error\n";
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.
842 die "failed to update ".$n-$i." locations\n";
847 =item process_standardize [ LOCATIONNUMS ]
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).
855 Disabled locations will be skipped, as nobody cares.
857 If any LOCATIONNUMS are provided, only those locations will be updated.
861 sub process_standardize {
863 my @others = qsearch('queue', {
864 'status' => 'locked',
866 'jobnum' => {op=>'!=', value=>$job->jobnum},
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 => '' },
877 my $n_todo = scalar(@locations);
882 eval "use Text::CSV";
883 open $log, '>', "$FS::UID::cache_dir/process_standardize-" .
884 time2str('%Y%m%d',time) .
886 my $csv = Text::CSV->new({binary => 1, eol => "\n"});
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->{$_});
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);
903 dbh->commit; # so that we can resume if interrupted
911 # are we going to need to update tax districts?
912 my $use_districts = $conf->config('tax_district_method') ? 1 : 0;
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 '% ')"
923 my $error = $location->replace;
924 die "$error (fixing whitespace in $field, locationnum ".$location->locationnum.')'
927 if ( $use_districts ) {
928 my $queue = new FS::queue {
929 'job' => 'FS::geocode_Mixin::process_district_update'
931 $error = $queue->insert( 'FS::cust_location' => $location->locationnum );
932 die $error if $error;
934 } # foreach $location
943 L<FS::cust_main_county>, L<FS::cust_pkg>, L<FS::Record>,
944 schema.html from the base documentation.