Freeside:3:Documentation:Developer/FS/cust pkg

From Freeside
Jump to: navigation, search

NAME

FS::cust_pkg - Object methods for cust_pkg objects

SYNOPSIS

 use FS::cust_pkg;

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

 $error = $record->insert;

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

 $error = $record->delete;

 $error = $record->check;

 $error = $record->cancel;

 $error = $record->suspend;

 $error = $record->unsuspend;

 $part_pkg = $record->part_pkg;

 @labels = $record->labels;

 $seconds = $record->seconds_since($timestamp);

 #bulk cancel+order... perhaps slightly deprecated, only used by the bulk
 # cancel+order in the web UI and nowhere else (edit/process/cust_pkg.cgi)
 $error = FS::cust_pkg::order( $custnum, \@pkgparts );
 $error = FS::cust_pkg::order( $custnum, \@pkgparts, \@remove_pkgnums ] );

DESCRIPTION

An FS::cust_pkg object represents a customer billing item. FS::cust_pkg inherits from FS::Record. The following fields are currently supported:

pkgnum
Primary key (assigned automatically for new billing items)
custnum
Customer (see FS::cust_main)
pkgpart
Billing item definition (see FS::part_pkg)
locationnum
Optional link to package location (see FS::location)
order_date
date package was ordered (also remains same on changes)
start_date
date
setup
date
bill
date (next bill date)
last_bill
last bill date
adjourn
date
susp
date
expire
date
contract_end
date
cancel
date
usernum
order taker (see FS::access_user)
manual_flag
If this field is set to 1, disables the automatic unsuspension of this package when using the unsuspendauto config option.
quantity
If not set, defaults to 1
change_date
Date of change from previous package
change_pkgnum
Previous pkgnum
change_pkgpart
Previous pkgpart
change_locationnum
Previous locationnum
waive_setup; main_pkgnum
The pkgnum of the package that this package is supplemental to, if any.
pkglinknum
The package link (FS::part_pkg_link) that defines this supplemental package, if it is one.
change_to_pkgnum
The pkgnum of the package this one will be "changed to" in the future (on its expiration date).

Note: setup, last_bill, bill, adjourn, susp, expire, cancel and change_date are specified as UNIX timestamps; see "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.

METHODS

new HASHREF
Create a new billing item. To add the item to the database, see "insert".
set_initial_timers
If required by the package definition, sets any automatic expire, adjourn, or contract_end timers to some number of months after the start date (or setup date, if the package has already been setup). If the package has a delayed setup fee after a period of "free days", will also set the start date to the end of that period.
insert [ OPTION => VALUE ... ]
Adds this billing item to the database ("Orders" the item). If there is an error, returns the error, otherwise returns false.
If the additional field promo_code is defined instead of pkgpart, it will be used to look up the package definition and agent restrictions will be ignored.
If the additional field refnum is defined, an FS::pkg_referral record will be created and inserted. Multiple FS::pkg_referral records can be created by setting refnum to an array reference of refnums or a hash reference with refnums as keys. If no refnum is defined, a default FS::pkg_referral record will be created corresponding to cust_main.refnum.
The following options are available:
change
If set true, supresses actions that should only be taken for new package orders. (Currently this includes: intro periods when delay_setup is on, auto-adding a 1st start date, auto-adding expiration/adjourn/contract_end dates)
options
cust_pkg_option records will be created
ticket_subject
a ticket will be added to this customer with this subject
ticket_queue
an optional queue name for ticket additions
allow_pkgpart
Don't check the legality of the package definition. This should be used when performing a package change that doesn't change the pkgpart (i.e. a location change).
delete
This method now works but you probably shouldn't use it.
You don't want to delete packages, because there would then be no record the customer ever purchased the package. Instead, see the cancel method and hide cancelled packages.
replace [ OLD_RECORD ] [ HASHREF | OPTION => VALUE ... ]
Replaces the OLD_RECORD with this one in the database. If there is an error, returns the error, otherwise returns false.
Currently, custnum, setup, bill, adjourn, susp, expire, and cancel may be changed.
Changing pkgpart may have disasterous effects. See the order subroutine.
setup and bill are normally updated by calling the bill method of a customer object (see FS::cust_main).
suspend is normally updated by the suspend and unsuspend methods.
cancel is normally updated by the cancel method (and also the order subroutine in some cases).
Available options are:
reason
can be set to a cancellation reason (see FS:reason), either a reasonnum of an existing reason, or passing a hashref will create a new reason. The hashref should have the following keys: typenum - Reason type (see FS::reason_type, reason - Text of the new reason.
reason_otaker
the access_user (see FS::access_user) providing the reason
options
hashref of keys and values - cust_pkg_option records will be created, updated or removed as appopriate
check
Checks all fields to make sure this is a valid billing item. If there is an error, returns the error, otherwise returns false. Called by the insert and replace methods.
check_pkgpart
Check the pkgpart to make sure it's allowed with the reg_code and/or promo_code of the package (if present) and with the customer's agent. Called from insert, unless we are doing a package change that doesn't affect pkgpart.
cancel [ OPTION => VALUE ... ]
Cancels and removes all services (see FS::cust_svc and FS::part_svc) in this package, then cancels the package itself (sets the cancel field to now).
Available options are:
quiet - can be set true to supress email cancellation notices.
; time - can be set to cancel the package based on a specific future or historical date. Using time ensures that the remaining amount is calculated correctly. Note however that this is an immediate cancel and just changes the date. You are PROBABLY looking to expire the account instead of using this.:; reason - can be set to a cancellation reason (see FS:reason), either a reasonnum of an existing reason, or passing a hashref will create a new reason. The hashref should have the following keys: typenum - Reason type (see FS::reason_type, reason - Text of the new reason.:; date - can be set to a unix style timestamp to specify when to cancel (expire):; nobill - can be set true to skip billing if it might otherwise be done.:; unused_credit - can be set to 1 to credit the remaining time, or 0 to not credit it. This must be set (by change()) when changing the package to a different pkgpart or location, and probably shouldn't be in any other case. If it's not set, the 'unused_credit_cancel' part_pkg option will be used.:; no_delay_cancel - prevents delay_cancel behavior no matter what other options say, for use when changing packages (or any other time you're really sure you want an immediate cancel)
If there is an error, returns the error, otherwise returns false.
cancel_if_expired [ NOW_TIMESTAMP ]
Cancels this package if its expire date has been reached.
uncancel
"Un-cancels" this package: Orders a new package with the same custnum, pkgpart, locationnum, (other fields?). Attempts to re-provision cancelled services using history information (errors at this stage are not fatal).
cust_pkg: pass a scalar reference, will be filled in with the new cust_pkg object
svc_fatal: service provisioning errors are fatal
svc_errors: pass an array reference, will be filled in with any provisioning errors
main_pkgnum: link the package as a supplemental package of this one. For internal use only.
unexpire
Cancels any pending expiration (sets the expire field to null).
If there is an error, returns the error, otherwise returns false.
suspend [ OPTION => VALUE ... ]
Suspends all services (see FS::cust_svc and FS::part_svc) in this package, then suspends the package itself (sets the susp field to now).
Available options are:
reason - can be set to a cancellation reason (see FS
reason), either a reasonnum of an existing reason, or passing a hashref will create a new reason. The hashref should have the following keys: - typenum - Reason type (see FS::reason_type - reason - Text of the new reason.:; date - can be set to a unix style timestamp to specify when to suspend (adjourn):; time - can be set to override the current time, for calculation of final invoices or unused-time credits:; resume_date - can be set to a time when the package should be unsuspended. This may be more convenient than calling unsuspend() separately.:; from_main - allows a supplemental package to be suspended, rather than redirecting the method call to its main package. For internal use.:; from_cancel - used when suspending from the cancel method, forces this to skip everything besides basic suspension. For internal use.
If there is an error, returns the error, otherwise returns false.
credit_remaining MODE TIME
Generate a credit for this package for the time remaining in the current billing period. MODE is either "suspend" or "cancel" (determines the credit type). TIME is the time of suspension/cancellation. Both arguments are mandatory.
unsuspend [ OPTION => VALUE ... ]
Unsuspends all services (see FS::cust_svc and FS::part_svc) in this package, then unsuspends the package itself (clears the susp field and the adjourn field if it is in the past). If the suspend reason includes an unsuspension package, that package will be ordered.
Available options are:
date
Can be set to a date to unsuspend the package in the future (the 'resume' field).
adjust_next_bill
Can be set true to adjust the next bill date forward by the amount of time the account was inactive. This was set true by default in the past (from 1.4.2 and 1.5.0pre6 through 1.7.0), but now needs to be explicitly requested with this option or in the price plan.
If there is an error, returns the error, otherwise returns false.
unadjourn
Cancels any pending suspension (sets the adjourn field to null).
If there is an error, returns the error, otherwise returns false.
change HASHREF | OPTION => VALUE ...
Changes this package: cancels it and creates a new one, with a different pkgpart or locationnum or both. All services are transferred to the new package (no change will be made if this is not possible).
Options may be passed as a list of key/value pairs or as a hash reference. Options are:
locationnum
New locationnum, to change the location for this package.
cust_location
New FS::cust_location object, to create a new location and assign it to this package.
cust_main
New FS::cust_main object, to create a new customer and assign the new package to it.
pkgpart
New pkgpart (see FS::part_pkg).
refnum
New refnum (see FS::part_referral).
quantity
New quantity; if unspecified, the new package will have the same quantity as the old.
cust_pkg
"New" (existing) FS::cust_pkg object. The package's services and other attributes will be transferred to this package.
keep_dates
Set to true to transfer billing dates (start_date, setup, last_bill, bill, susp, adjourn, cancel, expire, and contract_end) to the new package.
unprotect_svcs
Normally, change() will rollback and return an error if some services can't be transferred (also see the cust_pkg-change_svcpart config option). If unprotect_svcs is true, this method will transfer as many services as it can and then unconditionally cancel the old package.
contract_end
If specified, sets this value for the contract_end date on the new package (without regard for keep_dates or the usual date-preservation behavior.) Will throw an error if defined but false; the UI doesn't allow editing this unless it already exists, making removal impossible to undo.
At least one of locationnum, cust_location, pkgpart, refnum, cust_main, or cust_pkg must be specified (otherwise, what's the point?)
Returns either the new FS::cust_pkg object or a scalar error.
For example:

 my $err_or_new_cust_pkg = $old_cust_pkg->change

change_later OPTION => VALUE...
Schedule a package change for a later date. This actually orders the new package immediately, but sets its start date for a future date, and sets the current package to expire on the same date.
If the package is already scheduled for a change, this can be called with 'start_date' to change the scheduled date, or with pkgpart and/or locationnum to modify the package change. To cancel the scheduled change entirely, see abort_change.
Options include:
start_date
The date for the package change. Required, and must be in the future.
pkgpart
; locationnum:; quantity:; contract_end
The pkgpart, locationnum, quantity and optional contract_end of the new package, with the same meaning as in change.
abort_change
Cancels a future package change scheduled by change_later.
set_quantity QUANTITY
Change the package's quantity field. This is one of the few package properties that can safely be changed without canceling and reordering the package (because it doesn't affect tax eligibility). Returns an error or an empty string.
set_salesnum SALESNUM
Change the package's salesnum (sales person) field. This is one of the few package properties that can safely be changed without canceling and reordering the package (because it doesn't affect tax eligibility). Returns an error or an empty string.
modify_charge OPTIONS
Change the properties of a one-time charge. The following properties can be changed this way: - pkg: the package description - classnum: the package class - additional: arrayref of additional invoice details to add to this package
and, if the charge has not yet been billed: - start_date: the date when it will be billed - amount: the setup fee to be charged - quantity: the multiplier for the setup fee - separate_bill: whether to put the charge on a separate invoice
If you pass 'adjust_commission' => 1, and the classnum changes, and there are commission credits linked to this charge, they will be recalculated.
last_bill
Returns the last bill date, or if there is no last bill date, the setup date. Useful for billing metered services.
last_cust_pkg_reason ACTION
Returns the most recent ACTION FS::cust_pkg_reason associated with the package. Returns false if there is no reason or the package is not currenly ACTION'd ACTION is one of adjourn, susp, cancel, or expire.
last_reason ACTION
Returns the most recent ACTION FS::reason associated with the package. Returns false if there is no reason or the package is not currenly ACTION'd ACTION is one of adjourn, susp, cancel, or expire.
part_pkg
Returns the definition for this billing item, as an FS::part_pkg object (see FS::part_pkg).
old_cust_pkg
Returns the cancelled package this package was changed from, if any.
change_cust_main
Returns the customter this package was detached to, if any.
calc_setup
Calls the calc_setup of the FS::part_pkg object associated with this billing item.
calc_recur
Calls the calc_recur of the FS::part_pkg object associated with this billing item.
base_recur
Calls the base_recur of the FS::part_pkg object associated with this billing item.
calc_remain
Calls the calc_remain of the FS::part_pkg object associated with this billing item.
calc_cancel
Calls the calc_cancel of the FS::part_pkg object associated with this billing item.
cust_bill_pkg
Returns any invoice line items for this package (see FS::cust_bill_pkg).
cust_pkg_detail [ DETAILTYPE ]
Returns any customer package details for this package (see FS::cust_pkg_detail).
DETAILTYPE can be set to "I" for invoice details or "C" for comments.
set_cust_pkg_detail DETAILTYPE [ DETAIL, DETAIL, ... ]
Sets customer package details for this package (see FS::cust_pkg_detail).
DETAILTYPE can be set to "I" for invoice details or "C" for comments.
If there is an error, returns the error, otherwise returns false.
cust_event
Returns the customer billing events (see FS::cust_event) for this invoice.
num_cust_event
Returns the number of customer billing events (see FS::cust_event) for this package.
exists_cust_event
Returns true if there are customer billing events (see FS::cust_event) for this package. More efficient than using num_cust_event.
cust_svc [ SVCPART ] (old, deprecated usage); cust_svc [ OPTION => VALUE ... ] (current usage); cust_svc_unsorted [ OPTION => VALUE ... ]
Returns the services for this package, as FS::cust_svc objects (see FS::cust_svc). Available options are svcpart and svcdb. If either is spcififed, returns only the matching services.
As an optimization, use the cust_svc_unsorted version if you are not displaying the results.
overlimit [ SVCPART ]
Returns the services for this package which have exceeded their usage limit as FS::cust_svc objects (see FS::cust_svc). If a svcpart is specified, return only the matching services.
h_cust_svc END_TIMESTAMP [ START_TIMESTAMP ] [ MODE ]
Returns historical services for this package created before END TIMESTAMP and (optionally) not cancelled before START_TIMESTAMP, as FS::h_cust_svc objects (see FS::h_cust_svc). If MODE is 'I' (for 'invoice'), services with the pkg_svc.hidden flag will be omitted.
num_cust_svc [ SVCPART ] (old, deprecated usage); num_cust_svc [ OPTION => VALUE ... ] (current usage)
Returns the number of services for this package. Available options are svcpart and svcdb. If either is spcififed, returns only the matching services.
available_part_svc
Returns a list of FS::part_svc objects representing services included in this package but not yet provisioned. Each FS::part_svc object also has an extra field, num_avail, which specifies the number of available services.
Accepts option provision_hold; if true, only returns part_svc for which the associated pkg_svc has the provision_hold flag set.
part_svc [ OPTION => VALUE ... ]
Returns a list of FS::part_svc objects representing provisioned and available services included in this package. Each FS::part_svc object also has the following extra fields:
num_cust_svc
(count)
num_avail
(quantity - count)
cust_pkg_svc
(services) - array reference containing the provisioned services, as cust_svc objects
Accepts two options:
summarize_size
If true, will omit the extra cust_pkg_svc option for objects where num_cust_svc is this size or greater.
hide_discontinued
If true, will omit looking for services that are no longer avaialble in the package definition.
extra_part_svc
Returns a list of FS::part_svc objects corresponding to services in this package which are still provisioned but not (any longer) available in the package definition.
status
Returns a short status string for this package, currently:
on hold
; not yet billed:; one-time charge:; active:; suspended:; cancelled; ucfirst_status
Returns the status with the first character capitalized.
statuses
Class method that returns the list of possible status strings for packages (see the status method). For example:

 @statuses = FS::cust_pkg->statuses();

statuscolor
Returns a hex triplet color string for this package's status.
is_status_delay_cancel
Returns true if part_pkg has option delay_cancel, cust_pkg status is 'suspended' and expire is set to cancel package within the next day (or however many days are set in global config part_pkg-delay_cancel-days.
Accepts option part_pkg-delay_cancel-days which should be the value of the config setting, to avoid looking it up again.
This is not a real status, this only meant for hacking display values, because otherwise treating the package as suspended is really the whole point of the delay_cancel option.
pkg_label
Returns a label for this package. (Currently "pkgnum: pkg - comment" or "pkg - comment" depending on user preference).
pkg_label_long
Returns a long label for this package, adding the primary service's label to pkg_label.
pkg_locale
Returns a customer-localized label for this package.
primary_cust_svc
Returns a primary service (as FS::cust_svc object) if one can be identified.
labels
Returns a list of lists, calling the label method for all services (see FS::cust_svc) of this billing item.
h_labels END_TIMESTAMP [ START_TIMESTAMP ] [ MODE ]
Like the labels method, but returns historical information on services that were active as of END_TIMESTAMP and (optionally) not cancelled before START_TIMESTAMP. If MODE is 'I' (for 'invoice'), services with the pkg_svc.hidden flag will be omitted.
Returns a list of lists, calling the label method for all (historical) services (see FS::h_cust_svc) of this billing item.
labels_short
Like labels, except returns a simple flat list, and shortens long (currently >5 or the cust_bill-max_same_services configuration value) lists of identical services to one line that lists the service label and the number of individual services rather than individual items.
h_labels_short END_TIMESTAMP [ START_TIMESTAMP ]
Like h_labels, except returns a simple flat list, and shortens long (currently >5 or the cust_bill-max_same_services configuration value) lists of identical services to one line that lists the service label and the number of individual services rather than individual items.
cust_main
Returns the parent customer object (see FS::cust_main).
balance
Returns the balance for this specific package, when using experimental package balance.
cust_location
Returns the location object, if any (see FS::cust_location).
cust_location_or_main
If this package is associated with a location, returns the locaiton (see FS::cust_location), otherwise returns the customer (see FS::cust_main).
location_label [ OPTION => VALUE ... ]
Returns the label of the location object (see FS::cust_location).
tax_locationnum
Returns the foreign key to a FS::cust_location object for calculating tax on this package, as determined by the tax-pkg_address and tax-ship_address configuration flags.
tax_location
Returns the FS::cust_location object for tax_locationnum.
seconds_since TIMESTAMP
Returns the number of seconds all accounts (see FS::svc_acct) in this package have been online since TIMESTAMP, according to the session monitor.
TIMESTAMP is specified as a UNIX timestamp; see "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.
seconds_since_sqlradacct TIMESTAMP_START TIMESTAMP_END
Returns the numbers of seconds all accounts (see FS::svc_acct) in this package have been online between TIMESTAMP_START (inclusive) and TIMESTAMP_END (exclusive).
TIMESTAMP_START and TIMESTAMP_END are specified as UNIX timestamps; see "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.
attribute_since_sqlradacct TIMESTAMP_START TIMESTAMP_END ATTRIBUTE
Returns the sum of the given attribute for all accounts (see FS::svc_acct) in this package for sessions ending between TIMESTAMP_START (inclusive) and TIMESTAMP_END (exclusive).
TIMESTAMP_START and TIMESTAMP_END are specified as UNIX timestamps; see "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.
quantity; transfer DEST_PKGNUM | DEST_CUST_PKG, [ OPTION => VALUE ... ]
Transfers as many services as possible from this package to another package.
The destination package can be specified by pkgnum by passing an FS::cust_pkg object. The destination package must already exist.
Services are moved only if the destination allows services with the correct svcpart (not svcdb), unless the change_svcpart option is set true. Use this option with caution! No provision is made for export differences between the old and new service definitions. Probably only should be used when your exports for all service definitions of a given svcdb are identical. (attempt a transfer without it first, to move all possible svcpart-matching services)
Any services that can't be moved remain in the original package.
Returns an error, if there is one; otherwise, returns the number of services that couldn't be moved.
grab_svcnums SVCNUM, SVCNUM ...
Change the pkgnum for the provided services to this packages. If there is an error, returns the error, otherwise returns false.
reexport
This method is deprecated. See the depend_jobnum option to the insert and order_pkgs methods in FS::cust_main for a better way to defer provisioning.
export_pkg_change OLD_CUST_PKG
Calls the "pkg_change" export action for all services attached to this package.
insert_reason
Associates this package with a (suspension or cancellation) reason (see FS::cust_pkg_reason, possibly inserting a new reason on the fly (see FS::reason).
Available options are:
reason
can be set to a cancellation reason (see FS:reason), either a reasonnum of an existing reason, or passing a hashref will create a new reason. The hashref should have the following keys: typenum - Reason type (see FS::reason_type, reason - Text of the new reason.
reason_otaker
the access_user (see FS::access_user) providing the reason
date
a unix timestamp
action
the action (cancel, susp, adjourn, expire) associated with the reason
If there is an error, returns the error, otherwise returns false.
insert_discount
Associates this package with a discount (see FS::cust_pkg_discount, possibly inserting a new discount on the fly (see FS::discount).
Available options are:
discountnum
If there is an error, returns the error, otherwise returns false.
set_usage USAGE_VALUE_HASHREF
USAGE_VALUE_HASHREF is a hashref of svc_acct usage columns and the amounts to which they should be set (see FS::svc_acct). Currently seconds, upbytes, downbytes, and totalbytes are appropriate keys.
All svc_accts which are part of this package have their values reset.
recharge USAGE_VALUE_HASHREF
USAGE_VALUE_HASHREF is a hashref of svc_acct usage columns and the amounts to which they should be set (see FS::svc_acct). Currently seconds, upbytes, downbytes, and totalbytes are appropriate keys.
All svc_accts which are part of this package have their values incremented.
cust_pkg_discount; cust_pkg_discount_active; cust_pkg_usage
Returns a list of all voice usage counters attached to this package.
apply_usage OPTIONS
Takes the following options: - cdr: a call detail record (FS::cdr) - rate_detail: the rate determined for this call (FS::rate_detail) - minutes: the maximum number of minutes to be charged
Finds available usage minutes for a call of this class, and subtracts up to that many minutes from the usage pool. If the usage pool is empty, and the cdr-minutes_priority global config option is set, minutes may be taken from other calls as well. Either way, an allocation record will be created (FS::cdr_cust_pkg_usage) and this method will return the number of minutes of usage applied to the call.
supplemental_pkgs
Returns a list of all packages supplemental to this one.
main_pkg
Returns the package that this one is supplemental to, if any.

CLASS METHODS

recurring_sql
Returns an SQL expression identifying recurring packages.
onetime_sql
Returns an SQL expression identifying one-time packages.
ordered_sql
Returns an SQL expression identifying ordered packages (recurring packages not yet billed).
active_sql
Returns an SQL expression identifying active packages.
not_yet_billed_sql
Returns an SQL expression identifying packages which have not yet been billed.
inactive_sql
Returns an SQL expression identifying inactive packages (one-time packages that are otherwise unsuspended/uncancelled).
on_hold_sql
Returns an SQL expression identifying on-hold packages.
susp_sql =item suspended_sql
Returns an SQL expression identifying suspended packages.
cancel_sql =item cancelled_sql
Returns an SQL exprression identifying cancelled packages.
status_sql
Returns an SQL expression to give the package status as a string.
search HASHREF
(Class method)
Returns a qsearch hash expression to search for parameters specified in HASHREF. Valid parameters are
agentnum
; status
on hold, active, inactive (or one-time charge), suspended, canceled (or cancelled)
magic
Equivalent to "status", except that "canceled"/"cancelled" will exclude packages that were changed into a new package with the same pkgpart (i.e. location or quantity changes).
custom
boolean selects custom packages

classnum
; pkgpart
pkgpart or arrayref or hashref of pkgparts
setup
arrayref of beginning and ending epoch date
last_bill
arrayref of beginning and ending epoch date
bill
arrayref of beginning and ending epoch date
adjourn
arrayref of beginning and ending epoch date
susp
arrayref of beginning and ending epoch date
expire
arrayref of beginning and ending epoch date
cancel
arrayref of beginning and ending epoch date
query
pkgnum or APKG_pkgnum
cust_fields
a value suited to passing to FS::UI::Web::cust_header
CurrentUser
specifies the user for agent virtualization
fcc_line
boolean; if true, returns only packages with more than 0 FCC phone lines.
state, country
Limit to packages with a service location in the specified state and country. For FCC 477 reporting, mostly.
location_cust
Limit to packages whose service locations are the same as the customer's default service location.
location_nocust
Limit to packages whose service locations are not the customer's default service location.
location_census
Limit to packages whose service locations have census tracts.
location_nocensus
Limit to packages whose service locations do not have a census tract.
location_geocode
Limit to packages whose locations have geocodes.
location_geocode
Limit to packages whose locations do not have geocodes.
towernum
Limit to packages associated with a svc_broadband, associated with a sector, associated with this towernum (or any of these, if it's an arrayref) (or NO towernum, if it's zero). This is an extreme niche case.
477part, 477rownum, date
Limit to packages included in a specific row of one of the FCC 477 reports. '477part' is the section name (see FS::Report::FCC_477 methods), 'date' is the report as-of date (completely unrelated to the package setup/bill/ other date fields), and '477rownum' is the row number of the report starting with zero. Row numbers have no inherent meaning, so this is useful only for explaining a 477 report you've already run.
fcc_477_count
Returns a list of two package counts. The first is a count of packages based on the supplied criteria and the second is the count of residential packages with those same criteria. Criteria are specified as in the search method.
tax_locationnum_sql
Returns an SQL expression for the tax location for a package, based on the settings of 'tax-pkg_address' and 'tax-ship_address'.
location_sql
Returns a list: the first item is an SQL fragment identifying matching packages/customers via location (taking into account shipping and package address taxation, if enabled), and subsequent items are the parameters to substitute for the placeholders in that fragment.

SUBROUTINES

order CUSTNUM, PKGPARTS_ARYREF, [ REMOVE_PKGNUMS_ARYREF [ RETURN_CUST_PKG_ARRAYREF [ REFNUM ] ] ]
Bulk cancel + order subroutine. Perhaps slightly deprecated, only used by the bulk cancel+order in the web UI and nowhere else (edit/process/cust_pkg.cgi)
CUSTNUM is a customer (see FS::cust_main)
PKGPARTS is a list of pkgparts specifying the the billing item definitions (see FS::part_pkg) to order for this customer. Duplicates are of course permitted.
REMOVE_PKGNUMS is an optional list of pkgnums specifying the billing items to remove for this customer. The services (see FS::cust_svc) are moved to the new billing items. An error is returned if this is not possible (see FS::pkg_svc). An empty arrayref is equivalent to not specifying this parameter.
RETURN_CUST_PKG_ARRAYREF, if specified, will be filled in with the newly-created cust_pkg objects.
REFNUM, if specified, will specify the FS::pkg_referral record to be created and inserted. Multiple FS::pkg_referral records can be created by setting refnum to an array reference of refnums or a hash reference with refnums as keys. If no refnum is defined, a default FS::pkg_referral record will be created corresponding to cust_main.refnum.
bulk_change PKGPARTS_ARYREF, REMOVE_PKGNUMS_ARYREF [ RETURN_CUST_PKG_ARRAYREF ]
A bulk change method to change packages for multiple customers.
PKGPARTS is a list of pkgparts specifying the the billing item definitions (see FS::part_pkg) to order for each customer. Duplicates are of course permitted.
REMOVE_PKGNUMS is an list of pkgnums specifying the billing items to replace. The services (see FS::cust_svc) are moved to the new billing items. An error is returned if this is not possible (see FS::pkg_svc).
RETURN_CUST_PKG_ARRAYREF, if specified, will be filled in with the newly-created cust_pkg objects.
forward_emails
Returns a hash of svcnums and corresponding email addresses for svc_acct services that can be used as source or dest for svc_forward services provisioned in this package.
Accepts options svc_forward OR svcnum for a svc_forward service; if included, will ensure the current values of the specified service are included in the list, even if for some other reason they wouldn't be. If called as a class method with a specified service, returns only these current values.
Caution: does not actually check if svc_forward services are available to be provisioned on this package.

BUGS

sub order is not OO. Perhaps it should be moved to FS::cust_main and made so?

In sub order, the @pkgparts array (passed by reference) is clobbered.

Also in sub order, no money is adjusted. Once FS::part_pkg defines a standard method to pass dates to the recur_prog expression, it should do so.

FS::svc_acct, FS::svc_domain, FS::svc_www, FS::svc_ip and FS::svc_forward are loaded via 'use' at compile time, rather than via 'require' in sub { setup, suspend, unsuspend, cancel } because they use %FS::UID::callback to load configuration values. Probably need a subroutine which decides what to do based on whether or not we've fetched the user yet, rather than a hash. See FS::UID and the TODO.

Now that things are transactional should the check in the insert method be moved to check ?

SEE ALSO

FS::Record, FS::cust_main, FS::part_pkg, FS::cust_svc, FS::pkg_svc, schema.html from the base documentation

POD ERRORS

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

Around line 5511:
You forgot a '=back' before '=head1'