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 the FS::cust_main manpage)
pkgpart - Billing item definition (see the FS::part_pkg manpage)
setup - date
bill - date
susp - date
expire - date
cancel - date
otaker - order taker (assigned automatically if null, see the FS::UID manpage)
manual_flag - If this field is set to 1, disables the automatic unsuspension of this package when using the unsuspendauto config file.

Note: setup, bill, susp, expire and cancel are specified as UNIX timestamps; see perlfunc/``time''. Also see the Time::Local manpage and the Date::Parse manpage for conversion functions.

METHODS

new HASHREF

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

insert

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

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

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, 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 the FS::cust_main manpage).

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

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

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

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

suspend

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

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

unsuspend

Unsuspends all services (see the FS::cust_svc manpage and the FS::part_svc manpage) in this package, then unsuspends the package itself (clears the susp field).

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

part_pkg

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

cust_svc

Returns the services for this package, as FS::cust_svc objects (see the FS::cust_svc manpage)

labels

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

cust_main

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

seconds_since TIMESTAMP

Returns the number of seconds all accounts (see the FS::svc_acct manpage) in this package have been online since TIMESTAMP.

TIMESTAMP is specified as a UNIX timestamp; see perlfunc/``time''. Also see the Time::Local manpage and the Date::Parse manpage for conversion functions.

SUBROUTINES

order CUSTNUM, PKGPARTS_ARYREF, [ REMOVE_PKGNUMS_ARYREF [ RETURN_CUST_PKG_ARRAYREF ] ]

CUSTNUM is a customer (see the FS::cust_main manpage)

PKGPARTS is a list of pkgparts specifying the the billing item definitions (see the FS::part_pkg manpage) 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 the FS::cust_svc manpage) are moved to the new billing items. An error is returned if this is not possible (see the FS::pkg_svc manpage). 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.

VERSION

$Id: cust_pkg.html,v 1.2 2002-01-29 16:33:15 ivan Exp $

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_acct_sm, and FS::svc_domain 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 ?