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 location. FS::cust_location
48 inherits from FS::Record. The following fields are currently supported:
62 Address line one (required)
66 Address line two (optional)
70 City (if cust_main-no_city_in_address config is set when inserting, this will be forced blank)
74 County (optional, see L<FS::cust_main_county>)
78 State (see L<FS::cust_main_county>)
86 Country (see L<FS::cust_main_county>)
94 Tax district code (optional)
98 Disabled flag; set to 'Y' to disable the location.
108 Creates a new location. To add the location to the database, see L<"insert">.
110 Note that this stores the hash reference, not a distinct copy of the hash it
111 points to. You can ask the object for a copy with the I<hash> method.
115 sub table { 'cust_location'; }
119 Finds an existing location matching the customer and address values in this
120 location, if one exists, and sets the contents of this location equal to that
121 one (including its locationnum).
123 If an existing location is not found, this one I<will> be inserted. (This is a
124 change from the "new_or_existing" method that this replaces.)
126 The following fields are considered "essential" and I<must> match: custnum,
127 address1, address2, city, county, state, zip, country, location_number,
128 location_type, location_kind. Disabled locations will be found only if this
129 location is set to disabled.
131 All other fields are considered "non-essential" and will be ignored in
132 finding a matching location. If the existing location doesn't match
133 in these fields, it will be updated in-place to match.
135 Returns an error string if inserting or updating a location failed.
137 It is unfortunately hard to determine if this created a new location or not.
144 warn "find_or_insert:\n".Dumper($self) if $DEBUG;
146 my @essential = (qw(custnum address1 address2 city county state zip country
147 location_number location_type location_kind disabled));
149 if ($conf->exists('cust_main-no_city_in_address')) {
150 warn "Warning: passed city to find_or_insert when cust_main-no_city_in_address is configured, ignoring it"
151 if $self->get('city');
152 $self->set('city','');
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
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'};
168 my %hash = map { $_ => $self->get($_) } @essential;
169 foreach (values %hash) {
173 my @matches = qsearch('cust_location', \%hash);
175 # we no longer reject matches for having different values in nonessential
176 # fields; we just alter the record to match
178 my $old = $matches[0];
179 warn "found existing location #".$old->locationnum."\n" if $DEBUG;
180 foreach my $field (keys %nonempty) {
181 if ($old->get($field) ne $nonempty{$field}) {
182 warn "altering $field to match requested location" if $DEBUG;
183 $old->set($field, $nonempty{$field});
187 if ( $old->modified ) {
188 warn "updating non-essential fields\n" if $DEBUG;
189 my $error = $old->replace;
190 return $error if $error;
192 # set $self equal to $old
193 foreach ($self->fields) {
194 $self->set($_, $old->get($_));
199 # didn't find a match
200 warn "not found; inserting new location\n" if $DEBUG;
201 return $self->insert;
206 Adds this record to the database. If there is an error, returns the error,
207 otherwise returns false.
214 if ($conf->exists('cust_main-no_city_in_address')) {
215 warn "Warning: passed city to insert when cust_main-no_city_in_address is configured, ignoring it"
216 if $self->get('city');
217 $self->set('city','');
220 if ( $self->censustract ) {
221 $self->set('censusyear' => $conf->config('census_year') || 2012);
224 my $oldAutoCommit = $FS::UID::AutoCommit;
225 local $FS::UID::AutoCommit = 0;
228 my $error = $self->SUPER::insert(@_);
230 $dbh->rollback if $oldAutoCommit;
234 #false laziness with cust_main, will go away eventually
235 if ( !$import and $conf->config('tax_district_method') ) {
237 my $queue = new FS::queue {
238 'job' => 'FS::geocode_Mixin::process_district_update'
240 $error = $queue->insert( ref($self), $self->locationnum );
242 $dbh->rollback if $oldAutoCommit;
248 # cust_location exports
249 #my $export_args = $options{'export_args'} || [];
251 # don't export custnum_pending cases, let follow-up replace handle that
252 if ($self->custnum || $self->prospectnum) {
254 map qsearch( 'part_export', {exportnum=>$_} ),
255 $conf->config('cust_location-exports'); #, $agentnum
257 foreach my $part_export ( @part_export ) {
258 my $error = $part_export->export_insert($self); #, @$export_args);
260 $dbh->rollback if $oldAutoCommit;
261 return "exporting to ". $part_export->exporttype.
262 " (transaction rolled back): $error";
267 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
273 Delete this record from the database.
275 =item replace OLD_RECORD
277 Replaces the OLD_RECORD with this one in the database. If there is an error,
278 returns the error, otherwise returns false.
285 $old ||= $self->replace_old;
287 warn "Warning: passed city to replace when cust_main-no_city_in_address is configured"
288 if $conf->exists('cust_main-no_city_in_address') && $self->get('city');
290 # the following fields are immutable if this is a customer location. if
291 # it's a prospect location, then there are no active packages, no billing
292 # history, no taxes, and in general no reason to keep the old location
294 if ( !$allow_location_edit and $self->custnum ) {
295 foreach (qw(address1 address2 city state zip country)) {
296 if ( $self->$_ ne $old->$_ ) {
297 return "can't change cust_location field $_";
302 my $oldAutoCommit = $FS::UID::AutoCommit;
303 local $FS::UID::AutoCommit = 0;
306 my $error = $self->SUPER::replace($old);
308 $dbh->rollback if $oldAutoCommit;
312 # cust_location exports
313 #my $export_args = $options{'export_args'} || [];
315 # don't export custnum_pending cases, let follow-up replace handle that
316 if ($self->custnum || $self->prospectnum) {
318 map qsearch( 'part_export', {exportnum=>$_} ),
319 $conf->config('cust_location-exports'); #, $agentnum
321 foreach my $part_export ( @part_export ) {
322 my $error = $part_export->export_replace($self, $old); #, @$export_args);
324 $dbh->rollback if $oldAutoCommit;
325 return "exporting to ". $part_export->exporttype.
326 " (transaction rolled back): $error";
331 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
338 Checks all fields to make sure this is a valid location. If there is
339 an error, returns the error, otherwise returns false. Called by the insert
347 return '' if $self->disabled; # so that disabling locations never fails
349 # maybe should just do all fields in the table?
351 $self->trim_whitespace(qw(district city county state country));
354 $self->ut_numbern('locationnum')
355 || $self->ut_foreign_keyn('prospectnum', 'prospect_main', 'prospectnum')
356 || $self->ut_foreign_keyn('custnum', 'cust_main', 'custnum')
357 || $self->ut_textn('locationname')
358 || $self->ut_text('address1')
359 || $self->ut_textn('address2')
360 || ($conf->exists('cust_main-no_city_in_address')
361 ? $self->ut_textn('city')
362 : $self->ut_text('city'))
363 || $self->ut_textn('county')
364 || $self->ut_textn('state')
365 || $self->ut_country('country')
366 || (!$import && $self->ut_zip('zip', $self->country))
367 || $self->ut_coordn('latitude')
368 || $self->ut_coordn('longitude')
369 || $self->ut_enum('coord_auto', [ '', 'Y' ])
370 || $self->ut_enum('addr_clean', [ '', 'Y' ])
371 || $self->ut_alphan('location_type')
372 || $self->ut_textn('location_number')
373 || $self->ut_enum('location_kind', [ '', 'R', 'B' ] )
374 || $self->ut_alphan('geocode')
375 || $self->ut_alphan('district')
376 || $self->ut_numbern('censusyear')
378 return $error if $error;
379 if ( $self->censustract ne '' ) {
380 $self->censustract =~ /^\s*(\d{9})\.?(\d{2})\s*$/
381 or return "Illegal census tract: ". $self->censustract;
383 $self->censustract("$1.$2");
386 #yikes... this is ancient, pre-dates cust_location and will be harder to
387 # implement now... how do we know this location is a service location from
388 # here and not a billing? we can't just check locationnums, we might be new :/
389 return "Unit # is required"
390 if $conf->exists('cust_main-require_address2')
391 && ! $self->address2 =~ /\S/;
393 # tricky...we have to allow for the customer to not be inserted yet
394 return "No prospect or customer!" unless $self->prospectnum
396 || $self->get('custnum_pending');
397 return "Prospect and customer!" if $self->prospectnum && $self->custnum;
399 return 'Location kind is required'
400 if $self->prospectnum
401 && $conf->exists('prospect_main-alt_address_format')
402 && ! $self->location_kind;
404 unless ( $import or qsearch('cust_main_county', {
405 'country' => $self->country,
408 return "Unknown state/county/country: ".
409 $self->state. "/". $self->county. "/". $self->country
410 unless qsearch('cust_main_county',{
411 'state' => $self->state,
412 'county' => $self->county,
413 'country' => $self->country,
417 # set coordinates, unless we already have them
418 if (!$import and !$self->latitude and !$self->longitude) {
427 Returns this location's full country name
431 #moved to geocode_Mixin.pm
435 Synonym for location_label
441 $self->location_label(@_);
444 =item has_ship_address
446 Returns false since cust_location objects do not have a separate shipping
451 sub has_ship_address {
457 Returns a list of key/value pairs, with the following keys: address1, address2,
458 city, county, state, zip, country, geocode, location_type, location_number,
463 =item disable_if_unused
465 Sets the "disabled" flag on the location if it is no longer in use as a
466 prospect location, package location, or a customer's billing or default
471 sub disable_if_unused {
474 my $locationnum = $self->locationnum;
475 return '' if FS::cust_main->count('bill_locationnum = '.$locationnum.' OR
476 ship_locationnum = '.$locationnum)
477 or FS::contact->count( 'locationnum = '.$locationnum)
478 or FS::cust_pkg->count('cancel IS NULL AND
479 locationnum = '.$locationnum)
481 $self->disabled('Y');
488 Takes a new L<FS::cust_location> object. Moves all packages that use the
489 existing location to the new one, then sets the "disabled" flag on the old
490 location. Returns nothing on success, an error message on error.
498 warn "move_to:\nFROM:".Dumper($old)."\nTO:".Dumper($new) if $DEBUG;
500 local $SIG{HUP} = 'IGNORE';
501 local $SIG{INT} = 'IGNORE';
502 local $SIG{QUIT} = 'IGNORE';
503 local $SIG{TERM} = 'IGNORE';
504 local $SIG{TSTP} = 'IGNORE';
505 local $SIG{PIPE} = 'IGNORE';
507 my $oldAutoCommit = $FS::UID::AutoCommit;
508 local $FS::UID::AutoCommit = 0;
512 # prevent this from failing because of pkg_svc quantity limits
513 local( $FS::cust_svc::ignore_quantity ) = 1;
515 if ( !$new->locationnum ) {
516 $error = $new->insert;
518 $dbh->rollback if $oldAutoCommit;
519 return "Error creating location: $error";
521 } elsif ( $new->locationnum == $old->locationnum ) {
522 # then they're the same location; the normal result of doing a minor
524 $dbh->commit if $oldAutoCommit;
528 # find all packages that have the old location as their service address,
529 # and aren't canceled,
530 # and aren't supplemental to another package.
531 my @pkgs = qsearch('cust_pkg', {
532 'locationnum' => $old->locationnum,
536 foreach my $cust_pkg (@pkgs) {
537 # don't move one-time charges that have already been charged
538 next if $cust_pkg->part_pkg->freq eq '0'
539 and ($cust_pkg->setup || 0) > 0;
541 $error = $cust_pkg->change(
542 'locationnum' => $new->locationnum,
545 if ( $error and not ref($error) ) {
546 $dbh->rollback if $oldAutoCommit;
547 return "Error moving pkgnum ".$cust_pkg->pkgnum.": $error";
551 $error = $old->disable_if_unused;
553 $dbh->rollback if $oldAutoCommit;
554 return "Error disabling old location: $error";
557 $dbh->commit if $oldAutoCommit;
563 Attempts to parse data for location_type and location_number from address1
571 return '' if $self->get('location_type')
572 || $self->get('location_number');
575 if ( 1 ) { #ikano, switch on via config
576 { no warnings 'void';
577 eval { 'use FS::part_export::ikano;' };
580 %parse = FS::part_export::ikano->location_types_parse;
585 foreach my $from ('address1', 'address2') {
586 foreach my $parse ( keys %parse ) {
587 my $value = $self->get($from);
588 if ( $value =~ s/(^|\W+)$parse\W+(\w+)\W*$//i ) {
589 $self->set('location_type', $parse{$parse});
590 $self->set('location_number', $2);
591 $self->set($from, $value);
597 #nothing matched, no changes
598 $self->get('address2')
599 ? "Can't parse unit type and number from address2"
605 Moves data from location_type and location_number to the end of address1.
612 #false laziness w/geocode_Mixin.pm::line
613 my $lt = $self->get('location_type');
617 if ( 1 ) { #ikano, switch on via config
618 { no warnings 'void';
619 eval { 'use FS::part_export::ikano;' };
622 %location_type = FS::part_export::ikano->location_types;
624 %location_type = (); #?
627 $self->address1( $self->address1. ' '. $location_type{$lt} || $lt );
628 $self->location_type('');
631 if ( length($self->location_number) ) {
632 $self->address1( $self->address1. ' '. $self->location_number );
633 $self->location_number('');
641 Returns the label of the location object.
649 Customer object (see L<FS::cust_main>)
653 Prospect object (see L<FS::prospect_main>)
657 String used to join location elements
661 Don't label the default service location as "Default service location".
662 May become the default at some point.
669 my( $self, %opt ) = @_;
671 my $prefix = $self->label_prefix;
672 $prefix .= ($opt{join_string} || ': ') if $prefix;
673 $prefix = '' if $opt{'no_prefix'};
675 $prefix . $self->SUPER::location_label(%opt);
680 Returns the optional site ID string (based on the cust_location-label_prefix
681 config option), "Default service location", or the empty string.
689 Customer object (see L<FS::cust_main>)
693 Prospect object (see L<FS::prospect_main>)
700 my( $self, %opt ) = @_;
702 my $cust_or_prospect = $opt{cust_main} || $opt{prospect_main};
703 unless ( $cust_or_prospect ) {
704 if ( $self->custnum ) {
705 $cust_or_prospect = FS::cust_main->by_key($self->custnum);
706 } elsif ( $self->prospectnum ) {
707 $cust_or_prospect = FS::prospect_main->by_key($self->prospectnum);
712 if ( $label_prefix eq 'CoStAg' ) {
713 my $agent = $conf->config('cust_main-custnum-display_prefix',
714 $cust_or_prospect->agentnum)
715 || $cust_or_prospect->agent->agent;
716 # else this location is invalid
717 $prefix = uc( join('',
719 ($self->state =~ /^(..)/),
721 sprintf('%05d', $self->locationnum)
724 } elsif ( $label_prefix eq '_location' && $self->locationname ) {
725 $prefix = $self->locationname;
727 #} elsif ( ( $opt{'cust_main'} || $self->custnum )
728 # && $self->locationnum == $cust_or_prospect->ship_locationnum ) {
729 # $prefix = 'Default service location';
738 =item county_state_country
740 Returns a string consisting of just the county, state and country.
744 sub county_state_country {
746 my $label = $self->country;
747 $label = $self->state.", $label" if $self->state;
748 $label = $self->county." County, $label" if $self->county;
758 return '' unless $self->custnum;
759 qsearchs('cust_main', { 'custnum' => $self->custnum } );
768 =item process_censustract_update LOCATIONNUM
770 Queueable function to update the census tract to the current year (as set in
771 the 'census_year' configuration variable) and retrieve the new tract code.
775 sub process_censustract_update {
776 eval "use FS::GeocodeCache";
778 my $locationnum = shift;
780 qsearchs( 'cust_location', { locationnum => $locationnum })
781 or die "locationnum '$locationnum' not found!\n";
783 my $new_year = $conf->config('census_year') or return;
784 my $loc = FS::GeocodeCache->new( $cust_location->location_hash );
785 $loc->set_censustract;
786 my $error = $loc->get('censustract_error');
787 die $error if $error;
788 $cust_location->set('censustract', $loc->get('censustract'));
789 $cust_location->set('censusyear', $new_year);
790 $error = $cust_location->replace;
791 die $error if $error;
795 =item process_set_coord
797 Queueable function to find and fill in coordinates for all locations that
798 lack them. Because this uses the Google Maps API, it's internally rate
799 limited and must run in a single process.
803 sub process_set_coord {
805 # avoid starting multiple instances of this job
806 my @others = qsearch('queue', {
807 'status' => 'locked',
809 'jobnum' => {op=>'!=', value=>$job->jobnum},
813 $job->update_statustext('finding locations to update');
814 my @missing_coords = qsearch('cust_location', {
820 my $n = scalar @missing_coords;
821 for my $cust_location (@missing_coords) {
822 $cust_location->set_coord;
823 my $error = $cust_location->replace;
825 warn "error geocoding location#".$cust_location->locationnum.": $error\n";
828 $job->update_statustext("updated $i / $n locations");
829 dbh->commit; # so that we don't have to wait for the whole thing to finish
830 # Rate-limit to stay under the Google Maps usage limit (2500/day).
831 # 86,400 / 35 = 2,468 lookups per day.
836 die "failed to update ".$n-$i." locations\n";
841 =item process_standardize [ LOCATIONNUMS ]
843 Performs address standardization on locations with unclean addresses,
844 using whatever method you have configured. If the standardize_* method
845 returns a I<clean> address match, the location will be updated. This is
846 always an in-place update (because the physical location is the same,
847 and is just being referred to by a more accurate name).
849 Disabled locations will be skipped, as nobody cares.
851 If any LOCATIONNUMS are provided, only those locations will be updated.
855 sub process_standardize {
857 my @others = qsearch('queue', {
858 'status' => 'locked',
860 'jobnum' => {op=>'!=', value=>$job->jobnum},
863 my @locationnums = grep /^\d+$/, @_;
864 my $where = "AND locationnum IN(".join(',',@locationnums).")"
865 if scalar(@locationnums);
866 my @locations = qsearch({
867 table => 'cust_location',
868 hashref => { addr_clean => '', disabled => '' },
871 my $n_todo = scalar(@locations);
876 eval "use Text::CSV";
877 open $log, '>', "$FS::UID::cache_dir/process_standardize-" .
878 time2str('%Y%m%d',time) .
880 my $csv = Text::CSV->new({binary => 1, eol => "\n"});
882 foreach my $cust_location (@locations) {
883 $job->update_statustext( int(100 * $n_done/$n_todo) . ",$n_done / $n_todo locations" ) if $job;
884 my $result = FS::GeocodeCache->standardize($cust_location);
885 if ( $result->{addr_clean} and !$result->{error} ) {
886 my @cols = ($cust_location->locationnum);
887 foreach (keys %$result) {
888 push @cols, $cust_location->get($_), $result->{$_};
889 $cust_location->set($_, $result->{$_});
891 # bypass immutable field restrictions
892 my $error = $cust_location->FS::Record::replace;
893 warn "location ".$cust_location->locationnum.": $error\n" if $error;
894 $csv->print($log, \@cols);
897 dbh->commit; # so that we can resume if interrupted
905 # are we going to need to update tax districts?
906 my $use_districts = $conf->config('tax_district_method') ? 1 : 0;
908 # trim whitespace on records that need it
909 local $allow_location_edit = 1;
910 foreach my $field (qw(city county state country district)) {
911 foreach my $location (qsearch({
912 table => 'cust_location',
913 extra_sql => " WHERE $field LIKE ' %' OR $field LIKE '% '"
915 my $error = $location->replace;
916 die "$error (fixing whitespace in $field, locationnum ".$location->locationnum.')'
919 if ( $use_districts ) {
920 my $queue = new FS::queue {
921 'job' => 'FS::geocode_Mixin::process_district_update'
923 $error = $queue->insert( 'FS::cust_location' => $location->locationnum );
924 die $error if $error;
926 } # foreach $location
935 L<FS::cust_main_county>, L<FS::cust_pkg>, L<FS::Record>,
936 schema.html from the base documentation.