1 package FS::cust_location;
2 use base qw( FS::geocode_Mixin FS::Record );
5 use vars qw( $import $DEBUG $conf $label_prefix );
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 Incorporated city flag: set to 'Y' if the address is in the legal borders
99 of an incorporated city.
103 Disabled flag; set to 'Y' to disable the location.
113 Creates a new location. To add the location to the database, see L<"insert">.
115 Note that this stores the hash reference, not a distinct copy of the hash it
116 points to. You can ask the object for a copy with the I<hash> method.
120 sub table { 'cust_location'; }
124 Finds an existing location matching the customer and address values in this
125 location, if one exists, and sets the contents of this location equal to that
126 one (including its locationnum).
128 If an existing location is not found, this one I<will> be inserted. (This is a
129 change from the "new_or_existing" method that this replaces.)
131 The following fields are considered "essential" and I<must> match: custnum,
132 address1, address2, city, county, state, zip, country, location_number,
133 location_type, location_kind. Disabled locations will be found only if this
134 location is set to disabled.
136 All other fields are considered "non-essential" and will be ignored in
137 finding a matching location. If the existing location doesn't match
138 in these fields, it will be updated in-place to match.
140 Returns an error string if inserting or updating a location failed.
142 It is unfortunately hard to determine if this created a new location or not.
149 warn "find_or_insert:\n".Dumper($self) if $DEBUG;
151 my @essential = (qw(custnum address1 address2 city county state zip country
152 location_number location_type location_kind disabled));
154 if ($conf->exists('cust_main-no_city_in_address')) {
155 warn "Warning: passed city to find_or_insert when cust_main-no_city_in_address is configured, ignoring it"
156 if $self->get('city');
157 $self->set('city','');
160 # I don't think this is necessary
161 #if ( !$self->coord_auto and $self->latitude and $self->longitude ) {
162 # push @essential, qw(latitude longitude);
163 # # but NOT coord_auto; if the latitude and longitude match the geocoded
164 # # values then that's good enough
167 # put nonempty, nonessential fields/values into this hash
168 my %nonempty = map { $_ => $self->get($_) }
169 grep {$self->get($_)} $self->fields;
170 delete @nonempty{@essential};
171 delete $nonempty{'locationnum'};
173 my %hash = map { $_ => $self->get($_) } @essential;
174 my @matches = qsearch('cust_location', \%hash);
176 # we no longer reject matches for having different values in nonessential
177 # fields; we just alter the record to match
179 my $old = $matches[0];
180 warn "found existing location #".$old->locationnum."\n" if $DEBUG;
181 foreach my $field (keys %nonempty) {
182 if ($old->get($field) ne $nonempty{$field}) {
183 warn "altering $field to match requested location" if $DEBUG;
184 $old->set($field, $nonempty{$field});
188 if ( $old->modified ) {
189 warn "updating non-essential fields\n" if $DEBUG;
190 my $error = $old->replace;
191 return $error if $error;
193 # set $self equal to $old
194 foreach ($self->fields) {
195 $self->set($_, $old->get($_));
200 # didn't find a match
201 warn "not found; inserting new location\n" if $DEBUG;
202 return $self->insert;
207 Adds this record to the database. If there is an error, returns the error,
208 otherwise returns false.
215 if ($conf->exists('cust_main-no_city_in_address')) {
216 warn "Warning: passed city to insert when cust_main-no_city_in_address is configured, ignoring it"
217 if $self->get('city');
218 $self->set('city','');
221 if ( $self->censustract ) {
222 $self->set('censusyear' => $conf->config('census_year') || 2012);
225 my $oldAutoCommit = $FS::UID::AutoCommit;
226 local $FS::UID::AutoCommit = 0;
229 my $error = $self->SUPER::insert(@_);
231 $dbh->rollback if $oldAutoCommit;
235 #false laziness with cust_main, will go away eventually
236 if ( !$import and $conf->config('tax_district_method') ) {
238 my $queue = new FS::queue {
239 'job' => 'FS::geocode_Mixin::process_district_update'
241 $error = $queue->insert( ref($self), $self->locationnum );
243 $dbh->rollback if $oldAutoCommit;
249 # cust_location exports
250 #my $export_args = $options{'export_args'} || [];
252 # don't export custnum_pending cases, let follow-up replace handle that
253 if ($self->custnum || $self->prospectnum) {
255 map qsearch( 'part_export', {exportnum=>$_} ),
256 $conf->config('cust_location-exports'); #, $agentnum
258 foreach my $part_export ( @part_export ) {
259 my $error = $part_export->export_insert($self); #, @$export_args);
261 $dbh->rollback if $oldAutoCommit;
262 return "exporting to ". $part_export->exporttype.
263 " (transaction rolled back): $error";
268 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
274 Delete this record from the database.
276 =item replace OLD_RECORD
278 Replaces the OLD_RECORD with this one in the database. If there is an error,
279 returns the error, otherwise returns false.
286 $old ||= $self->replace_old;
288 warn "Warning: passed city to replace when cust_main-no_city_in_address is configured"
289 if $conf->exists('cust_main-no_city_in_address') && $self->get('city');
291 # the following fields are immutable if this is a customer location. if
292 # it's a prospect location, then there are no active packages, no billing
293 # history, no taxes, and in general no reason to keep the old location
295 if ( $self->custnum ) {
296 foreach (qw(address1 address2 city state zip country)) {
297 if ( $self->$_ ne $old->$_ ) {
298 return "can't change cust_location field $_";
303 my $oldAutoCommit = $FS::UID::AutoCommit;
304 local $FS::UID::AutoCommit = 0;
307 my $error = $self->SUPER::replace($old);
309 $dbh->rollback if $oldAutoCommit;
313 # cust_location exports
314 #my $export_args = $options{'export_args'} || [];
316 # don't export custnum_pending cases, let follow-up replace handle that
317 if ($self->custnum || $self->prospectnum) {
319 map qsearch( 'part_export', {exportnum=>$_} ),
320 $conf->config('cust_location-exports'); #, $agentnum
322 foreach my $part_export ( @part_export ) {
323 my $error = $part_export->export_replace($self, $old); #, @$export_args);
325 $dbh->rollback if $oldAutoCommit;
326 return "exporting to ". $part_export->exporttype.
327 " (transaction rolled back): $error";
332 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
339 Checks all fields to make sure this is a valid location. If there is
340 an error, returns the error, otherwise returns false. Called by the insert
348 return '' if $self->disabled; # so that disabling locations never fails
351 $self->ut_numbern('locationnum')
352 || $self->ut_foreign_keyn('prospectnum', 'prospect_main', 'prospectnum')
353 || $self->ut_foreign_keyn('custnum', 'cust_main', 'custnum')
354 || $self->ut_textn('locationname')
355 || $self->ut_text('address1')
356 || $self->ut_textn('address2')
357 || ($conf->exists('cust_main-no_city_in_address')
358 ? $self->ut_textn('city')
359 : $self->ut_text('city'))
360 || $self->ut_textn('county')
361 || $self->ut_textn('state')
362 || $self->ut_country('country')
363 || (!$import && $self->ut_zip('zip', $self->country))
364 || $self->ut_coordn('latitude')
365 || $self->ut_coordn('longitude')
366 || $self->ut_enum('coord_auto', [ '', 'Y' ])
367 || $self->ut_enum('addr_clean', [ '', 'Y' ])
368 || $self->ut_alphan('location_type')
369 || $self->ut_textn('location_number')
370 || $self->ut_enum('location_kind', [ '', 'R', 'B' ] )
371 || $self->ut_alphan('geocode')
372 || $self->ut_alphan('district')
373 || $self->ut_numbern('censusyear')
374 || $self->ut_flag('incorporated')
376 return $error if $error;
377 if ( $self->censustract ne '' ) {
378 $self->censustract =~ /^\s*(\d{9})\.?(\d{2})\s*$/
379 or return "Illegal census tract: ". $self->censustract;
381 $self->censustract("$1.$2");
384 #yikes... this is ancient, pre-dates cust_location and will be harder to
385 # implement now... how do we know this location is a service location from
386 # here and not a billing? we can't just check locationnums, we might be new :/
387 return "Unit # is required"
388 if $conf->exists('cust_main-require_address2')
389 && ! $self->address2 =~ /\S/;
391 # tricky...we have to allow for the customer to not be inserted yet
392 return "No prospect or customer!" unless $self->prospectnum
394 || $self->get('custnum_pending');
395 return "Prospect and customer!" if $self->prospectnum && $self->custnum;
397 return 'Location kind is required'
398 if $self->prospectnum
399 && $conf->exists('prospect_main-alt_address_format')
400 && ! $self->location_kind;
402 unless ( $import or qsearch('cust_main_county', {
403 'country' => $self->country,
406 return "Unknown state/county/country: ".
407 $self->state. "/". $self->county. "/". $self->country
408 unless qsearch('cust_main_county',{
409 'state' => $self->state,
410 'county' => $self->county,
411 'country' => $self->country,
415 # set coordinates, unless we already have them
416 if (!$import and !$self->latitude and !$self->longitude) {
425 Returns this location's full country name
429 #moved to geocode_Mixin.pm
433 Synonym for location_label
439 $self->location_label(@_);
442 =item has_ship_address
444 Returns false since cust_location objects do not have a separate shipping
449 sub has_ship_address {
455 Returns a list of key/value pairs, with the following keys: address1, address2,
456 city, county, state, zip, country, geocode, location_type, location_number,
461 =item disable_if_unused
463 Sets the "disabled" flag on the location if it is no longer in use as a
464 prospect location, package location, or a customer's billing or default
469 sub disable_if_unused {
472 my $locationnum = $self->locationnum;
473 return '' if FS::cust_main->count('bill_locationnum = '.$locationnum.' OR
474 ship_locationnum = '.$locationnum)
475 or FS::contact->count( 'locationnum = '.$locationnum)
476 or FS::cust_pkg->count('cancel IS NULL AND
477 locationnum = '.$locationnum)
479 $self->disabled('Y');
486 Takes a new L<FS::cust_location> object. Moves all packages that use the
487 existing location to the new one, then sets the "disabled" flag on the old
488 location. Returns nothing on success, an error message on error.
496 warn "move_to:\nFROM:".Dumper($old)."\nTO:".Dumper($new) if $DEBUG;
498 local $SIG{HUP} = 'IGNORE';
499 local $SIG{INT} = 'IGNORE';
500 local $SIG{QUIT} = 'IGNORE';
501 local $SIG{TERM} = 'IGNORE';
502 local $SIG{TSTP} = 'IGNORE';
503 local $SIG{PIPE} = 'IGNORE';
505 my $oldAutoCommit = $FS::UID::AutoCommit;
506 local $FS::UID::AutoCommit = 0;
510 # prevent this from failing because of pkg_svc quantity limits
511 local( $FS::cust_svc::ignore_quantity ) = 1;
513 if ( !$new->locationnum ) {
514 $error = $new->insert;
516 $dbh->rollback if $oldAutoCommit;
517 return "Error creating location: $error";
519 } elsif ( $new->locationnum == $old->locationnum ) {
520 # then they're the same location; the normal result of doing a minor
522 $dbh->commit if $oldAutoCommit;
526 # find all packages that have the old location as their service address,
527 # and aren't canceled,
528 # and aren't supplemental to another package.
529 my @pkgs = qsearch('cust_pkg', {
530 'locationnum' => $old->locationnum,
534 foreach my $cust_pkg (@pkgs) {
535 # don't move one-time charges that have already been charged
536 next if $cust_pkg->part_pkg->freq eq '0'
537 and ($cust_pkg->setup || 0) > 0;
539 $error = $cust_pkg->change(
540 'locationnum' => $new->locationnum,
543 if ( $error and not ref($error) ) {
544 $dbh->rollback if $oldAutoCommit;
545 return "Error moving pkgnum ".$cust_pkg->pkgnum.": $error";
549 $error = $old->disable_if_unused;
551 $dbh->rollback if $oldAutoCommit;
552 return "Error disabling old location: $error";
555 $dbh->commit if $oldAutoCommit;
561 Attempts to parse data for location_type and location_number from address1
569 return '' if $self->get('location_type')
570 || $self->get('location_number');
573 if ( 1 ) { #ikano, switch on via config
574 { no warnings 'void';
575 eval { 'use FS::part_export::ikano;' };
578 %parse = FS::part_export::ikano->location_types_parse;
583 foreach my $from ('address1', 'address2') {
584 foreach my $parse ( keys %parse ) {
585 my $value = $self->get($from);
586 if ( $value =~ s/(^|\W+)$parse\W+(\w+)\W*$//i ) {
587 $self->set('location_type', $parse{$parse});
588 $self->set('location_number', $2);
589 $self->set($from, $value);
595 #nothing matched, no changes
596 $self->get('address2')
597 ? "Can't parse unit type and number from address2"
603 Moves data from location_type and location_number to the end of address1.
610 #false laziness w/geocode_Mixin.pm::line
611 my $lt = $self->get('location_type');
615 if ( 1 ) { #ikano, switch on via config
616 { no warnings 'void';
617 eval { 'use FS::part_export::ikano;' };
620 %location_type = FS::part_export::ikano->location_types;
622 %location_type = (); #?
625 $self->address1( $self->address1. ' '. $location_type{$lt} || $lt );
626 $self->location_type('');
629 if ( length($self->location_number) ) {
630 $self->address1( $self->address1. ' '. $self->location_number );
631 $self->location_number('');
639 Returns the label of the location object.
647 Customer object (see L<FS::cust_main>)
651 Prospect object (see L<FS::prospect_main>)
655 String used to join location elements
659 Don't label the default service location as "Default service location".
660 May become the default at some point.
667 my( $self, %opt ) = @_;
669 my $prefix = $self->label_prefix(%opt);
670 $prefix .= ($opt{join_string} || ': ') if $prefix;
671 $prefix = '' if $opt{'no_prefix'};
673 $prefix . $self->SUPER::location_label(%opt);
678 Returns the optional site ID string (based on the cust_location-label_prefix
679 config option), "Default service location", or the empty string.
687 Customer object (see L<FS::cust_main>)
691 Prospect object (see L<FS::prospect_main>)
698 my( $self, %opt ) = @_;
700 my $cust_or_prospect = $opt{cust_main} || $opt{prospect_main};
701 unless ( $cust_or_prospect ) {
702 if ( $self->custnum ) {
703 $cust_or_prospect = FS::cust_main->by_key($self->custnum);
704 } elsif ( $self->prospectnum ) {
705 $cust_or_prospect = FS::prospect_main->by_key($self->prospectnum);
710 if ( $label_prefix eq 'CoStAg' ) {
711 my $agent = $conf->config('cust_main-custnum-display_prefix',
712 $cust_or_prospect->agentnum)
713 || $cust_or_prospect->agent->agent;
714 # else this location is invalid
715 $prefix = uc( join('',
717 ($self->state =~ /^(..)/),
719 sprintf('%05d', $self->locationnum)
722 } elsif ( $label_prefix eq '_location' && $self->locationname ) {
723 $prefix = $self->locationname;
725 #} elsif ( ( $opt{'cust_main'} || $self->custnum )
726 # && $self->locationnum == $cust_or_prospect->ship_locationnum ) {
727 # $prefix = 'Default service location';
736 =item county_state_country
738 Returns a string consisting of just the county, state and country.
742 sub county_state_country {
744 my $label = $self->country;
745 $label = $self->state.", $label" if $self->state;
746 $label = $self->county." County, $label" if $self->county;
756 =item process_censustract_update LOCATIONNUM
758 Queueable function to update the census tract to the current year (as set in
759 the 'census_year' configuration variable) and retrieve the new tract code.
763 sub process_censustract_update {
764 eval "use FS::GeocodeCache";
766 my $locationnum = shift;
768 qsearchs( 'cust_location', { locationnum => $locationnum })
769 or die "locationnum '$locationnum' not found!\n";
771 my $new_year = $conf->config('census_year') or return;
772 my $loc = FS::GeocodeCache->new( $cust_location->location_hash );
773 $loc->set_censustract;
774 my $error = $loc->get('censustract_error');
775 die $error if $error;
776 $cust_location->set('censustract', $loc->get('censustract'));
777 $cust_location->set('censusyear', $new_year);
778 $error = $cust_location->replace;
779 die $error if $error;
783 =item process_set_coord
785 Queueable function to find and fill in coordinates for all locations that
786 lack them. Because this uses the Google Maps API, it's internally rate
787 limited and must run in a single process.
791 sub process_set_coord {
793 # avoid starting multiple instances of this job
794 my @others = qsearch('queue', {
795 'status' => 'locked',
797 'jobnum' => {op=>'!=', value=>$job->jobnum},
801 $job->update_statustext('finding locations to update');
802 my @missing_coords = qsearch('cust_location', {
808 my $n = scalar @missing_coords;
809 for my $cust_location (@missing_coords) {
810 $cust_location->set_coord;
811 my $error = $cust_location->replace;
813 warn "error geocoding location#".$cust_location->locationnum.": $error\n";
816 $job->update_statustext("updated $i / $n locations");
817 dbh->commit; # so that we don't have to wait for the whole thing to finish
818 # Rate-limit to stay under the Google Maps usage limit (2500/day).
819 # 86,400 / 35 = 2,468 lookups per day.
824 die "failed to update ".$n-$i." locations\n";
829 =item process_standardize [ LOCATIONNUMS ]
831 Performs address standardization on locations with unclean addresses,
832 using whatever method you have configured. If the standardize_* method
833 returns a I<clean> address match, the location will be updated. This is
834 always an in-place update (because the physical location is the same,
835 and is just being referred to by a more accurate name).
837 Disabled locations will be skipped, as nobody cares.
839 If any LOCATIONNUMS are provided, only those locations will be updated.
843 sub process_standardize {
845 my @others = qsearch('queue', {
846 'status' => 'locked',
848 'jobnum' => {op=>'!=', value=>$job->jobnum},
851 my @locationnums = grep /^\d+$/, @_;
852 my $where = "AND locationnum IN(".join(',',@locationnums).")"
853 if scalar(@locationnums);
854 my @locations = qsearch({
855 table => 'cust_location',
856 hashref => { addr_clean => '', disabled => '' },
859 my $n_todo = scalar(@locations);
864 eval "use Text::CSV";
865 open $log, '>', "$FS::UID::cache_dir/process_standardize-" .
866 time2str('%Y%m%d',time) .
868 my $csv = Text::CSV->new({binary => 1, eol => "\n"});
870 foreach my $cust_location (@locations) {
871 $job->update_statustext( int(100 * $n_done/$n_todo) . ",$n_done / $n_todo locations" ) if $job;
872 my $result = FS::GeocodeCache->standardize($cust_location);
873 if ( $result->{addr_clean} and !$result->{error} ) {
874 my @cols = ($cust_location->locationnum);
875 foreach (keys %$result) {
876 push @cols, $cust_location->get($_), $result->{$_};
877 $cust_location->set($_, $result->{$_});
879 # bypass immutable field restrictions
880 my $error = $cust_location->FS::Record::replace;
881 warn "location ".$cust_location->locationnum.": $error\n" if $error;
882 $csv->print($log, \@cols);
885 dbh->commit; # so that we can resume if interrupted
894 L<FS::cust_main_county>, L<FS::cust_pkg>, L<FS::Record>,
895 schema.html from the base documentation.