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

Latest revision as of 07:25, 18 November 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.; change_to_pkgpart - When this package is ordered, schedule a future package change. The 'expire_months' field will determine when the package change occurs.; expire_months - Number of months until this package expires (or changes to another package).; adjourn_months - Number of months until this package becomes suspended.; contract_end_months - Number of months until the package's contract ends.

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.

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

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, bulk_skip, 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 and provision_hold can be set to a hashref of svcparts and flag values ('Y' or '') to set the respective 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.

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

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.

check_pkg_svc

Checks pkg_svc records as a whole (for part_svc_link dependencies).

If there is an error, returns the error, otherwise returns false.

part_svc_link OPTION => VALUE ...

Returns the service dependencies (see FS::part_svc_link) for the given search options, taking into account this package definition's agent.

Available options are any field in part_svc_link. Typically used options are src_svcpart and link_type.

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.

part_pkg_currency [ CURRENCY ]

Returns all currency options as FS::part_pkg_currency objects (see 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

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.

change_to_pkg

Returns the automatic transfer target for this package, or an empty string if there isn't one.

_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".

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 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 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 /base setup|base_setup|/base_setup and /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. 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 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.