htdocs/docs/man/cust_pkg.txt

   1 NAME
   2     FS::cust_pkg - Object methods for cust_pkg objects
   3
   4 SYNOPSIS
   5       use FS::cust_pkg;
   6
   7       $record = new FS::cust_pkg \%hash;
   8       $record = new FS::cust_pkg { 'column' => 'value' };
   9
  10       $error = $record->insert;
  11
  12       $error = $new_record->replace($old_record);
  13
  14       $error = $record->delete;
  15
  16       $error = $record->check;
  17
  18       $error = $record->cancel;
  19
  20       $error = $record->suspend;
  21
  22       $error = $record->unsuspend;
  23
  24       $part_pkg = $record->part_pkg;
  25
  26       @labels = $record->labels;
  27
  28       $error = FS::cust_pkg::order( $custnum, \@pkgparts );
  29       $error = FS::cust_pkg::order( $custnum, \@pkgparts, \@remove_pkgnums ] );
  30
  31 DESCRIPTION
  32     An FS::cust_pkg object represents a customer billing item.
  33     FS::cust_pkg inherits from FS::Record. The following fields are
  34     currently supported:
  35
  36     pkgnum - primary key (assigned automatically for new billing items)
  37     custnum - Customer (see the FS::cust_main manpage)
  38     pkgpart - Billing item definition (see the FS::part_pkg manpage)
  39     setup - date
  40     bill - date
  41     susp - date
  42     expire - date
  43     cancel - date
  44     otaker - order taker (assigned automatically if null, see the FS::UID manpage)
  45     Note: setup, bill, susp, expire and cancel are specified as UNIX
  46     timestamps; see the section on "time" in the perlfunc manpage.
  47     Also see the Time::Local manpage and the Date::Parse manpage for
  48     conversion functions.
  49
  50 METHODS
  51     new HASHREF
  52         Create a new billing item. To add the item to the database,
  53         see the section on "insert".
  54
  55     insert
  56         Adds this billing item to the database ("Orders" the item).
  57         If there is an error, returns the error, otherwise returns
  58         false.
  59
  60     delete
  61         Currently unimplemented. You don't want to delete billing
  62         items, because there would then be no record the customer
  63         ever purchased the item. Instead, see the cancel method.
  64
  65     replace OLD_RECORD
  66         Replaces the OLD_RECORD with this one in the database. If
  67         there is an error, returns the error, otherwise returns
  68         false.
  69
  70         Currently, custnum, setup, bill, susp, expire, and cancel
  71         may be changed.
  72
  73         Changing pkgpart may have disasterous effects. See the order
  74         subroutine.
  75
  76         setup and bill are normally updated by calling the bill
  77         method of a customer object (see the FS::cust_main manpage).
  78
  79         suspend is normally updated by the suspend and unsuspend
  80         methods.
  81
  82         cancel is normally updated by the cancel method (and also
  83         the order subroutine in some cases).
  84
  85     check
  86         Checks all fields to make sure this is a valid billing item.
  87         If there is an error, returns the error, otherwise returns
  88         false. Called by the insert and replace methods.
  89
  90     cancel
  91         Cancels and removes all services (see the FS::cust_svc
  92         manpage and the FS::part_svc manpage) in this package, then
  93         cancels the package itself (sets the cancel field to now).
  94
  95         If there is an error, returns the error, otherwise returns
  96         false.
  97
  98     suspend
  99         Suspends all services (see the FS::cust_svc manpage and the
 100         FS::part_svc manpage) in this package, then suspends the
 101         package itself (sets the susp field to now).
 102
 103         If there is an error, returns the error, otherwise returns
 104         false.
 105
 106     unsuspend
 107         Unsuspends all services (see the FS::cust_svc manpage and
 108         the FS::part_svc manpage) in this package, then unsuspends
 109         the package itself (clears the susp field).
 110
 111         If there is an error, returns the error, otherwise returns
 112         false.
 113
 114     part_pkg
 115         Returns the definition for this billing item, as an
 116         FS::part_pkg object (see L<FS::part_pkg).
 117
 118     labels
 119         Returns a list of lists, calling the label method for all
 120         services (see the FS::cust_svc manpage) of this billing
 121         item.
 122
 123 SUBROUTINES
 124     order CUSTNUM, PKGPARTS_ARYREF, [ REMOVE_PKGNUMS_ARYREF ]
 125         CUSTNUM is a customer (see the FS::cust_main manpage)
 126
 127         PKGPARTS is a list of pkgparts specifying the the billing
 128         item definitions (see the FS::part_pkg manpage) to order for
 129         this customer. Duplicates are of course permitted.
 130
 131         REMOVE_PKGNUMS is an optional list of pkgnums specifying the
 132         billing items to remove for this customer. The services (see
 133         the FS::cust_svc manpage) are moved to the new billing
 134         items. An error is returned if this is not possible (see the
 135         FS::pkg_svc manpage).
 136
 137 VERSION
 138     $Id: cust_pkg.txt,v 1.3 1999-02-09 09:38:01 ivan Exp $
 139
 140 BUGS
 141     sub order is not OO. Perhaps it should be moved to FS::cust_main
 142     and made so?
 143
 144     In sub order, the @pkgparts array (passed by reference) is
 145     clobbered.
 146
 147     Also in sub order, no money is adjusted. Once FS::part_pkg
 148     defines a standard method to pass dates to the recur_prog
 149     expression, it should do so.
 150
 151     FS::svc_acct, FS::svc_acct_sm, and FS::svc_domain are loaded via
 152     'use' at compile time, rather than via 'require' in sub { setup,
 153     suspend, unsuspend, cancel } because they use %FS::UID::callback
 154     to load configuration values. Probably need a subroutine which
 155     decides what to do based on whether or not we've fetched the
 156     user yet, rather than a hash. See FS::UID and the TODO.
 157
 158 SEE ALSO
 159     the FS::Record manpage, the FS::cust_main manpage, the
 160     FS::part_pkg manpage, the FS::cust_svc manpage , the FS::pkg_svc
 161     manpage, schema.html from the base documentation
 162
 163 HISTORY
 164     ivan@voicenet.com 97-jul-1 - 21
 165
 166     fixed for new agent->agent_type->type_pkgs in &order
 167     ivan@sisd.com 98-mar-7
 168
 169     pod ivan@sisd.com 98-sep-21
 170
 171     $Log: cust_pkg.txt,v $
 172     Revision 1.3  1999-02-09 09:38:01  ivan
 173     regenerated perl api docs from embedded pod
 174  Revision 1.6 1999/01/25 12:26:12 ivan yet
 175     more mod_perl stuff
 176
 177     Revision 1.5 1999/01/18 21:58:07 ivan esthetic: eq and ne were
 178     used in a few places instead of == and !=
 179
 180     Revision 1.4 1998/12/29 11:59:45 ivan mostly properly OO, some
 181     work still to be done with svc_ stuff
 182
 183     Revision 1.3 1998/11/15 13:01:35 ivan allow pkgpart changing
 184     (for per-customer custom pricing). warn about it in doc
 185
 186     Revision 1.2 1998/11/12 03:42:45 ivan added label method
 187