Difference between revisions of "Freeside:3:Documentation:Developer/FS/cust location"

From Freeside
Jump to: navigation, search
m (Edit via perl MediaWiki framework (1.13))
 
m (Edit via perl MediaWiki framework (1.13))
Line 50: Line 50:
  
 
:Note that this stores the hash reference, not a distinct copy of the hash it points to. You can ask the object for a copy with the ''hash'' method.
 
:Note that this stores the hash reference, not a distinct copy of the hash it points to. You can ask the object for a copy with the ''hash'' method.
 +
; find_or_insert
 +
:Finds an existing location matching the customer and address values in this location, if one exists, and sets the contents of this location equal to that one (including its locationnum).
 +
 +
:If an existing location is not found, this one ''will'' be inserted. (This is a change from the "new_or_existing" method that this replaces.)
 +
 +
:The following fields are considered "essential" and ''must'' match: custnum, address1, address2, city, county, state, zip, country, location_number, location_type, location_kind. Disabled locations will be found only if this location is set to disabled.
 +
 +
:All other fields are considered "non-essential" and will be ignored in finding a matching location. If the existing location doesn't match in these fields, it will be updated in-place to match.
 +
 +
:Returns an error string if inserting or updating a location failed.
 +
 +
:It is unfortunately hard to determine if this created a new location or not.
 
; insert
 
; insert
 
:Adds this record to the database. If there is an error, returns the error, otherwise returns false.
 
:Adds this record to the database. If there is an error, returns the error, otherwise returns false.
Line 76: Line 88:
 
; location_label
 
; location_label
 
:Returns the label of the location object, with an optional site ID string (based on the cust_location-label_prefix config option).
 
:Returns the label of the location object, with an optional site ID string (based on the cust_location-label_prefix config option).
 
+
; county_state_county
 +
:Returns a string consisting of just the county, state and country.
 +
; cust_main
 
==CLASS METHODS==
 
==CLASS METHODS==
 
; in_county_sql OPTIONS
 
; in_county_sql OPTIONS
Line 82: Line 96:
  
 
:Pass "param => 1" to receive a parameterized expression (rather than one that requires a join to cust_main_county) and a list of parameter names in order.
 
:Pass "param => 1" to receive a parameterized expression (rather than one that requires a join to cust_main_county) and a list of parameter names in order.
 +
 +
===SUBROUTINES===
 +
; process_censustract_update LOCATIONNUM
 +
:Queueable function to update the census tract to the current year (as set in the 'census_year' configuration variable) and retrieve the new tract code.
 +
; process_set_coord
 +
:Queueable function to find and fill in coordinates for all locations that lack them. Because this uses the Google Maps API, it's internally rate limited and must run in a single process.
 +
; process_standardize [ LOCATIONNUMS ]
 +
:Performs address standardization on locations with unclean addresses, using whatever method you have configured. If the standardize_* method returns a ''clean'' address match, the location will be updated. This is always an in-place update (because the physical location is the same, and is just being referred to by a more accurate name).
 +
 +
:Disabled locations will be skipped, as nobody cares.
 +
 +
:If any LOCATIONNUMS are provided, only those locations will be updated.
  
 
==BUGS==
 
==BUGS==
Line 90: Line 116:
 
Hey! '''The above document had some coding errors, which are explained below:'''
 
Hey! '''The above document had some coding errors, which are explained below:'''
  
; Around line 485:
+
; Around line 674:
 
:'=item' outside of any '=over'
 
:'=item' outside of any '=over'
; Around line 533:
+
; Around line 862:
 
:You forgot a '=back' before '=head1'
 
:You forgot a '=back' before '=head1'

Revision as of 13:33, 27 June 2014

NAME

FS::cust_location - Object methods for cust_location records

SYNOPSIS

 use FS::cust_location;

 $record = new FS::cust_location \%hash;
 $record = new FS::cust_location { 'column' => 'value' };

 $error = $record->insert;

 $error = $new_record->replace($old_record);

 $error = $record->delete;

 $error = $record->check;

DESCRIPTION

An FS::cust_location object represents a customer location. FS::cust_location inherits from FS::Record. The following fields are currently supported:

locationnum
primary key
custnum
custnum
address1
Address line one (required)
address2
Address line two (optional)
city
City
county
County (optional, see FS::cust_main_county)
state
State (see FS::cust_main_county)
zip
Zip
country
Country (see FS::cust_main_county)
geocode
Geocode
district
Tax district code (optional)
disabled
Disabled flag; set to 'Y' to disable the location.

METHODS

new HASHREF
Creates a new location. To add the location to the database, see "insert".
Note that this stores the hash reference, not a distinct copy of the hash it points to. You can ask the object for a copy with the hash method.
find_or_insert
Finds an existing location matching the customer and address values in this location, if one exists, and sets the contents of this location equal to that one (including its locationnum).
If an existing location is not found, this one will be inserted. (This is a change from the "new_or_existing" method that this replaces.)
The following fields are considered "essential" and must match: custnum, address1, address2, city, county, state, zip, country, location_number, location_type, location_kind. Disabled locations will be found only if this location is set to disabled.
All other fields are considered "non-essential" and will be ignored in finding a matching location. If the existing location doesn't match in these fields, it will be updated in-place to match.
Returns an error string if inserting or updating a location failed.
It is unfortunately hard to determine if this created a new location or not.
insert
Adds this record to the database. If there is an error, returns the error, otherwise returns false.
delete
Delete this record from the database.
replace OLD_RECORD
Replaces the OLD_RECORD with this one in the database. If there is an error, returns the error, otherwise returns false.
check
Checks all fields to make sure this is a valid location. If there is an error, returns the error, otherwise returns false. Called by the insert and replace methods.
country_full
Returns this locations's full country name
line
Synonym for location_label
has_ship_address
Returns false since cust_location objects do not have a separate shipping address.
location_hash
Returns a list of key/value pairs, with the following keys: address1, address2, city, county, state, zip, country, geocode, location_type, location_number, location_kind.
disable_if_unused
Sets the "disabled" flag on the location if it is no longer in use as a prospect location, package location, or a customer's billing or default service address.
move_to
Takes a new FS::cust_location object. Moves all packages that use the existing location to the new one, then sets the "disabled" flag on the old location. Returns nothing on success, an error message on error.
alternize
Attempts to parse data for location_type and location_number from address1 and address2.
dealternize
Moves data from location_type and location_number to the end of address1.
location_label
Returns the label of the location object, with an optional site ID string (based on the cust_location-label_prefix config option).
county_state_county
Returns a string consisting of just the county, state and country.
cust_main

CLASS METHODS

in_county_sql OPTIONS
Returns an SQL expression to test membership in a cust_main_county geographic area. By default, this requires district, city, county, state, and country to match exactly. Pass "ornull => 1" to allow partial matches where some fields are NULL in the cust_main_county record but not in the location.
Pass "param => 1" to receive a parameterized expression (rather than one that requires a join to cust_main_county) and a list of parameter names in order.

SUBROUTINES

process_censustract_update LOCATIONNUM
Queueable function to update the census tract to the current year (as set in the 'census_year' configuration variable) and retrieve the new tract code.
process_set_coord
Queueable function to find and fill in coordinates for all locations that lack them. Because this uses the Google Maps API, it's internally rate limited and must run in a single process.
process_standardize [ LOCATIONNUMS ]
Performs address standardization on locations with unclean addresses, using whatever method you have configured. If the standardize_* method returns a clean address match, the location will be updated. This is always an in-place update (because the physical location is the same, and is just being referred to by a more accurate name).
Disabled locations will be skipped, as nobody cares.
If any LOCATIONNUMS are provided, only those locations will be updated.

BUGS

SEE ALSO

FS::cust_main_county, FS::cust_pkg, FS::Record, schema.html from the base documentation.

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 674:
'=item' outside of any '=over'
Around line 862:
You forgot a '=back' before '=head1'