FS::part_pkg - Object methods for part_pkg objects
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' );
An FS::part_pkg object represents a package definition. FS::part_pkg inherits from FS::Record. The following fields are currently supported:
Creates a new package definition. To add the package definition to the database, see "insert".
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".
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.
Currently unimplemented.
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.
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.
Pass an $options hashref that contains the values to be inserted or updated for any FS::part_pkg::MODULE.pm.
For each key in $options, validates the value by calling the 'validate' subroutine defined for that option e.g. FS::part_pkg::MODULE::plan_info()->{$KEY}->{validate}. The option validation function is only called when the hashkey for that option exists in $options.
Then the module validation function is called, from FS::part_pkg::MODULE::plan_info()->{validate}
Returns error message, or empty string if valid.
Invoked by "insert" and "replace" via the equivalent methods in FS::option_Common.
Checks pkg_svc records as a whole (for part_svc_link dependencies).
If there is an error, returns the error, otherwise returns false.
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.
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.
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.
Sets the FCC options on this package definition to the values specified in HASHREF.
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.
Like pkg_locale, but returns the FS::part_pkg_msgcat object itself.
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.
Returns the package class, as an FS::pkg_class object, or the empty string if there is no package 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.
Returns the package category name, or the empty string if there is no package category.
Returns the package class name, or the empty string if there is no package class.
Returns the add-on package class name, or the empty string if there is no add-on package class.
Returns the associated agent for this event, if any, as an FS::agent object.
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.
Returns all FS::type_pkgs objects (see FS::type_pkgs) for this package definition.
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.
Like the svcpart method, but returns the FS::part_svc object (see FS::part_svc).
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.
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)
Returns true if this package is free.
Returns an english representation of the freq field, such as "monthly", "weekly", "semi-annually", etc.
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.
For backwards compatibility, returns the plandata field as well as all options from FS::part_pkg_option.
Returns all vendor/external package ids as FS::part_pkg_vendor objects (see FS::part_pkg_vendor).
Returns a list of vendor/external package ids by exportnum
Returns all options as FS::part_pkg_option objects (see FS::part_pkg_option).
Returns a list of option names and values suitable for assigning to a hash.
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 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.
Returns a list of option names and values from FS::part_pkg_currency for the specified currency.
Returns the option value for the given name and currency.
Returns the FCC 477 report option value for the given name, or the empty string.
Returns all FCC 477 report options for this package, as a hash-like list.
Returns the associated part_pkg_link records (see FS::part_pkg_link).
Returns the associated part_pkg_link records (see FS::part_pkg_link).
Returns the associated part_pkg_link records of type 'supp' (supplemental packages).
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.
Returns true if this package has any taxproduct associated with it.
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.
Returns the description of the associated tax product for this package definition (see FS::part_pkg_taxproduct).
Returns the FS::part_pkg_taxproduct record used to report the taxable service units (usually phone lines) on this package.
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).
Returns the package to discount m2m records (see FS::part_pkg_discount) for this package.
Returns the voice usage pools (see FS::part_pkg_usage) defined for this package.
Returns the automatic transfer target for this package, or an empty string if there isn't one.
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".
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:
Frequency override (for calc_recur)
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 records.
For package add-ons, is the base FS::part_pkg package definition, otherwise no different than pkgpart.
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 the next bill date (boolean, for calc_recur). Typically true except for particular situations.
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" in FS::cust_pkg and "base_recur" in FS::cust_pkg methods.
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:
Override for the current time
This option is filled in by the method rather than controlling its operation. It is an arrayref. 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.
This returns the number of provisioned svc_phone records, or, of the package count_available_phones option is set, the number available to be provisioned in the package.
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 divided by freq (only supported for monthly and longer frequencies)
Actual recurring charge for the specified customer package from customer's most recent invoice
Returns the setup fee for one unit of the package.
unit_setup minus setup_cost
base_recur_permonth minus recur_cost_permonth
Takes an FS::cust_pkg object. If this plan has an introductory rate, returns the expected date the intro period will end. If there is no intro rate, returns zero.
Returns data formatted according to the function 'format' described in the plan info. Returns DATA if no such function exists.
Returns data parsed according to the function 'parse' described in the plan info. Returns DATA if no such function exists.
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).
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).
Returns an SQL fragment for JOINing the part_pkg_option records for this package's setup_fee and recur_fee (as setup_option and recur_option, respectively). Useful for optimization.
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.
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)
FS::Record, FS::cust_pkg, FS::type_pkgs, FS::pkg_svc, Safe. schema.html from the base documentation.