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

Latest revision as of 17:15, 6 February 2009

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'; 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)

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 `(CUSTOM) ' is prepended to the comment field. 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.

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, 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.

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.

pkg_comment

Returns an (internal) string representing this package. Currently, "pkgpart: pkg - comment", is returned. "pkg - comment" may be returned in the future, omitting pkgpart.

pkg_class

Returns the package class, as an FS::pkg_class object, or the empty string if there is no 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.

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.

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,

svcpart_unique_svcdb SVCDB

Returns the svcpart of the 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

Adds the frequency of this package to the provided timestamp and returns the resulting timestamp, or -1 if the frequency of this package could not be parsed (shouldn't happen).

plandata

For backwards compatibility, returns the plandata field as well as all options from FS::part_pkg_option.

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

Returns the option value for the given name, or the empty string.

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).

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).

part_pkg_taxrate DATA_PROVIDER, GEOCODE, [ CLASS ]

Returns the package to taxrate m2m records for this package in the location specified by GEOCODE (see FS::part_pkg_taxrate) and usage class CLASS. CLASS may be one of 'setup', 'recur', or one of the usage classes numbers (see FS::usage_class).

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

SUBROUTINES

plan_info; 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.

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

SEE ALSO

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