Difference between revisions of "Freeside:3:Documentation:Developer/FS/part pkg"

From Freeside
Jump to: navigation, search
m (Edit via perl MediaWiki framework (1.13))
m (Edit via perl MediaWiki framework (1.13))
 
(One intermediate revision by the same user not shown)
Line 38: Line 38:
 
:Currently available options are: ''pkg_svc'', ''primary_svc'', ''cust_pkg'', ''custnum_ref'' and ''options''.
 
:Currently available options are: ''pkg_svc'', ''primary_svc'', ''cust_pkg'', ''custnum_ref'' and ''options''.
  
:If ''pkg_svc'' is set to a hashref with svcparts as keys and quantities as values, appropriate FS::pkg_svc records will be inserted. ''hidden_svc'' can be set to a hashref of svcparts and flag values ('Y' or '') to set the 'hidden' field in these records.
+
:If ''pkg_svc'' is set to a hashref with svcparts as keys and quantities as values, appropriate FS::pkg_svc records will be inserted. ''hidden_svc'' can be set to a hashref of svcparts and flag values ('Y' or '') to set the 'hidden' field in these records, and ''provision_hold'' can be set similarly for the 'provision_hold' field in these records.
  
 
:If ''primary_svc'' is set to the svcpart of the primary service, the appropriate FS::pkg_svc record will be updated.
 
:If ''primary_svc'' is set to the svcpart of the primary service, the appropriate FS::pkg_svc record will be updated.
Line 49: Line 49:
  
 
:If ''options'' is set to a hashref of options, appropriate FS::part_pkg_option records will be inserted.
 
:If ''options'' is set to a hashref of options, appropriate FS::part_pkg_option records will be inserted.
 
:If ''part_pkg_currency'' is set to a hashref of options (with the keys as option_CURRENCY), appropriate FS::part_pkg::currency records will be inserted.
 
 
; delete
 
; delete
 
:Currently unimplemented.
 
:Currently unimplemented.
Line 56: Line 54:
 
:Replaces OLD_RECORD with this one in the database. If there is an error, returns the error, otherwise returns false.
 
:Replaces OLD_RECORD with this one in the database. If there is an error, returns the error, otherwise returns false.
  
:Currently available options are: ''pkg_svc'', ''hidden_svc'', ''primary_svc'' and ''options''
+
:Currently available options are: ''pkg_svc'', ''hidden_svc'', ''primary_svc'', ''provision_hold'' and ''options''
  
:If ''pkg_svc'' is set to a hashref with svcparts as keys and quantities as values, the appropriate FS::pkg_svc records will be replaced. ''hidden_svc'' can be set to a hashref of svcparts and flag values ('Y' or '') to set the 'hidden' field in these records. ''bulk_skip'' can be set to a hashref of svcparts and flag values ('Y' or '') to set the 'bulk_skip' field in those records.
+
:If ''pkg_svc'' is set to a hashref with svcparts as keys and quantities as values, the appropriate FS::pkg_svc records will be replaced. ''hidden_svc'' can be set to a hashref of svcparts and flag values ('Y' or '') to set the 'hidden' field in these records. ''provision_hold'' can be set to a hashref of svcparts and flag values ('Y' or '') to set the field in those records.
  
 
:If ''primary_svc'' is set to the svcpart of the primary service, the appropriate FS::pkg_svc record will be updated.
 
:If ''primary_svc'' is set to the svcpart of the primary service, the appropriate FS::pkg_svc record will be updated.
  
 
:If ''options'' is set to a hashref, the appropriate FS::part_pkg_option records will be replaced.
 
:If ''options'' is set to a hashref, the appropriate FS::part_pkg_option records will be replaced.
 
:If ''part_pkg_currency'' is set to a hashref of options (with the keys as option_CURRENCY), appropriate FS::part_pkg::currency records will be replaced.
 
 
; check
 
; check
 
:Checks all fields to make sure this is a valid package definition. If there is an error, returns the error, otherwise returns false. Called by the insert and replace methods.
 
:Checks all fields to make sure this is a valid package definition. If there is an error, returns the error, otherwise returns false. Called by the insert and replace methods.
Line 129: Line 125:
 
; option OPTIONNAME [ QUIET ]
 
; option OPTIONNAME [ QUIET ]
 
:Returns the option value for the given name, or the empty string. If a true value is passed as the second argument, warnings about missing the option will be suppressed.
 
:Returns the option value for the given name, or the empty string. If a true value is passed as the second argument, warnings about missing the option will be suppressed.
; part_pkg_currency [ CURRENCY ]
 
:Returns all currency options as FS::part_pkg_currency objects (see [[Freeside:3:Documentation:Developer/FS/part pkg currency|FS::part_pkg_currency]]), or, if a currency is specified, only return the objects for that currency.
 
; part_pkg_currency_options CURRENCY
 
:Returns a list of option names and values from FS::part_pkg_currency for the specified currency.
 
; part_pkg_currency_option CURRENCY OPTIONNAME
 
:Returns the option value for the given name and currency.
 
 
; fcc_option OPTIONNAME
 
; fcc_option OPTIONNAME
 
:Returns the FCC 477 report option value for the given name, or the empty string.
 
:Returns the FCC 477 report option value for the given name, or the empty string.
Line 161: Line 151:
 
; _rebless
 
; _rebless
 
:Reblesses the object into the FS::part_pkg::PLAN class (if available), where PLAN is the object's ''plan'' field. There should be better docs on how to create new price plans, but until then, see [[#NEW PLAN CLASSES|"NEW PLAN CLASSES"]].
 
:Reblesses the object into the FS::part_pkg::PLAN class (if available), where PLAN is the object's ''plan'' field. There should be better docs on how to create new price plans, but until then, see [[#NEW PLAN CLASSES|"NEW PLAN CLASSES"]].
; calc_setup CUST_PKG START_DATE DETAILS_ARRAYREF OPTIONS_HASHREF; calc_recur CUST_PKG START_DATE DETAILS_ARRAYREF OPTIONS_HASHREF
 
:Calculates and returns the setup or recurring fees, respectively, for this package. Implementation is in the FS::part_pkg:* module specific to this price plan.
 
 
:Adds invoicing details to the passed-in DETAILS_ARRAYREF
 
 
:Options are passed as a hashref. Available options:
 
:; freq_override
 
::Frequency override (for calc_recur)
 
:; discounts
 
::This option is filled in by the method rather than controlling its operation. It is an arrayref. Applicable discounts will be added to the arrayref, as [[Freeside:3:Documentation:Developer/FS/cust bill pkg discount records|FS/cust bill pkg discount|FS::cust_bill_pkg_discount records|FS::cust_bill_pkg_discount]].
 
:; real_pkgpart
 
::For package add-ons, is the base [[package definition|FS::part_pkg]], otherwise no different than pkgpart.
 
:; precommit_hooks
 
::This option is filled in by the method rather than controlling its operation. It is an arrayref. Anonymous coderefs will be added to the arrayref. They need to be called before completing the billing operation. For calc_recur only.
 
:; increment_next_bill
 
::Increment the next bill date (boolean, for calc_recur). Typically true except for particular situations.
 
:; setup_fee
 
::This option is filled in by the method rather than controlling its operation. It indicates a deferred setup fee that is billed at calc_recur time (see price plan option prorate_defer_bill).
 
 
:Note: Don't calculate prices when not actually billing the package. For that, see the [[Freeside:3:Documentation:Developer/base setup|/base setup|base_setup|/base_setup]] and [[Freeside:3:Documentation:Developer/base recur|/base recur|base_recur|/base_recur]] methods.
 
; calc_remain CUST_PKG [ OPTION => VALUE ... ]
 
:Calculates and returns the remaining value to be credited upon package suspension, change, or cancellation, if enabled.
 
 
:Options are passed as a list of keys and values. Available options:
 
:; time
 
::Override for the current time
 
:; cust_credit_source_bill_pkg
 
::This option is filled in by the method rather than controlling its operation. It is an arrayref. [[Freeside:3:Documentation:Developer/FS/cust credit source bill pkg|FS/cust credit source bill pkg|FS::cust_credit_source_bill_pkg|FS::cust_credit_source_bill_pkg]] records will be added to the arrayref indicating the specific line items and amounts which are the source of this remaining credit.
 
 
:Note: Don't calculate prices when not actually suspending or cancelling the package.
 
; calc_units CUST_PKG
 
:This returns the number of provisioned svc_phone records, or, of the package count_available_phones option is set, the number available to be provisoined in the package.
 
; calc_cancel START_DATE DETAILS_ARRAYREF OPTIONS_HASHREF
 
:Runs any necessary billing on cancellation: another recurring cycle for recur_temporailty 'preceding' pacakges with the bill_recur_on_cancel option set (calc_recur), or, any outstanding usage for pacakges with the bill_usage_on_cancel option set (calc_usage).
 
 
; recur_cost_permonth CUST_PKG
 
; recur_cost_permonth CUST_PKG
 
:recur_cost divided by freq (only supported for monthly and longer frequencies)
 
:recur_cost divided by freq (only supported for monthly and longer frequencies)

Latest revision as of 07:21, 28 September 2015

NAME

FS::part_pkg - Object methods for part_pkg objects

SYNOPSIS

 use FS::part_pkg;

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

 $custom_record = $template_record->clone;

 $error = $record->insert;

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

 $error = $record->delete;

 $error = $record->check;

 @pkg_svc = $record->pkg_svc;

 $svcnum = $record->svcpart;
 $svcnum = $record->svcpart( 'svc_acct' );

DESCRIPTION

An FS::part_pkg object represents a package definition. FS::part_pkg inherits from FS::Record. The following fields are currently supported:

pkgpart - primary key (assigned automatically for new package definitions); pkg - Text name of this package definition (customer-viewable); comment - Text name of this package definition (non-customer-viewable); classnum - Optional package class (see FS::pkg_class); promo_code - Promotional code; setup - Setup fee expression (deprecated); freq - Frequency of recurring fee; recur - Recurring fee expression (deprecated); setuptax - Setup fee tax exempt flag, empty or `Y'; recurtax - Recurring fee tax exempt flag, empty or `Y'; taxclass - Tax class; plan - Price plan; plandata - Price plan data (deprecated - see FS::part_pkg_option instead); disabled - Disabled flag, empty or `Y'; custom - Custom flag, empty or `Y'; setup_cost - for cost tracking; recur_cost - for cost tracking; pay_weight - Weight (relative to credit_weight and other package definitions) that controls payment application to specific line items.; credit_weight - Weight (relative to other package definitions) that controls credit application to specific line items.; agentnum - Optional agentnum (see FS::agent); fcc_ds0s - Optional DS0 equivalency number for FCC form 477; fcc_voip_class - Which column of FCC form 477 part II.B this package belongs in.; successor - Foreign key for the part_pkg that replaced this record. If this record is not obsolete, will be null.; family_pkgpart - Foreign key for the part_pkg that was the earliest ancestor of this record. If this record is not a successor to another part_pkg, will be equal to pkgpart.; delay_start - Number of days to delay package start, by default; start_on_hold - 'Y' to suspend this package immediately when it is ordered. The package will not start billing or have a setup fee charged until it is manually unsuspended.

METHODS

new HASHREF
Creates a new package definition. To add the package definition to the database, see "insert".
clone
An alternate constructor. Creates a new package definition by duplicating an existing definition. A new pkgpart is assigned and the custom flag is set to Y. To add the package definition to the database, see "insert".
insert [ , OPTION => VALUE ... ]
Adds this package definition to the database. If there is an error, returns the error, otherwise returns false.
Currently available options are: pkg_svc, primary_svc, cust_pkg, custnum_ref and options.
If pkg_svc is set to a hashref with svcparts as keys and quantities as values, appropriate FS::pkg_svc records will be inserted. hidden_svc can be set to a hashref of svcparts and flag values ('Y' or '') to set the 'hidden' field in these records, and provision_hold can be set similarly for the 'provision_hold' field in these records.
If primary_svc is set to the svcpart of the primary service, the appropriate FS::pkg_svc record will be updated.
If cust_pkg is set to a pkgnum of a FS::cust_pkg record (or the FS::cust_pkg record itself), the object will be updated to point to this package definition.
In conjunction with cust_pkg, if custnum_ref is set to a scalar reference, the scalar will be updated with the custnum value from the cust_pkg record.
If tax_overrides is set to a hashref with usage classes as keys and comma separated tax class numbers as values, appropriate FS::part_pkg_taxoverride records will be inserted.
If options is set to a hashref of options, appropriate FS::part_pkg_option records will be inserted.
delete
Currently unimplemented.
replace OLD_RECORD [ , OPTION => VALUE ... ]
Replaces OLD_RECORD with this one in the database. If there is an error, returns the error, otherwise returns false.
Currently available options are: pkg_svc, hidden_svc, primary_svc, provision_hold and options
If pkg_svc is set to a hashref with svcparts as keys and quantities as values, the appropriate FS::pkg_svc records will be replaced. hidden_svc can be set to a hashref of svcparts and flag values ('Y' or '') to set the 'hidden' field in these records. provision_hold can be set to a hashref of svcparts and flag values ('Y' or '') to set the field in those records.
If primary_svc is set to the svcpart of the primary service, the appropriate FS::pkg_svc record will be updated.
If options is set to a hashref, the appropriate FS::part_pkg_option records will be replaced.
check
Checks all fields to make sure this is a valid package definition. If there is an error, returns the error, otherwise returns false. Called by the insert and replace methods.
supersede OLD [, OPTION => VALUE ... ]
Inserts this package as a successor to the package OLD. All options are as for insert. After inserting, disables OLD and sets the new package as its successor.
propagate OLD
If any of certain fields have changed from OLD to this package, then, for all packages in the same lineage as this one, sets those fields to their values in this package.
set_fcc_options HASHREF
Sets the FCC options on this package definition to the values specified in HASHREF.
pkg_locale LOCALE
Returns a customer-viewable string representing this package for the given locale, from the part_pkg_msgcat table. If the given locale is empty or no localized string is found, returns the base pkg field.
part_pkg_msgcat LOCALE
Like pkg_locale, but returns the FS::part_pkg_msgcat object itself.
pkg_comment [ OPTION => VALUE... ]
Returns an (internal) string representing this package. Currently, "pkgpart: pkg - comment", is returned. "pkg - comment" may be returned in the future, omitting pkgpart. The comment will have '(CUSTOM) ' prepended if custom is Y.
If the option nopkgpart is true then the "pkgpart: ' is omitted.
pkg_class
Returns the package class, as an FS::pkg_class object, or the empty string if there is no package class.
addon_pkg_class
Returns the add-on package class, as an FS::pkg_class object, or the empty string if there is no add-on package class.
categoryname
Returns the package category name, or the empty string if there is no package category.
classname
Returns the package class name, or the empty string if there is no package class.
addon_classname
Returns the add-on package class name, or the empty string if there is no add-on package class.
agent
Returns the associated agent for this event, if any, as an FS::agent object.
pkg_svc [ HASHREF | OPTION => VALUE ]
Returns all FS::pkg_svc objects (see FS::pkg_svc) for this package definition (with non-zero quantity).
One option is available, disable_linked. If set true it will return the services for this package definition alone, omitting services from any add-on packages.
type_pkgs
Returns all FS::type_pkgs objects (see FS::type_pkgs) for this package definition.
svcpart [ SVCDB ]
Returns the svcpart of the primary service definition (see FS::part_svc) associated with this package definition (see FS::pkg_svc). Returns false if there not a primary service definition or exactly one service definition with quantity 1, or if SVCDB is specified and does not match the svcdb of the service definition. SVCDB can be specified as a scalar table name, such as 'svc_acct', or as an arrayref of possible table names.
part_svc [ SVCDB ]
Like the svcpart method, but returns the FS::part_svc object (see FS::part_svc).
svcpart_unique_svcdb SVCDB
Returns the svcpart of a service definition (see FS::part_svc) matching SVCDB associated with this package definition (see FS::pkg_svc). Returns false if there not a primary service definition for SVCDB or there are multiple service definitions for SVCDB.
payby
Returns a list of the acceptable payment types for this package. Eventually this should come out of a database table and be editable, but currently has the following logic instead:
If the package is free, the single item BILL is returned, otherwise, the single item CARD is returned.
(CHEK? LEC? Probably shouldn't accept those by default, prone to abuse)
is_free
Returns true if this package is free.
freq_pretty
Returns an english representation of the freq field, such as "monthly", "weekly", "semi-annually", etc.
add_freq TIMESTAMP [ FREQ ]
Adds a billing period of some frequency to the provided timestamp and returns the resulting timestamp, or -1 if the frequency could not be parsed (shouldn't happen). By default, the frequency of this package will be used; to override this, pass a different frequency as a second argument.
plandata
For backwards compatibility, returns the plandata field as well as all options from FS::part_pkg_option.
part_pkg_vendor
Returns all vendor/external package ids as FS::part_pkg_vendor objects (see FS::part_pkg_vendor).
vendor_pkg_ids
Returns a list of vendor/external package ids by exportnum
part_pkg_option
Returns all options as FS::part_pkg_option objects (see FS::part_pkg_option).
options
Returns a list of option names and values suitable for assigning to a hash.
option OPTIONNAME [ QUIET ]
Returns the option value for the given name, or the empty string. If a true value is passed as the second argument, warnings about missing the option will be suppressed.
fcc_option OPTIONNAME
Returns the FCC 477 report option value for the given name, or the empty string.
fcc_options
Returns all FCC 477 report options for this package, as a hash-like list.
bill_part_pkg_link
Returns the associated part_pkg_link records (see FS::part_pkg_link).
svc_part_pkg_link
Returns the associated part_pkg_link records (see FS::part_pkg_link).
supp_part_pkg_link
Returns the associated part_pkg_link records of type 'supp' (supplemental packages).
part_pkg_taxoverride [ CLASS ]
Returns all associated FS::part_pkg_taxoverride objects (see FS::part_pkg_taxoverride). Limits the returned set to those of class CLASS if defined. Class may be one of 'setup', 'recur', the empty string (default), or a usage class number (see FS::usage_class). When a class is specified, the empty string class (default) is returned if no more specific values exist.
has_taxproduct
Returns true if this package has any taxproduct associated with it.
taxproduct [ CLASS ]
Returns the associated tax product for this package definition (see FS::part_pkg_taxproduct). CLASS may be one of 'setup', 'recur' or the usage classnum (see FS::usage_class). Returns the default tax product for this record if the more specific CLASS value does not exist.
taxproduct_description [ CLASS ]
Returns the description of the associated tax product for this package definition (see FS::part_pkg_taxproduct).
tax_rates DATA_PROVIDER, GEOCODE, [ CLASS ]
Returns the tax table entries (FS::tax_rate objects) that apply to this package in the location specified by GEOCODE, for usage class CLASS (one of 'setup', 'recur', null, or a usage_class number).
part_pkg_discount
Returns the package to discount m2m records (see FS::part_pkg_discount) for this package.
part_pkg_usage
Returns the voice usage pools (see FS::part_pkg_usage) defined for this package.
_rebless
Reblesses the object into the FS::part_pkg::PLAN class (if available), where PLAN is the object's plan field. There should be better docs on how to create new price plans, but until then, see "NEW PLAN CLASSES".
recur_cost_permonth CUST_PKG
recur_cost divided by freq (only supported for monthly and longer frequencies)
cust_bill_pkg_recur CUST_PKG
Actual recurring charge for the specified customer package from customer's most recent invoice
unit_setup CUST_PKG
Returns the setup fee for one unit of the package.
setup_margin
unit_setup minus setup_cost
recur_margin_permonth
base_recur_permonth minus recur_cost_permonth
format OPTION DATA
Returns data formatted according to the function 'format' described in the plan info. Returns DATA if no such function exists.
parse OPTION DATA
Returns data parsed according to the function 'parse' described in the plan info. Returns DATA if no such function exists.

CLASS METHODS

curuser_pkgs_sql
Returns an SQL fragment for searching for packages the current user can use, either via part_pkg.agentnum directly, or via agent type (see FS::type_pkgs).
agent_pkgs_sql AGENT | AGENTNUM, ...
Returns an SQL fragment for searching for packages the provided agent or agents can use, either via part_pkg.agentnum directly, or via agent type (see FS::type_pkgs).

SUBROUTINES

plan_info

NEW PLAN CLASSES

A module should be added in FS/FS/part_pkg/ Eventually, an example may be found in eg/plan_template.pm. Until then, it is suggested that you use the other modules in FS/FS/part_pkg/ as a guide.

BUGS

The delete method is unimplemented.

setup and recur semantics are not yet defined (and are implemented in FS::cust_bill. hmm.). now they're deprecated and need to go.

plandata should go

part_pkg_taxrate is Pg specific

replace should be smarter about managing the related tables (options, pkg_svc)

SEE ALSO

FS::Record, FS::cust_pkg, FS::type_pkgs, FS::pkg_svc, Safe. schema.html from the base documentation.