Difference between revisions of "Freeside:3:Documentation:Developer/FS/part pkg"
m (Edit via perl MediaWiki framework (1.13)) |
m (Edit via perl MediaWiki framework (1.13)) |
||
Line 27: | Line 27: | ||
An FS::part_pkg object represents a package definition. FS::part_pkg inherits from FS::Record. The following fields are currently supported: | 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 [[Freeside:3:Documentation:Developer/FS/pkg class|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 [[Freeside:3:Documentation:Developer/FS/part pkg option|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 [[Freeside:3:Documentation:Developer/FS/agent|FS::agent]]); fcc_ds0s - Optional DS0 equivalency number for FCC form 477; 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. | + | ; 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 [[Freeside:3:Documentation:Developer/FS/pkg class|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 [[Freeside:3:Documentation:Developer/FS/part pkg option|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 [[Freeside:3:Documentation:Developer/FS/agent|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 |
==METHODS== | ==METHODS== | ||
; new HASHREF | ; new HASHREF | ||
Line 67: | Line 67: | ||
; propagate OLD | ; 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. | :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. | ||
+ | ; 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... ] | ; 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. | :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. | ||
Line 123: | Line 127: | ||
; svc_part_pkg_link | ; svc_part_pkg_link | ||
:Returns the associated part_pkg_link records (see [[Freeside:3:Documentation:Developer/FS/part pkg link|FS::part_pkg_link]]). | :Returns the associated part_pkg_link records (see [[Freeside:3:Documentation:Developer/FS/part pkg link|FS::part_pkg_link]]). | ||
+ | ; supp_part_pkg_link | ||
+ | :Returns the associated part_pkg_link records of type 'supp' (supplemental packages). | ||
; part_pkg_taxoverride [ CLASS ] | ; part_pkg_taxoverride [ CLASS ] | ||
:Returns all associated FS::part_pkg_taxoverride objects (see [[Freeside:3:Documentation:Developer/FS/part pkg taxoverride|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 [[Freeside:3:Documentation:Developer/FS/usage class|FS::usage_class]]). When a class is specified, the empty string class (default) is returned if no more specific values exist. | :Returns all associated FS::part_pkg_taxoverride objects (see [[Freeside:3:Documentation:Developer/FS/part pkg taxoverride|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 [[Freeside:3:Documentation:Developer/FS/usage class|FS::usage_class]]). When a class is specified, the empty string class (default) is returned if no more specific values exist. | ||
Line 131: | Line 137: | ||
; taxproduct_description [ CLASS ] | ; taxproduct_description [ CLASS ] | ||
:Returns the description of the associated tax product for this package definition (see [[Freeside:3:Documentation:Developer/FS/part pkg taxproduct|FS::part_pkg_taxproduct]]). | :Returns the description of the associated tax product for this package definition (see [[Freeside:3:Documentation:Developer/FS/part pkg taxproduct|FS::part_pkg_taxproduct]]). | ||
− | ; | + | ; tax_rates DATA_PROVIDER, GEOCODE, [ CLASS ] |
− | :Returns the | + | :Returns the tax table entries ([[Freeside:3:Documentation:Developer/FS/tax rate|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 <tt>usage_class</tt> number). |
; part_pkg_discount | ; part_pkg_discount | ||
:Returns the package to discount m2m records (see [[Freeside:3:Documentation:Developer/FS/part pkg discount|FS::part_pkg_discount]]) for this package. | :Returns the package to discount m2m records (see [[Freeside:3:Documentation:Developer/FS/part pkg discount|FS::part_pkg_discount]]) for this package. | ||
+ | ; part_pkg_usage | ||
+ | :Returns the voice usage pools (see [[Freeside:3:Documentation:Developer/FS/part pkg usage|FS::part_pkg_usage]]) defined for this package. | ||
; _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"]]. | ||
; 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) | ||
+ | ; 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 | ; format OPTION DATA | ||
:Returns data formatted according to the function 'format' described in the plan info. Returns DATA if no such function exists. | :Returns data formatted according to the function 'format' described in the plan info. Returns DATA if no such function exists. |
Revision as of 14:37, 27 June 2014
Contents
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
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.
- 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 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.
- 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.
- 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.
- 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.