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 );
9 use FS::UID qw( dbh driver_name );
10 use FS::Record qw( qsearch qsearchs );
12 use FS::prospect_main;
14 use FS::cust_main_county;
22 FS::UID->install_callback( sub {
23 $conf = FS::Conf->new;
24 $label_prefix = $conf->config('cust_location-label_prefix') || '';
29 FS::cust_location - Object methods for cust_location records
33 use FS::cust_location;
35 $record = new FS::cust_location \%hash;
36 $record = new FS::cust_location { 'column' => 'value' };
38 $error = $record->insert;
40 $error = $new_record->replace($old_record);
42 $error = $record->delete;
44 $error = $record->check;
48 An FS::cust_location object represents a customer location. FS::cust_location
49 inherits from FS::Record. The following fields are currently supported:
63 Address line one (required)
67 Address line two (optional)
71 City (if cust_main-no_city_in_address config is set when inserting, this will be forced blank)
75 County (optional, see L<FS::cust_main_county>)
79 State (see L<FS::cust_main_county>)
87 Country (see L<FS::cust_main_county>)
95 Tax district code (optional)
99 Disabled flag; set to 'Y' to disable the location.
109 Creates a new location. To add the location to the database, see L<"insert">.
111 Note that this stores the hash reference, not a distinct copy of the hash it
112 points to. You can ask the object for a copy with the I<hash> method.
116 sub table { 'cust_location'; }
120 Finds an existing location matching the customer and address values in this
121 location, if one exists, and sets the contents of this location equal to that
122 one (including its locationnum).
124 If an existing location is not found, this one I<will> be inserted. (This is a
125 change from the "new_or_existing" method that this replaces.)
127 The following fields are considered "essential" and I<must> match: custnum,
128 address1, address2, city, county, state, zip, country, location_number,
129 location_type, location_kind. Disabled locations will be found only if this
130 location is set to disabled.
132 All other fields are considered "non-essential" and will be ignored in
133 finding a matching location. If the existing location doesn't match
134 in these fields, it will be updated in-place to match.
136 Returns an error string if inserting or updating a location failed.
138 It is unfortunately hard to determine if this created a new location or not.
145 warn "find_or_insert:\n".Dumper($self) if $DEBUG;
147 my @essential = (qw(custnum address1 address2 city county state zip country
148 location_number location_type location_kind disabled));
150 if ($conf->exists('cust_main-no_city_in_address')) {
151 warn "Warning: passed city to find_or_insert when cust_main-no_city_in_address is configured, ignoring it"
152 if $self->get('city');
153 $self->set('city','');
156 # I don't think this is necessary
157 #if ( !$self->coord_auto and $self->latitude and $self->longitude ) {
158 # push @essential, qw(latitude longitude);
159 # # but NOT coord_auto; if the latitude and longitude match the geocoded
160 # # values then that's good enough
163 # put nonempty, nonessential fields/values into this hash
164 my %nonempty = map { $_ => $self->get($_) }
165 grep {$self->get($_)} $self->fields;
166 delete @nonempty{@essential};
167 delete $nonempty{'locationnum'};
169 my %hash = map { $_ => $self->get($_) } @essential;
170 my @matches = qsearch('cust_location', \%hash);
172 # we no longer reject matches for having different values in nonessential
173 # fields; we just alter the record to match
175 my $old = $matches[0];
176 warn "found existing location #".$old->locationnum."\n" if $DEBUG;
177 foreach my $field (keys %nonempty) {
178 if ($old->get($field) ne $nonempty{$field}) {
179 warn "altering $field to match requested location" if $DEBUG;
180 $old->set($field, $nonempty{$field});
184 if ( $old->modified ) {
185 warn "updating non-essential fields\n" if $DEBUG;
186 my $error = $old->replace;
187 return $error if $error;
189 # set $self equal to $old
190 foreach ($self->fields) {
191 $self->set($_, $old->get($_));
196 # didn't find a match
197 warn "not found; inserting new location\n" if $DEBUG;
198 return $self->insert;
203 Adds this record to the database. If there is an error, returns the error,
204 otherwise returns false.
211 if ($conf->exists('cust_main-no_city_in_address')) {
212 warn "Warning: passed city to insert when cust_main-no_city_in_address is configured, ignoring it"
213 if $self->get('city');
214 $self->set('city','');
217 if ( $self->censustract ) {
218 $self->set('censusyear' => $conf->config('census_year') || 2012);
221 my $oldAutoCommit = $FS::UID::AutoCommit;
222 local $FS::UID::AutoCommit = 0;
225 my $error = $self->SUPER::insert(@_);
227 $dbh->rollback if $oldAutoCommit;
231 #false laziness with cust_main, will go away eventually
232 if ( !$import and $conf->config('tax_district_method') ) {
234 my $queue = new FS::queue {
235 'job' => 'FS::geocode_Mixin::process_district_update'
237 $error = $queue->insert( ref($self), $self->locationnum );
239 $dbh->rollback if $oldAutoCommit;
245 # cust_location exports
246 #my $export_args = $options{'export_args'} || [];
249 map qsearch( 'part_export', {exportnum=>$_} ),
250 $conf->config('cust_location-exports'); #, $agentnum
252 foreach my $part_export ( @part_export ) {
253 my $error = $part_export->export_insert($self); #, @$export_args);
255 $dbh->rollback if $oldAutoCommit;
256 return "exporting to ". $part_export->exporttype.
257 " (transaction rolled back): $error";
262 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
268 Delete this record from the database.
270 =item replace OLD_RECORD
272 Replaces the OLD_RECORD with this one in the database. If there is an error,
273 returns the error, otherwise returns false.
280 $old ||= $self->replace_old;
282 warn "Warning: passed city to replace when cust_main-no_city_in_address is configured"
283 if $conf->exists('cust_main-no_city_in_address') && $self->get('city');
285 # the following fields are immutable
286 foreach (qw(address1 address2 city state zip country)) {
287 if ( $self->$_ ne $old->$_ ) {
288 return "can't change cust_location field $_";
292 my $oldAutoCommit = $FS::UID::AutoCommit;
293 local $FS::UID::AutoCommit = 0;
296 my $error = $self->SUPER::replace($old);
298 $dbh->rollback if $oldAutoCommit;
302 # cust_location exports
303 #my $export_args = $options{'export_args'} || [];
306 map qsearch( 'part_export', {exportnum=>$_} ),
307 $conf->config('cust_location-exports'); #, $agentnum
309 foreach my $part_export ( @part_export ) {
310 my $error = $part_export->export_replace($self, $old); #, @$export_args);
312 $dbh->rollback if $oldAutoCommit;
313 return "exporting to ". $part_export->exporttype.
314 " (transaction rolled back): $error";
319 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
326 Checks all fields to make sure this is a valid location. If there is
327 an error, returns the error, otherwise returns false. Called by the insert
335 return '' if $self->disabled; # so that disabling locations never fails
338 $self->ut_numbern('locationnum')
339 || $self->ut_foreign_keyn('prospectnum', 'prospect_main', 'prospectnum')
340 || $self->ut_foreign_keyn('custnum', 'cust_main', 'custnum')
341 || $self->ut_textn('locationname')
342 || $self->ut_text('address1')
343 || $self->ut_textn('address2')
344 || ($conf->exists('cust_main-no_city_in_address')
345 ? $self->ut_textn('city')
346 : $self->ut_text('city'))
347 || $self->ut_textn('county')
348 || $self->ut_textn('state')
349 || $self->ut_country('country')
350 || (!$import && $self->ut_zip('zip', $self->country))
351 || $self->ut_coordn('latitude')
352 || $self->ut_coordn('longitude')
353 || $self->ut_enum('coord_auto', [ '', 'Y' ])
354 || $self->ut_enum('addr_clean', [ '', 'Y' ])
355 || $self->ut_alphan('location_type')
356 || $self->ut_textn('location_number')
357 || $self->ut_enum('location_kind', [ '', 'R', 'B' ] )
358 || $self->ut_alphan('geocode')
359 || $self->ut_alphan('district')
360 || $self->ut_numbern('censusyear')
362 return $error if $error;
363 if ( $self->censustract ne '' ) {
364 $self->censustract =~ /^\s*(\d{9})\.?(\d{2})\s*$/
365 or return "Illegal census tract: ". $self->censustract;
367 $self->censustract("$1.$2");
370 if ( $conf->exists('cust_main-require_address2') and
371 !$self->ship_address2 =~ /\S/ ) {
372 return "Unit # is required";
375 # tricky...we have to allow for the customer to not be inserted yet
376 return "No prospect or customer!" unless $self->prospectnum
378 || $self->get('custnum_pending');
379 return "Prospect and customer!" if $self->prospectnum && $self->custnum;
381 return 'Location kind is required'
382 if $self->prospectnum
383 && $conf->exists('prospect_main-alt_address_format')
384 && ! $self->location_kind;
386 unless ( $import or qsearch('cust_main_county', {
387 'country' => $self->country,
390 return "Unknown state/county/country: ".
391 $self->state. "/". $self->county. "/". $self->country
392 unless qsearch('cust_main_county',{
393 'state' => $self->state,
394 'county' => $self->county,
395 'country' => $self->country,
399 # set coordinates, unless we already have them
400 if (!$import and !$self->latitude and !$self->longitude) {
409 Returns this locations's full country name
415 code2country($self->country);
420 Synonym for location_label
426 $self->location_label(@_);
429 =item has_ship_address
431 Returns false since cust_location objects do not have a separate shipping
436 sub has_ship_address {
442 Returns a list of key/value pairs, with the following keys: address1, address2,
443 city, county, state, zip, country, geocode, location_type, location_number,
448 =item disable_if_unused
450 Sets the "disabled" flag on the location if it is no longer in use as a
451 prospect location, package location, or a customer's billing or default
456 sub disable_if_unused {
459 my $locationnum = $self->locationnum;
460 return '' if FS::cust_main->count('bill_locationnum = '.$locationnum.' OR
461 ship_locationnum = '.$locationnum)
462 or FS::contact->count( 'locationnum = '.$locationnum)
463 or FS::cust_pkg->count('cancel IS NULL AND
464 locationnum = '.$locationnum)
466 $self->disabled('Y');
473 Takes a new L<FS::cust_location> object. Moves all packages that use the
474 existing location to the new one, then sets the "disabled" flag on the old
475 location. Returns nothing on success, an error message on error.
483 warn "move_to:\nFROM:".Dumper($old)."\nTO:".Dumper($new) if $DEBUG;
485 local $SIG{HUP} = 'IGNORE';
486 local $SIG{INT} = 'IGNORE';
487 local $SIG{QUIT} = 'IGNORE';
488 local $SIG{TERM} = 'IGNORE';
489 local $SIG{TSTP} = 'IGNORE';
490 local $SIG{PIPE} = 'IGNORE';
492 my $oldAutoCommit = $FS::UID::AutoCommit;
493 local $FS::UID::AutoCommit = 0;
497 # prevent this from failing because of pkg_svc quantity limits
498 local( $FS::cust_svc::ignore_quantity ) = 1;
500 if ( !$new->locationnum ) {
501 $error = $new->insert;
503 $dbh->rollback if $oldAutoCommit;
504 return "Error creating location: $error";
506 } elsif ( $new->locationnum == $old->locationnum ) {
507 # then they're the same location; the normal result of doing a minor
509 $dbh->commit if $oldAutoCommit;
513 # find all packages that have the old location as their service address,
514 # and aren't canceled,
515 # and aren't supplemental to another package.
516 my @pkgs = qsearch('cust_pkg', {
517 'locationnum' => $old->locationnum,
521 foreach my $cust_pkg (@pkgs) {
522 # don't move one-time charges that have already been charged
523 next if $cust_pkg->part_pkg->freq eq '0'
524 and ($cust_pkg->setup || 0) > 0;
526 $error = $cust_pkg->change(
527 'locationnum' => $new->locationnum,
530 if ( $error and not ref($error) ) {
531 $dbh->rollback if $oldAutoCommit;
532 return "Error moving pkgnum ".$cust_pkg->pkgnum.": $error";
536 $error = $old->disable_if_unused;
538 $dbh->rollback if $oldAutoCommit;
539 return "Error disabling old location: $error";
542 $dbh->commit if $oldAutoCommit;
548 Attempts to parse data for location_type and location_number from address1
556 return '' if $self->get('location_type')
557 || $self->get('location_number');
560 if ( 1 ) { #ikano, switch on via config
561 { no warnings 'void';
562 eval { 'use FS::part_export::ikano;' };
565 %parse = FS::part_export::ikano->location_types_parse;
570 foreach my $from ('address1', 'address2') {
571 foreach my $parse ( keys %parse ) {
572 my $value = $self->get($from);
573 if ( $value =~ s/(^|\W+)$parse\W+(\w+)\W*$//i ) {
574 $self->set('location_type', $parse{$parse});
575 $self->set('location_number', $2);
576 $self->set($from, $value);
582 #nothing matched, no changes
583 $self->get('address2')
584 ? "Can't parse unit type and number from address2"
590 Moves data from location_type and location_number to the end of address1.
597 #false laziness w/geocode_Mixin.pm::line
598 my $lt = $self->get('location_type');
602 if ( 1 ) { #ikano, switch on via config
603 { no warnings 'void';
604 eval { 'use FS::part_export::ikano;' };
607 %location_type = FS::part_export::ikano->location_types;
609 %location_type = (); #?
612 $self->address1( $self->address1. ' '. $location_type{$lt} || $lt );
613 $self->location_type('');
616 if ( length($self->location_number) ) {
617 $self->address1( $self->address1. ' '. $self->location_number );
618 $self->location_number('');
626 Returns the label of the location object.
634 Customer object (see L<FS::cust_main>)
638 Prospect object (see L<FS::prospect_main>)
642 String used to join location elements
646 Don't label the default service location as "Default service location".
647 May become the default at some point.
654 my( $self, %opt ) = @_;
656 my $prefix = $self->label_prefix;
657 $prefix .= ($opt{join_string} || ': ') if $prefix;
658 $prefix = '' if $opt{'no_prefix'};
660 $prefix . $self->SUPER::location_label(%opt);
665 Returns the optional site ID string (based on the cust_location-label_prefix
666 config option), "Default service location", or the empty string.
674 Customer object (see L<FS::cust_main>)
678 Prospect object (see L<FS::prospect_main>)
685 my( $self, %opt ) = @_;
687 my $cust_or_prospect = $opt{cust_main} || $opt{prospect_main};
688 unless ( $cust_or_prospect ) {
689 if ( $self->custnum ) {
690 $cust_or_prospect = FS::cust_main->by_key($self->custnum);
691 } elsif ( $self->prospectnum ) {
692 $cust_or_prospect = FS::prospect_main->by_key($self->prospectnum);
697 if ( $label_prefix eq 'CoStAg' ) {
698 my $agent = $conf->config('cust_main-custnum-display_prefix',
699 $cust_or_prospect->agentnum)
700 || $cust_or_prospect->agent->agent;
701 # else this location is invalid
702 $prefix = uc( join('',
704 ($self->state =~ /^(..)/),
706 sprintf('%05d', $self->locationnum)
709 } elsif ( $label_prefix eq '_location' && $self->locationname ) {
710 $prefix = $self->locationname;
712 } elsif ( ( $opt{'cust_main'} || $self->custnum )
713 && $self->locationnum == $cust_or_prospect->ship_locationnum ) {
714 $prefix = 'Default service location';
720 =item county_state_county
722 Returns a string consisting of just the county, state and country.
726 sub county_state_country {
728 my $label = $self->country;
729 $label = $self->state.", $label" if $self->state;
730 $label = $self->county." County, $label" if $self->county;
740 return '' unless $self->custnum;
741 qsearchs('cust_main', { 'custnum' => $self->custnum } );
750 =item process_censustract_update LOCATIONNUM
752 Queueable function to update the census tract to the current year (as set in
753 the 'census_year' configuration variable) and retrieve the new tract code.
757 sub process_censustract_update {
758 eval "use FS::GeocodeCache";
760 my $locationnum = shift;
762 qsearchs( 'cust_location', { locationnum => $locationnum })
763 or die "locationnum '$locationnum' not found!\n";
765 my $new_year = $conf->config('census_year') or return;
766 my $loc = FS::GeocodeCache->new( $cust_location->location_hash );
767 $loc->set_censustract;
768 my $error = $loc->get('censustract_error');
769 die $error if $error;
770 $cust_location->set('censustract', $loc->get('censustract'));
771 $cust_location->set('censusyear', $new_year);
772 $error = $cust_location->replace;
773 die $error if $error;
777 =item process_set_coord
779 Queueable function to find and fill in coordinates for all locations that
780 lack them. Because this uses the Google Maps API, it's internally rate
781 limited and must run in a single process.
785 sub process_set_coord {
787 # avoid starting multiple instances of this job
788 my @others = qsearch('queue', {
789 'status' => 'locked',
791 'jobnum' => {op=>'!=', value=>$job->jobnum},
795 $job->update_statustext('finding locations to update');
796 my @missing_coords = qsearch('cust_location', {
802 my $n = scalar @missing_coords;
803 for my $cust_location (@missing_coords) {
804 $cust_location->set_coord;
805 my $error = $cust_location->replace;
807 warn "error geocoding location#".$cust_location->locationnum.": $error\n";
810 $job->update_statustext("updated $i / $n locations");
811 dbh->commit; # so that we don't have to wait for the whole thing to finish
812 # Rate-limit to stay under the Google Maps usage limit (2500/day).
813 # 86,400 / 35 = 2,468 lookups per day.
818 die "failed to update ".$n-$i." locations\n";
823 =item process_standardize [ LOCATIONNUMS ]
825 Performs address standardization on locations with unclean addresses,
826 using whatever method you have configured. If the standardize_* method
827 returns a I<clean> address match, the location will be updated. This is
828 always an in-place update (because the physical location is the same,
829 and is just being referred to by a more accurate name).
831 Disabled locations will be skipped, as nobody cares.
833 If any LOCATIONNUMS are provided, only those locations will be updated.
837 sub process_standardize {
839 my @others = qsearch('queue', {
840 'status' => 'locked',
842 'jobnum' => {op=>'!=', value=>$job->jobnum},
845 my @locationnums = grep /^\d+$/, @_;
846 my $where = "AND locationnum IN(".join(',',@locationnums).")"
847 if scalar(@locationnums);
848 my @locations = qsearch({
849 table => 'cust_location',
850 hashref => { addr_clean => '', disabled => '' },
853 my $n_todo = scalar(@locations);
858 eval "use Text::CSV";
859 open $log, '>', "$FS::UID::cache_dir/process_standardize-" .
860 time2str('%Y%m%d',time) .
862 my $csv = Text::CSV->new({binary => 1, eol => "\n"});
864 foreach my $cust_location (@locations) {
865 $job->update_statustext( int(100 * $n_done/$n_todo) . ",$n_done / $n_todo locations" ) if $job;
866 my $result = FS::GeocodeCache->standardize($cust_location);
867 if ( $result->{addr_clean} and !$result->{error} ) {
868 my @cols = ($cust_location->locationnum);
869 foreach (keys %$result) {
870 push @cols, $cust_location->get($_), $result->{$_};
871 $cust_location->set($_, $result->{$_});
873 # bypass immutable field restrictions
874 my $error = $cust_location->FS::Record::replace;
875 warn "location ".$cust_location->locationnum.": $error\n" if $error;
876 $csv->print($log, \@cols);
879 dbh->commit; # so that we can resume if interrupted
888 L<FS::cust_main_county>, L<FS::cust_pkg>, L<FS::Record>,
889 schema.html from the base documentation.