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         sub insert { my $self = shift;
  61
  62           # custnum might not have have been defined in sub check (for one-shot new
  63           # customers), so check it here instead
  64
  65           my $error = $self->ut_number('custnum');
  66           return $error if $error
  67
  68           return "Unknown customer"
  69             unless qsearchs( 'cust_main', { 'custnum' => $self->custnum } );
  70
  71           $self->SUPER::insert;
  72
  73         }
  74
  75     delete
  76         Currently unimplemented. You don't want to delete billing
  77         items, because there would then be no record the customer
  78         ever purchased the item. Instead, see the cancel method.
  79
  80     replace OLD_RECORD
  81         Replaces the OLD_RECORD with this one in the database. If
  82         there is an error, returns the error, otherwise returns
  83         false.
  84
  85         Currently, custnum, setup, bill, susp, expire, and cancel
  86         may be changed.
  87
  88         Changing pkgpart may have disasterous effects. See the order
  89         subroutine.
  90
  91         setup and bill are normally updated by calling the bill
  92         method of a customer object (see the FS::cust_main manpage).
  93
  94         suspend is normally updated by the suspend and unsuspend
  95         methods.
  96
  97         cancel is normally updated by the cancel method (and also
  98         the order subroutine in some cases).
  99
 100     check
 101         Checks all fields to make sure this is a valid billing item.
 102         If there is an error, returns the error, otherwise returns
 103         false. Called by the insert and replace methods.
 104
 105     cancel
 106         Cancels and removes all services (see the FS::cust_svc
 107         manpage and the FS::part_svc manpage) in this package, then
 108         cancels the package itself (sets the cancel field to now).
 109
 110         If there is an error, returns the error, otherwise returns
 111         false.
 112
 113     suspend
 114         Suspends all services (see the FS::cust_svc manpage and the
 115         FS::part_svc manpage) in this package, then suspends the
 116         package itself (sets the susp field to now).
 117
 118         If there is an error, returns the error, otherwise returns
 119         false.
 120
 121     unsuspend
 122         Unsuspends all services (see the FS::cust_svc manpage and
 123         the FS::part_svc manpage) in this package, then unsuspends
 124         the package itself (clears the susp field).
 125
 126         If there is an error, returns the error, otherwise returns
 127         false.
 128
 129     part_pkg
 130         Returns the definition for this billing item, as an
 131         FS::part_pkg object (see L<FS::part_pkg).
 132
 133     labels
 134         Returns a list of lists, calling the label method for all
 135         services (see the FS::cust_svc manpage) of this billing
 136         item.
 137
 138 SUBROUTINES
 139     order CUSTNUM, PKGPARTS_ARYREF, [ REMOVE_PKGNUMS_ARYREF ]
 140         CUSTNUM is a customer (see the FS::cust_main manpage)
 141
 142         PKGPARTS is a list of pkgparts specifying the the billing
 143         item definitions (see the FS::part_pkg manpage) to order for
 144         this customer. Duplicates are of course permitted.
 145
 146         REMOVE_PKGNUMS is an optional list of pkgnums specifying the
 147         billing items to remove for this customer. The services (see
 148         the FS::cust_svc manpage) are moved to the new billing
 149         items. An error is returned if this is not possible (see the
 150         FS::pkg_svc manpage).
 151
 152 VERSION
 153     $Id: cust_pkg.txt,v 1.4 1999-04-08 13:39:32 ivan Exp $
 154
 155 BUGS
 156     sub order is not OO. Perhaps it should be moved to FS::cust_main
 157     and made so?
 158
 159     In sub order, the @pkgparts array (passed by reference) is
 160     clobbered.
 161
 162     Also in sub order, no money is adjusted. Once FS::part_pkg
 163     defines a standard method to pass dates to the recur_prog
 164     expression, it should do so.
 165
 166     FS::svc_acct, FS::svc_acct_sm, and FS::svc_domain are loaded via
 167     'use' at compile time, rather than via 'require' in sub { setup,
 168     suspend, unsuspend, cancel } because they use %FS::UID::callback
 169     to load configuration values. Probably need a subroutine which
 170     decides what to do based on whether or not we've fetched the
 171     user yet, rather than a hash. See FS::UID and the TODO.
 172
 173 SEE ALSO
 174     the FS::Record manpage, the FS::cust_main manpage, the
 175     FS::part_pkg manpage, the FS::cust_svc manpage , the FS::pkg_svc
 176     manpage, schema.html from the base documentation
 177
 178 HISTORY
 179     ivan@voicenet.com 97-jul-1 - 21
 180
 181     fixed for new agent->agent_type->type_pkgs in &order
 182     ivan@sisd.com 98-mar-7
 183
 184     pod ivan@sisd.com 98-sep-21
 185
 186     $Log: cust_pkg.txt,v $
 187     Revision 1.4  1999-04-08 13:39:32  ivan
 188     convert from pod for 1.2.0 release
 189  Revision 1.9 1999/03/29 01:11:51 ivan use
 190     FS::type_pkgs
 191
 192     Revision 1.8 1999/03/25 13:48:14 ivan allow empty custnum in sub
 193     check (but call that an error in sub insert), for one-screen new
 194     customer entry
 195
 196     Revision 1.7 1999/02/09 09:55:06 ivan invoices show line items
 197     for each service in a package (see the label method of
 198     FS::cust_svc)
 199
 200     Revision 1.6 1999/01/25 12:26:12 ivan yet more mod_perl stuff
 201
 202     Revision 1.5 1999/01/18 21:58:07 ivan esthetic: eq and ne were
 203     used in a few places instead of == and !=
 204
 205     Revision 1.4 1998/12/29 11:59:45 ivan mostly properly OO, some
 206     work still to be done with svc_ stuff
 207
 208     Revision 1.3 1998/11/15 13:01:35 ivan allow pkgpart changing
 209     (for per-customer custom pricing). warn about it in doc
 210
 211     Revision 1.2 1998/11/12 03:42:45 ivan added label method
 212