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 (or prospect) location.
54 FS::cust_location inherits from FS::Record. The following fields are currently
65 Customer (see L<FS::cust_main>).
69 Prospect (see L<FS::prospect_main>).
73 Optional location name.
77 Address line one (required)
81 Address line two (optional)
85 City (if cust_main-no_city_in_address config is set when inserting, this will be forced blank)
89 County (optional, see L<FS::cust_main_county>)
93 State (see L<FS::cust_main_county>)
101 Country (see L<FS::cust_main_county>)
113 Flag indicating whether coordinates were obtained automatically or manually
118 Flag indicating whether address has been normalized
126 Tax district code (optional)
130 Incorporated city flag: set to 'Y' if the address is in the legal borders
131 of an incorporated city.
135 Disabled flag; set to 'Y' to disable the location.
145 Creates a new location. To add the location to the database, see L<"insert">.
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.
152 sub table { 'cust_location'; }
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).
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.)
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.
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.
172 Returns an error string if inserting or updating a location failed.
174 It is unfortunately hard to determine if this created a new location or not.
181 warn "find_or_insert:\n".Dumper($self) if $DEBUG;
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','');
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
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'};
202 my %hash = map { $_ => $self->get($_) } @essential;
203 foreach (values %hash) {
207 my @matches = qsearch('cust_location', \%hash);
209 # we no longer reject matches for having different values in nonessential
210 # fields; we just alter the record to match
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});
221 if ( $old->modified ) {
222 warn "updating non-essential fields\n" if $DEBUG;
223 my $error = $old->replace;
224 return $error if $error;
226 # set $self equal to $old
227 foreach ($self->fields) {
228 $self->set($_, $old->get($_));
233 # didn't find a match
234 warn "not found; inserting new location\n" if $DEBUG;
235 return $self->insert;
240 Adds this record to the database. If there is an error, returns the error,
241 otherwise returns false.
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','');
254 if ( $self->censustract ) {
255 $self->set('censusyear' => $conf->config('census_year') || 2012);
258 my $oldAutoCommit = $FS::UID::AutoCommit;
259 local $FS::UID::AutoCommit = 0;
262 my $error = $self->SUPER::insert(@_);
264 $dbh->rollback if $oldAutoCommit;
268 #false laziness with cust_main, will go away eventually
269 if ( !$import and $conf->config('tax_district_method') ) {
271 my $queue = new FS::queue {
272 'job' => 'FS::geocode_Mixin::process_district_update'
274 $error = $queue->insert( ref($self), $self->locationnum );
276 $dbh->rollback if $oldAutoCommit;
282 # cust_location exports
283 #my $export_args = $options{'export_args'} || [];
285 # don't export custnum_pending cases, let follow-up replace handle that
286 if ($self->custnum || $self->prospectnum) {
288 map qsearch( 'part_export', {exportnum=>$_} ),
289 $conf->config('cust_location-exports'); #, $agentnum
291 foreach my $part_export ( @part_export ) {
292 my $error = $part_export->export_insert($self); #, @$export_args);
294 $dbh->rollback if $oldAutoCommit;
295 return "exporting to ". $part_export->exporttype.
296 " (transaction rolled back): $error";
301 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
307 Delete this record from the database.
309 =item replace OLD_RECORD
311 Replaces the OLD_RECORD with this one in the database. If there is an error,
312 returns the error, otherwise returns false.
319 $old ||= $self->replace_old;
321 warn "Warning: passed city to replace when cust_main-no_city_in_address is configured"
322 if $conf->exists('cust_main-no_city_in_address') && $self->get('city');
324 # the following fields are immutable if this is a customer location. if
325 # it's a prospect location, then there are no active packages, no billing
326 # history, no taxes, and in general no reason to keep the old location
328 if ( !$allow_location_edit and $self->custnum ) {
329 foreach (qw(address1 address2 city state zip country)) {
330 if ( $self->$_ ne $old->$_ ) {
331 return "can't change cust_location field $_";
336 my $oldAutoCommit = $FS::UID::AutoCommit;
337 local $FS::UID::AutoCommit = 0;
340 my $error = $self->SUPER::replace($old);
342 $dbh->rollback if $oldAutoCommit;
346 # cust_location exports
347 #my $export_args = $options{'export_args'} || [];
349 # don't export custnum_pending cases, let follow-up replace handle that
350 if ($self->custnum || $self->prospectnum) {
352 map qsearch( 'part_export', {exportnum=>$_} ),
353 $conf->config('cust_location-exports'); #, $agentnum
355 foreach my $part_export ( @part_export ) {
356 my $error = $part_export->export_replace($self, $old); #, @$export_args);
358 $dbh->rollback if $oldAutoCommit;
359 return "exporting to ". $part_export->exporttype.
360 " (transaction rolled back): $error";
365 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
372 Checks all fields to make sure this is a valid location. If there is
373 an error, returns the error, otherwise returns false. Called by the insert
381 return '' if $self->disabled; # so that disabling locations never fails
383 # whitespace in essential fields leads to problems figuring out if a
384 # record is "new"; get rid of it.
385 $self->trim_whitespace(@essential);
388 $self->ut_numbern('locationnum')
389 || $self->ut_foreign_keyn('prospectnum', 'prospect_main', 'prospectnum')
390 || $self->ut_foreign_keyn('custnum', 'cust_main', 'custnum')
391 || $self->ut_textn('locationname')
392 || $self->ut_text('address1')
393 || $self->ut_textn('address2')
394 || ($conf->exists('cust_main-no_city_in_address')
395 ? $self->ut_textn('city')
396 : $self->ut_text('city'))
397 || $self->ut_textn('county')
398 || $self->ut_textn('state')
399 || $self->ut_country('country')
400 || (!$import && $self->ut_zip('zip', $self->country))
401 || $self->ut_coordn('latitude')
402 || $self->ut_coordn('longitude')
403 || $self->ut_enum('coord_auto', [ '', 'Y' ])
404 || $self->ut_enum('addr_clean', [ '', 'Y' ])
405 || $self->ut_alphan('location_type')
406 || $self->ut_textn('location_number')
407 || $self->ut_enum('location_kind', [ '', 'R', 'B' ] )
408 || $self->ut_alphan('geocode')
409 || $self->ut_alphan('district')
410 || $self->ut_numbern('censusyear')
411 || $self->ut_flag('incorporated')
413 return $error if $error;
414 if ( $self->censustract ne '' ) {
415 $self->censustract =~ /^\s*(\d{9})\.?(\d{2})\s*$/
416 or return "Illegal census tract: ". $self->censustract;
418 $self->censustract("$1.$2");
421 #yikes... this is ancient, pre-dates cust_location and will be harder to
422 # implement now... how do we know this location is a service location from
423 # here and not a billing? we can't just check locationnums, we might be new :/
424 return "Unit # is required"
425 if $conf->exists('cust_main-require_address2')
426 && ! $self->address2 =~ /\S/;
428 # tricky...we have to allow for the customer to not be inserted yet
429 return "No prospect or customer!" unless $self->prospectnum
431 || $self->get('custnum_pending');
432 return "Prospect and customer!" if $self->prospectnum && $self->custnum;
434 return 'Location kind is required'
435 if $self->prospectnum
436 && $conf->exists('prospect_main-alt_address_format')
437 && ! $self->location_kind;
439 unless ( $import or qsearch('cust_main_county', {
440 'country' => $self->country,
443 return "Unknown state/county/country: ".
444 $self->state. "/". $self->county. "/". $self->country
445 unless qsearch('cust_main_county',{
446 'state' => $self->state,
447 'county' => $self->county,
448 'country' => $self->country,
452 # set coordinates, unless we already have them
453 if (!$import and !$self->latitude and !$self->longitude) {
462 Returns this location's full country name
466 #moved to geocode_Mixin.pm
470 Synonym for location_label
476 $self->location_label(@_);
479 =item has_ship_address
481 Returns false since cust_location objects do not have a separate shipping
486 sub has_ship_address {
492 Returns a list of key/value pairs, with the following keys: address1, address2,
493 city, county, state, zip, country, geocode, location_type, location_number,
498 =item disable_if_unused
500 Sets the "disabled" flag on the location if it is no longer in use as a
501 prospect location, package location, or a customer's billing or default
506 sub disable_if_unused {
509 my $locationnum = $self->locationnum;
510 return '' if FS::cust_main->count('bill_locationnum = '.$locationnum.' OR
511 ship_locationnum = '.$locationnum)
512 or FS::contact->count( 'locationnum = '.$locationnum)
513 or FS::cust_pkg->count('cancel IS NULL AND
514 locationnum = '.$locationnum)
516 $self->disabled('Y');
523 Takes a new L<FS::cust_location> object. Moves all packages that use the
524 existing location to the new one, then sets the "disabled" flag on the old
525 location. Returns nothing on success, an error message on error.
533 warn "move_to:\nFROM:".Dumper($old)."\nTO:".Dumper($new) if $DEBUG;
535 local $SIG{HUP} = 'IGNORE';
536 local $SIG{INT} = 'IGNORE';
537 local $SIG{QUIT} = 'IGNORE';
538 local $SIG{TERM} = 'IGNORE';
539 local $SIG{TSTP} = 'IGNORE';
540 local $SIG{PIPE} = 'IGNORE';
542 my $oldAutoCommit = $FS::UID::AutoCommit;
543 local $FS::UID::AutoCommit = 0;
547 # prevent this from failing because of pkg_svc quantity limits
548 local( $FS::cust_svc::ignore_quantity ) = 1;
550 if ( !$new->locationnum ) {
551 $error = $new->insert;
553 $dbh->rollback if $oldAutoCommit;
554 return "Error creating location: $error";
556 } elsif ( $new->locationnum == $old->locationnum ) {
557 # then they're the same location; the normal result of doing a minor
559 $dbh->commit if $oldAutoCommit;
563 # find all packages that have the old location as their service address,
564 # and aren't canceled,
565 # and aren't supplemental to another package.
566 my @pkgs = qsearch('cust_pkg', {
567 'locationnum' => $old->locationnum,
571 foreach my $cust_pkg (@pkgs) {
572 # don't move one-time charges that have already been charged
573 next if $cust_pkg->part_pkg->freq eq '0'
574 and ($cust_pkg->setup || 0) > 0;
576 $error = $cust_pkg->change(
577 'locationnum' => $new->locationnum,
580 if ( $error and not ref($error) ) {
581 $dbh->rollback if $oldAutoCommit;
582 return "Error moving pkgnum ".$cust_pkg->pkgnum.": $error";
586 $error = $old->disable_if_unused;
588 $dbh->rollback if $oldAutoCommit;
589 return "Error disabling old location: $error";
592 $dbh->commit if $oldAutoCommit;
598 Attempts to parse data for location_type and location_number from address1
606 return '' if $self->get('location_type')
607 || $self->get('location_number');
610 if ( 1 ) { #ikano, switch on via config
611 { no warnings 'void';
612 eval { 'use FS::part_export::ikano;' };
615 %parse = FS::part_export::ikano->location_types_parse;
620 foreach my $from ('address1', 'address2') {
621 foreach my $parse ( keys %parse ) {
622 my $value = $self->get($from);
623 if ( $value =~ s/(^|\W+)$parse\W+(\w+)\W*$//i ) {
624 $self->set('location_type', $parse{$parse});
625 $self->set('location_number', $2);
626 $self->set($from, $value);
632 #nothing matched, no changes
633 $self->get('address2')
634 ? "Can't parse unit type and number from address2"
640 Moves data from location_type and location_number to the end of address1.
647 #false laziness w/geocode_Mixin.pm::line
648 my $lt = $self->get('location_type');
652 if ( 1 ) { #ikano, switch on via config
653 { no warnings 'void';
654 eval { 'use FS::part_export::ikano;' };
657 %location_type = FS::part_export::ikano->location_types;
659 %location_type = (); #?
662 $self->address1( $self->address1. ' '. $location_type{$lt} || $lt );
663 $self->location_type('');
666 if ( length($self->location_number) ) {
667 $self->address1( $self->address1. ' '. $self->location_number );
668 $self->location_number('');
676 Returns the label of the location object.
684 Customer object (see L<FS::cust_main>)
688 Prospect object (see L<FS::prospect_main>)
692 String used to join location elements
696 Don't label the default service location as "Default service location".
697 May become the default at some point.
704 my( $self, %opt ) = @_;
706 my $prefix = $self->label_prefix(%opt);
707 $prefix .= ($opt{join_string} || ': ') if $prefix;
708 $prefix = '' if $opt{'no_prefix'};
710 $prefix . $self->SUPER::location_label(%opt);
715 Returns the optional site ID string (based on the cust_location-label_prefix
716 config option), "Default service location", or the empty string.
724 Customer object (see L<FS::cust_main>)
728 Prospect object (see L<FS::prospect_main>)
735 my( $self, %opt ) = @_;
737 my $cust_or_prospect = $opt{cust_main} || $opt{prospect_main};
738 unless ( $cust_or_prospect ) {
739 if ( $self->custnum ) {
740 $cust_or_prospect = FS::cust_main->by_key($self->custnum);
741 } elsif ( $self->prospectnum ) {
742 $cust_or_prospect = FS::prospect_main->by_key($self->prospectnum);
747 if ( $label_prefix eq 'CoStAg' ) {
748 my $agent = $conf->config('cust_main-custnum-display_prefix',
749 $cust_or_prospect->agentnum)
750 || $cust_or_prospect->agent->agent;
751 # else this location is invalid
752 $prefix = uc( join('',
754 ($self->state =~ /^(..)/),
756 sprintf('%05d', $self->locationnum)
759 } elsif ( $label_prefix eq '_location' && $self->locationname ) {
760 $prefix = $self->locationname;
762 #} elsif ( ( $opt{'cust_main'} || $self->custnum )
763 # && $self->locationnum == $cust_or_prospect->ship_locationnum ) {
764 # $prefix = 'Default service location';
773 =item county_state_country
775 Returns a string consisting of just the county, state and country.
779 sub county_state_country {
781 my $label = $self->country;
782 $label = $self->state.", $label" if $self->state;
783 $label = $self->county." County, $label" if $self->county;
793 =item process_censustract_update LOCATIONNUM
795 Queueable function to update the census tract to the current year (as set in
796 the 'census_year' configuration variable) and retrieve the new tract code.
800 sub process_censustract_update {
801 eval "use FS::GeocodeCache";
803 my $locationnum = shift;
805 qsearchs( 'cust_location', { locationnum => $locationnum })
806 or die "locationnum '$locationnum' not found!\n";
808 my $new_year = $conf->config('census_year') or return;
809 my $loc = FS::GeocodeCache->new( $cust_location->location_hash );
810 $loc->set_censustract;
811 my $error = $loc->get('censustract_error');
812 die $error if $error;
813 $cust_location->set('censustract', $loc->get('censustract'));
814 $cust_location->set('censusyear', $new_year);
815 $error = $cust_location->replace;
816 die $error if $error;
820 =item process_set_coord
822 Queueable function to find and fill in coordinates for all locations that
823 lack them. Because this uses the Google Maps API, it's internally rate
824 limited and must run in a single process.
828 sub process_set_coord {
830 # avoid starting multiple instances of this job
831 my @others = qsearch('queue', {
832 'status' => 'locked',
834 'jobnum' => {op=>'!=', value=>$job->jobnum},
838 $job->update_statustext('finding locations to update');
839 my @missing_coords = qsearch('cust_location', {
845 my $n = scalar @missing_coords;
846 for my $cust_location (@missing_coords) {
847 $cust_location->set_coord;
848 my $error = $cust_location->replace;
850 warn "error geocoding location#".$cust_location->locationnum.": $error\n";
853 $job->update_statustext("updated $i / $n locations");
854 dbh->commit; # so that we don't have to wait for the whole thing to finish
855 # Rate-limit to stay under the Google Maps usage limit (2500/day).
856 # 86,400 / 35 = 2,468 lookups per day.
861 die "failed to update ".$n-$i." locations\n";
866 =item process_standardize [ LOCATIONNUMS ]
868 Performs address standardization on locations with unclean addresses,
869 using whatever method you have configured. If the standardize_* method
870 returns a I<clean> address match, the location will be updated. This is
871 always an in-place update (because the physical location is the same,
872 and is just being referred to by a more accurate name).
874 Disabled locations will be skipped, as nobody cares.
876 If any LOCATIONNUMS are provided, only those locations will be updated.
880 sub process_standardize {
882 my @others = qsearch('queue', {
883 'status' => 'locked',
885 'jobnum' => {op=>'!=', value=>$job->jobnum},
888 my @locationnums = grep /^\d+$/, @_;
889 my $where = "AND locationnum IN(".join(',',@locationnums).")"
890 if scalar(@locationnums);
891 my @locations = qsearch({
892 table => 'cust_location',
893 hashref => { addr_clean => '', disabled => '' },
896 my $n_todo = scalar(@locations);
901 eval "use Text::CSV";
902 open $log, '>', "$FS::UID::cache_dir/process_standardize-" .
903 time2str('%Y%m%d',time) .
905 my $csv = Text::CSV->new({binary => 1, eol => "\n"});
907 foreach my $cust_location (@locations) {
908 $job->update_statustext( int(100 * $n_done/$n_todo) . ",$n_done / $n_todo locations" ) if $job;
909 my $result = FS::GeocodeCache->standardize($cust_location);
910 if ( $result->{addr_clean} and !$result->{error} ) {
911 my @cols = ($cust_location->locationnum);
912 foreach (keys %$result) {
913 push @cols, $cust_location->get($_), $result->{$_};
914 $cust_location->set($_, $result->{$_});
916 # bypass immutable field restrictions
917 my $error = $cust_location->FS::Record::replace;
918 warn "location ".$cust_location->locationnum.": $error\n" if $error;
919 $csv->print($log, \@cols);
922 dbh->commit; # so that we can resume if interrupted
930 # are we going to need to update tax districts?
931 my $use_districts = $conf->config('tax_district_method') ? 1 : 0;
933 # trim whitespace on records that need it
934 local $allow_location_edit = 1;
935 foreach my $field (@essential) {
936 next if $field eq 'custnum';
937 next if $field eq 'disabled';
938 foreach my $location (qsearch({
939 table => 'cust_location',
940 extra_sql => " WHERE $field LIKE ' %' OR $field LIKE '% '"
942 my $error = $location->replace;
943 die "$error (fixing whitespace in $field, locationnum ".$location->locationnum.')'
946 if ( $use_districts ) {
947 my $queue = new FS::queue {
948 'job' => 'FS::geocode_Mixin::process_district_update'
950 $error = $queue->insert( 'FS::cust_location' => $location->locationnum );
951 die $error if $error;
953 } # foreach $location
962 L<FS::cust_main_county>, L<FS::cust_pkg>, L<FS::Record>,
963 schema.html from the base documentation.