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

Latest revision as of 17:14, 6 February 2009

NAME

FS::cust_pkg - Object methods for cust_pkg objects

SYNOPSIS

 use FS::cust_pkg;

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

 $error = $record->insert;

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

 $error = $record->delete;

 $error = $record->check;

 $error = $record->cancel;

 $error = $record->suspend;

 $error = $record->unsuspend;

 $part_pkg = $record->part_pkg;

 @labels = $record->labels;

 $seconds = $record->seconds_since($timestamp);

 $error = FS::cust_pkg::order( $custnum, \@pkgparts );
 $error = FS::cust_pkg::order( $custnum, \@pkgparts, \@remove_pkgnums ] );

DESCRIPTION

An FS::cust_pkg object represents a customer billing item. FS::cust_pkg inherits from FS::Record. The following fields are currently supported:

pkgnum

Primary key (assigned automatically for new billing items)

custnum

Customer (see FS::cust_main)

pkgpart

Billing item definition (see FS::part_pkg)

locationnum

Optional link to package location (see FS::location)

setup

date

bill

date (next bill date)

last_bill

last bill date

adjourn

date

susp

date

expire

date

cancel

date

otaker

order taker (assigned automatically if null, see FS::UID)

manual_flag

If this field is set to 1, disables the automatic unsuspension of this package when using the unsuspendauto config option.

quantity

If not set, defaults to 1

change_date

Date of change from previous package

change_pkgnum

Previous pkgnum

change_pkgpart

Previous pkgpart

change_locationnum

Previous locationnum

Note: setup, last_bill, bill, adjourn, susp, expire, cancel and change_date are specified as UNIX timestamps; see "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.

METHODS

new HASHREF

Create a new billing item. To add the item to the database, see "insert".

insert [ OPTION => VALUE ... ]

Adds this billing item to the database ("Orders" the item). If there is an error, returns the error, otherwise returns false.

If the additional field promo_code is defined instead of pkgpart, it will be used to look up the package definition and agent restrictions will be ignored.

If the additional field refnum is defined, an FS::pkg_referral record will be created and inserted. Multiple FS::pkg_referral records can be created by setting refnum to an array reference of refnums or a hash reference with refnums as keys. If no refnum is defined, a default FS::pkg_referral record will be created corresponding to cust_main.refnum.

The following options are available:

change

If set true, supresses any referral credit to a referring customer.

options

cust_pkg_option records will be created

delete

This method now works but you probably shouldn't use it.

You don't want to delete billing items, because there would then be no record the customer ever purchased the item. Instead, see the cancel method.

replace [ OLD_RECORD ] [ HASHREF | OPTION => VALUE ... ]

Replaces the OLD_RECORD with this one in the database. If there is an error, returns the error, otherwise returns false.

Currently, custnum, setup, bill, adjourn, susp, expire, and cancel may be changed.

Changing pkgpart may have disasterous effects. See the order subroutine.

setup and bill are normally updated by calling the bill method of a customer object (see FS::cust_main).

suspend is normally updated by the suspend and unsuspend methods.

cancel is normally updated by the cancel method (and also the order subroutine in some cases).

Available options are:

reason

can be set to a cancellation reason (see FS:reason), either a reasonnum of an existing reason, or passing a hashref will create a new reason. The hashref should have the following keys: typenum - Reason type (see FS::reason_type, reason - Text of the new reason.

reason_otaker

the access_user (see FS::access_user) providing the reason

options

hashref of keys and values - cust_pkg_option records will be created, updated or removed as appopriate

check

Checks all fields to make sure this is a valid billing item. If there is an error, returns the error, otherwise returns false. Called by the insert and replace methods.

cancel [ OPTION => VALUE ... ]

Cancels and removes all services (see FS::cust_svc and FS::part_svc) in this package, then cancels the package itself (sets the cancel field to now).

Available options are:

quiet - can be set true to supress email cancellation notices.

; time - can be set to cancel the package based on a specific future or historical date. Using time ensures that the remaining amount is calculated correctly. Note however that this is an immediate cancel and just changes the date. You are PROBABLY looking to expire the account instead of using this.:; reason - can be set to a cancellation reason (see FS:reason), either a reasonnum of an existing reason, or passing a hashref will create a new reason. The hashref should have the following keys: typenum - Reason type (see FS::reason_type, reason - Text of the new reason.:; date - can be set to a unix style timestamp to specify when to cancel (expire)

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

cancel_if_expired [ NOW_TIMESTAMP ]

Cancels this package if its expire date has been reached.

unexpire

Cancels any pending expiration (sets the expire field to null).

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

suspend [ OPTION => VALUE ... ]

Suspends all services (see FS::cust_svc and FS::part_svc) in this package, then suspends the package itself (sets the susp field to now).

Available options are:

reason - can be set to a cancellation reason (see FS

reason), either a reasonnum of an existing reason, or passing a hashref will create a new reason. The hashref should have the following keys: typenum - Reason type (see FS::reason_type, reason - Text of the new reason.:; date - can be set to a unix style timestamp to specify when to suspend (adjourn)

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

unsuspend [ OPTION => VALUE ... ]

Unsuspends all services (see FS::cust_svc and FS::part_svc) in this package, then unsuspends the package itself (clears the susp field and the adjourn field if it is in the past).

Available options are:

adjust_next_bill

Can be set true to adjust the next bill date forward by the amount of time the account was inactive. This was set true by default since 1.4.2 and 1.5.0pre6; however, starting with 1.7.0 this needs to be explicitly requested. Price plans for which this makes sense (anniversary-date based than prorate or subscription) could have an option to enable this behaviour?

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

unadjourn

Cancels any pending suspension (sets the adjourn field to null).

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

change HASHREF | OPTION => VALUE ...

Changes this package: cancels it and creates a new one, with a different pkgpart or locationnum or both. All services are transferred to the new package (no change will be made if this is not possible).

Options may be passed as a list of key/value pairs or as a hash reference. Options are:

locaitonnum

New locationnum, to change the location for this package.

cust_location

New FS::cust_location object, to create a new location and assign it to this package.

pkgpart

New pkgpart (see FS::part_pkg).

refnum

New refnum (see FS::part_referral).

At least one option must be specified (otherwise, what's the point?)

Returns either the new FS::cust_pkg object or a scalar error.

For example:

 my $err_or_new_cust_pkg = $old_cust_pkg->change

last_bill

Returns the last bill date, or if there is no last bill date, the setup date. Useful for billing metered services.

last_cust_pkg_reason ACTION

Returns the most recent ACTION FS::cust_pkg_reason associated with the package. Returns false if there is no reason or the package is not currenly ACTION'd ACTION is one of adjourn, susp, cancel, or expire.

last_reason ACTION

Returns the most recent ACTION FS::reason associated with the package. Returns false if there is no reason or the package is not currenly ACTION'd ACTION is one of adjourn, susp, cancel, or expire.

part_pkg

Returns the definition for this billing item, as an FS::part_pkg object (see FS::part_pkg).

old_cust_pkg

Returns the cancelled package this package was changed from, if any.

calc_setup

Calls the calc_setup of the FS::part_pkg object associated with this billing item.

calc_recur

Calls the calc_recur of the FS::part_pkg object associated with this billing item.

calc_remain

Calls the calc_remain of the FS::part_pkg object associated with this billing item.

calc_cancel

Calls the calc_cancel of the FS::part_pkg object associated with this billing item.

cust_bill_pkg

Returns any invoice line items for this package (see FS::cust_bill_pkg).

cust_pkg_detail [ DETAILTYPE ]

Returns any customer package details for this package (see FS::cust_pkg_detail).

DETAILTYPE can be set to "I" for invoice details or "C" for comments.

set_cust_pkg_detail DETAILTYPE [ DETAIL, DETAIL, ... ]

Sets customer package details for this package (see FS::cust_pkg_detail).

DETAILTYPE can be set to "I" for invoice details or "C" for comments.

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

cust_event

Returns the new-style customer billing events (see FS::cust_event) for this invoice.

num_cust_event

Returns the number of new-style customer billing events (see FS::cust_event) for this invoice.

cust_svc [ SVCPART ]

Returns the services for this package, as FS::cust_svc objects (see FS::cust_svc). If a svcpart is specified, return only the matching services.

overlimit [ SVCPART ]

Returns the services for this package which have exceeded their usage limit as FS::cust_svc objects (see FS::cust_svc). If a svcpart is specified, return only the matching services.

h_cust_svc END_TIMESTAMP [ START_TIMESTAMP ]

Returns historical services for this package created before END TIMESTAMP and (optionally) not cancelled before START_TIMESTAMP, as FS::h_cust_svc objects (see FS::h_cust_svc).

num_cust_svc [ SVCPART ]

Returns the number of provisioned services for this package. If a svcpart is specified, counts only the matching services.

available_part_svc

Returns a list of FS::part_svc objects representing services included in this package but not yet provisioned. Each FS::part_svc object also has an extra field, num_avail, which specifies the number of available services.

part_svc

Returns a list of FS::part_svc objects representing provisioned and available services included in this package. Each FS::part_svc object also has the following extra fields:

num_cust_svc (count)

; num_avail (quantity - count):; cust_pkg_svc (services) - array reference containing the provisioned services, as cust_svc objects

svcnum label -> ($cust_svc->label)[1]

extra_part_svc

Returns a list of FS::part_svc objects corresponding to services in this package which are still provisioned but not (any longer) available in the package definition.

status

Returns a short status string for this package, currently:

not yet billed

; one-time charge:; active:; suspended:; cancelled; statuses

Class method that returns the list of possible status strings for packages (see the status method). For example:

 @statuses = FS::cust_pkg->statuses();

statuscolor

Returns a hex triplet color string for this package's status.

labels

Returns a list of lists, calling the label method for all services (see FS::cust_svc) of this billing item.

h_labels END_TIMESTAMP [ START_TIMESTAMP ]

Like the labels method, but returns historical information on services that were active as of END_TIMESTAMP and (optionally) not cancelled before START_TIMESTAMP.

Returns a list of lists, calling the label method for all (historical) services (see FS::h_cust_svc) of this billing item.

h_labels_short END_TIMESTAMP [ START_TIMESTAMP ]

Like h_labels, except returns a simple flat list, and shortens long (currently >5 or the cust_bill-max_same_services configuration value) lists of identical services to one line that lists the service label and the number of individual services rather than individual items.

cust_main

Returns the parent customer object (see FS::cust_main).

cust_location

Returns the location object, if any (see FS::cust_location).

cust_location_or_main

If this package is associated with a location, returns the locaiton (see FS::cust_location), otherwise returns the customer (see FS::cust_main).

seconds_since TIMESTAMP

Returns the number of seconds all accounts (see FS::svc_acct) in this package have been online since TIMESTAMP, according to the session monitor.

TIMESTAMP is specified as a UNIX timestamp; see "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.

seconds_since_sqlradacct TIMESTAMP_START TIMESTAMP_END

Returns the numbers of seconds all accounts (see FS::svc_acct) in this package have been online between TIMESTAMP_START (inclusive) and TIMESTAMP_END (exclusive).

TIMESTAMP_START and TIMESTAMP_END are specified as UNIX timestamps; see "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.

attribute_since_sqlradacct TIMESTAMP_START TIMESTAMP_END ATTRIBUTE

Returns the sum of the given attribute for all accounts (see FS::svc_acct) in this package for sessions ending between TIMESTAMP_START (inclusive) and TIMESTAMP_END (exclusive).

TIMESTAMP_START and TIMESTAMP_END are specified as UNIX timestamps; see "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.

quantity; transfer DEST_PKGNUM | DEST_CUST_PKG, [ OPTION => VALUE ... ]

Transfers as many services as possible from this package to another package.

The destination package can be specified by pkgnum by passing an FS::cust_pkg object. The destination package must already exist.

Services are moved only if the destination allows services with the correct svcpart (not svcdb), unless the change_svcpart option is set true. Use this option with caution! No provision is made for export differences between the old and new service definitions. Probably only should be used when your exports for all service definitions of a given svcdb are identical. (attempt a transfer without it first, to move all possible svcpart-matching services)

Any services that can't be moved remain in the original package.

Returns an error, if there is one; otherwise, returns the number of services that couldn't be moved.

reexport

This method is deprecated. See the depend_jobnum option to the insert and order_pkgs methods in FS::cust_main for a better way to defer provisioning.

CLASS METHODS

recurring_sql

Returns an SQL expression identifying recurring packages.

onetime_sql

Returns an SQL expression identifying one-time packages.

active_sql

Returns an SQL expression identifying active packages.

inactive_sql

Returns an SQL expression identifying inactive packages (one-time packages that are otherwise unsuspended/uncancelled).

susp_sql =item suspended_sql

Returns an SQL expression identifying suspended packages.

cancel_sql =item cancelled_sql

Returns an SQL exprression identifying cancelled packages.

search_sql HASHREF

(Class method)

Returns a qsearch hash expression to search for parameters specified in HASHREF. Valid parameters are

agentnum

; magic

active, inactive, suspended, cancel (or cancelled)

status

active, inactive, suspended, one-time charge, inactive, cancel (or cancelled)

classnum

; pkgpart

list specified how?

setup

arrayref of beginning and ending epoch date

last_bill

arrayref of beginning and ending epoch date

bill

arrayref of beginning and ending epoch date

adjourn

arrayref of beginning and ending epoch date

susp

arrayref of beginning and ending epoch date

expire

arrayref of beginning and ending epoch date

cancel

arrayref of beginning and ending epoch date

query

pkgnum or APKG_pkgnum

cust_fields

a value suited to passing to FS::UI::Web::cust_header

CurrentUser

specifies the user for agent virtualization

location_sql

Returns a list: the first item is an SQL fragment identifying matching packages/customers via location (taking into account shipping and package address taxation, if enabled), and subsequent items are the parameters to substitute for the placeholders in that fragment.

SUBROUTINES

order CUSTNUM, PKGPARTS_ARYREF, [ REMOVE_PKGNUMS_ARYREF [ RETURN_CUST_PKG_ARRAYREF [ REFNUM ] ] ]

CUSTNUM is a customer (see FS::cust_main)

PKGPARTS is a list of pkgparts specifying the the billing item definitions (see FS::part_pkg) to order for this customer. Duplicates are of course permitted.

REMOVE_PKGNUMS is an optional list of pkgnums specifying the billing items to remove for this customer. The services (see FS::cust_svc) are moved to the new billing items. An error is returned if this is not possible (see FS::pkg_svc). An empty arrayref is equivalent to not specifying this parameter.

RETURN_CUST_PKG_ARRAYREF, if specified, will be filled in with the newly-created cust_pkg objects.

REFNUM, if specified, will specify the FS::pkg_referral record to be created and inserted. Multiple FS::pkg_referral records can be created by setting refnum to an array reference of refnums or a hash reference with refnums as keys. If no refnum is defined, a default FS::pkg_referral record will be created corresponding to cust_main.refnum.

bulk_change PKGPARTS_ARYREF, REMOVE_PKGNUMS_ARYREF [ RETURN_CUST_PKG_ARRAYREF ]

A bulk change method to change packages for multiple customers.

PKGPARTS is a list of pkgparts specifying the the billing item definitions (see FS::part_pkg) to order for each customer. Duplicates are of course permitted.

REMOVE_PKGNUMS is an list of pkgnums specifying the billing items to replace. The services (see FS::cust_svc) are moved to the new billing items. An error is returned if this is not possible (see FS::pkg_svc).

RETURN_CUST_PKG_ARRAYREF, if specified, will be filled in with the newly-created cust_pkg objects.

insert_reason

Associates this package with a (suspension or cancellation) reason (see FS::cust_pkg_reason, possibly inserting a new reason on the fly (see FS::reason).

Available options are:

reason

can be set to a cancellation reason (see FS:reason), either a reasonnum of an existing reason, or passing a hashref will create a new reason. The hashref should have the following keys: typenum - Reason type (see FS::reason_type, reason - Text of the new reason.

reason_otaker

the access_user (see FS::access_user) providing the reason

date

a unix timestamp

action

the action (cancel, susp, adjourn, expire) associated with the reason

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

set_usage USAGE_VALUE_HASHREF

USAGE_VALUE_HASHREF is a hashref of svc_acct usage columns and the amounts to which they should be set (see FS::svc_acct). Currently seconds, upbytes, downbytes, and totalbytes are appropriate keys.

All svc_accts which are part of this package have their values reset.

recharge USAGE_VALUE_HASHREF

USAGE_VALUE_HASHREF is a hashref of svc_acct usage columns and the amounts to which they should be set (see FS::svc_acct). Currently seconds, upbytes, downbytes, and totalbytes are appropriate keys.

All svc_accts which are part of this package have their values incremented.

BUGS

sub order is not OO. Perhaps it should be moved to FS::cust_main and made so?

In sub order, the @pkgparts array (passed by reference) is clobbered.

Also in sub order, no money is adjusted. Once FS::part_pkg defines a standard method to pass dates to the recur_prog expression, it should do so.

FS::svc_acct, FS::svc_domain, FS::svc_www, FS::svc_ip and FS::svc_forward are loaded via 'use' at compile time, rather than via 'require' in sub { setup, suspend, unsuspend, cancel } because they use %FS::UID::callback to load configuration values. Probably need a subroutine which decides what to do based on whether or not we've fetched the user yet, rather than a hash. See FS::UID and the TODO.

Now that things are transactional should the check in the insert method be moved to check ?

SEE ALSO

FS::Record, FS::cust_main, FS::part_pkg, FS::cust_svc, FS::pkg_svc, schema.html from the base documentation

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 2431:

You forgot a '=back' before '=head1'