5 use FS::UID qw( getotaker dbh );
6 use FS::Record qw( qsearch qsearchs );
13 # need to 'use' these instead of 'require' in sub { cancel, suspend, unsuspend,
15 # because they load configuraion by setting FS::UID::callback (see TODO)
21 @ISA = qw( FS::Record );
25 FS::cust_pkg - Object methods for cust_pkg objects
31 $record = new FS::cust_pkg \%hash;
32 $record = new FS::cust_pkg { 'column' => 'value' };
34 $error = $record->insert;
36 $error = $new_record->replace($old_record);
38 $error = $record->delete;
40 $error = $record->check;
42 $error = $record->cancel;
44 $error = $record->suspend;
46 $error = $record->unsuspend;
48 $part_pkg = $record->part_pkg;
50 @labels = $record->labels;
52 $error = FS::cust_pkg::order( $custnum, \@pkgparts );
53 $error = FS::cust_pkg::order( $custnum, \@pkgparts, \@remove_pkgnums ] );
57 An FS::cust_pkg object represents a customer billing item. FS::cust_pkg
58 inherits from FS::Record. The following fields are currently supported:
62 =item pkgnum - primary key (assigned automatically for new billing items)
64 =item custnum - Customer (see L<FS::cust_main>)
66 =item pkgpart - Billing item definition (see L<FS::part_pkg>)
78 =item otaker - order taker (assigned automatically if null, see L<FS::UID>)
80 =item manual_flag - If this field is set to 1, disables the automatic
81 unsuspensiond of this package when using the B<unsuspendauto> config file.
85 Note: setup, bill, susp, expire and cancel are specified as UNIX timestamps;
86 see L<perlfunc/"time">. Also see L<Time::Local> and L<Date::Parse> for
95 Create a new billing item. To add the item to the database, see L<"insert">.
99 sub table { 'cust_pkg'; }
103 Adds this billing item to the database ("Orders" the item). If there is an
104 error, returns the error, otherwise returns false.
111 # custnum might not have have been defined in sub check (for one-shot new
112 # customers), so check it here instead
113 # (is this still necessary with transactions?)
115 my $error = $self->ut_number('custnum');
116 return $error if $error;
118 return "Unknown customer ". $self->custnum unless $self->cust_main;
120 $self->SUPER::insert;
126 This method now works but you probably shouldn't use it.
128 You don't want to delete billing items, because there would then be no record
129 the customer ever purchased the item. Instead, see the cancel method.
134 # return "Can't delete cust_pkg records!";
137 =item replace OLD_RECORD
139 Replaces the OLD_RECORD with this one in the database. If there is an error,
140 returns the error, otherwise returns false.
142 Currently, custnum, setup, bill, susp, expire, and cancel may be changed.
144 Changing pkgpart may have disasterous effects. See the order subroutine.
146 setup and bill are normally updated by calling the bill method of a customer
147 object (see L<FS::cust_main>).
149 suspend is normally updated by the suspend and unsuspend methods.
151 cancel is normally updated by the cancel method (and also the order subroutine
157 my( $new, $old ) = ( shift, shift );
159 #return "Can't (yet?) change pkgpart!" if $old->pkgpart != $new->pkgpart;
160 return "Can't change otaker!" if $old->otaker ne $new->otaker;
163 #return "Can't change setup once it exists!"
164 # if $old->getfield('setup') &&
165 # $old->getfield('setup') != $new->getfield('setup');
167 #some logic for bill, susp, cancel?
169 $new->SUPER::replace($old);
174 Checks all fields to make sure this is a valid billing item. If there is an
175 error, returns the error, otherwise returns false. Called by the insert and
184 $self->ut_numbern('pkgnum')
185 || $self->ut_numbern('custnum')
186 || $self->ut_number('pkgpart')
187 || $self->ut_numbern('setup')
188 || $self->ut_numbern('bill')
189 || $self->ut_numbern('susp')
190 || $self->ut_numbern('cancel')
192 return $error if $error;
194 if ( $self->custnum ) {
195 return "Unknown customer ". $self->custnum unless $self->cust_main;
198 return "Unknown pkgpart"
199 unless qsearchs( 'part_pkg', { 'pkgpart' => $self->pkgpart } );
201 $self->otaker(getotaker) unless $self->otaker;
202 $self->otaker =~ /^(\w{0,16})$/ or return "Illegal otaker";
205 if ( $self->dbdef_table->column('manual_flag') ) {
206 $self->manual_flag =~ /^([01]?)$/ or return "Illegal manual_flag";
207 $self->manual_flag($1);
215 Cancels and removes all services (see L<FS::cust_svc> and L<FS::part_svc>)
216 in this package, then cancels the package itself (sets the cancel field to
219 If there is an error, returns the error, otherwise returns false.
227 local $SIG{HUP} = 'IGNORE';
228 local $SIG{INT} = 'IGNORE';
229 local $SIG{QUIT} = 'IGNORE';
230 local $SIG{TERM} = 'IGNORE';
231 local $SIG{TSTP} = 'IGNORE';
232 local $SIG{PIPE} = 'IGNORE';
234 my $oldAutoCommit = $FS::UID::AutoCommit;
235 local $FS::UID::AutoCommit = 0;
238 foreach my $cust_svc (
239 qsearch( 'cust_svc', { 'pkgnum' => $self->pkgnum } )
241 my $part_svc = qsearchs( 'part_svc', { 'svcpart' => $cust_svc->svcpart } );
243 $part_svc->svcdb =~ /^([\w\-]+)$/ or do {
244 $dbh->rollback if $oldAutoCommit;
245 return "Illegal svcdb value in part_svc!";
248 require "FS/$svcdb.pm";
250 my $svc = qsearchs( $svcdb, { 'svcnum' => $cust_svc->svcnum } );
252 $error = $svc->cancel;
254 $dbh->rollback if $oldAutoCommit;
255 return "Error cancelling service: $error"
257 $error = $svc->delete;
259 $dbh->rollback if $oldAutoCommit;
260 return "Error deleting service: $error";
264 $error = $cust_svc->delete;
266 $dbh->rollback if $oldAutoCommit;
267 return "Error deleting cust_svc: $error";
272 unless ( $self->getfield('cancel') ) {
273 my %hash = $self->hash;
274 $hash{'cancel'} = time;
275 my $new = new FS::cust_pkg ( \%hash );
276 $error = $new->replace($self);
278 $dbh->rollback if $oldAutoCommit;
283 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
290 Suspends all services (see L<FS::cust_svc> and L<FS::part_svc>) in this
291 package, then suspends the package itself (sets the susp field to now).
293 If there is an error, returns the error, otherwise returns false.
301 local $SIG{HUP} = 'IGNORE';
302 local $SIG{INT} = 'IGNORE';
303 local $SIG{QUIT} = 'IGNORE';
304 local $SIG{TERM} = 'IGNORE';
305 local $SIG{TSTP} = 'IGNORE';
306 local $SIG{PIPE} = 'IGNORE';
308 my $oldAutoCommit = $FS::UID::AutoCommit;
309 local $FS::UID::AutoCommit = 0;
312 foreach my $cust_svc (
313 qsearch( 'cust_svc', { 'pkgnum' => $self->pkgnum } )
315 my $part_svc = qsearchs( 'part_svc', { 'svcpart' => $cust_svc->svcpart } );
317 $part_svc->svcdb =~ /^([\w\-]+)$/ or do {
318 $dbh->rollback if $oldAutoCommit;
319 return "Illegal svcdb value in part_svc!";
322 require "FS/$svcdb.pm";
324 my $svc = qsearchs( $svcdb, { 'svcnum' => $cust_svc->svcnum } );
326 $error = $svc->suspend;
328 $dbh->rollback if $oldAutoCommit;
335 unless ( $self->getfield('susp') ) {
336 my %hash = $self->hash;
337 $hash{'susp'} = time;
338 my $new = new FS::cust_pkg ( \%hash );
339 $error = $new->replace($self);
341 $dbh->rollback if $oldAutoCommit;
346 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
353 Unsuspends all services (see L<FS::cust_svc> and L<FS::part_svc>) in this
354 package, then unsuspends the package itself (clears the susp field).
356 If there is an error, returns the error, otherwise returns false.
364 local $SIG{HUP} = 'IGNORE';
365 local $SIG{INT} = 'IGNORE';
366 local $SIG{QUIT} = 'IGNORE';
367 local $SIG{TERM} = 'IGNORE';
368 local $SIG{TSTP} = 'IGNORE';
369 local $SIG{PIPE} = 'IGNORE';
371 my $oldAutoCommit = $FS::UID::AutoCommit;
372 local $FS::UID::AutoCommit = 0;
375 foreach my $cust_svc (
376 qsearch('cust_svc',{'pkgnum'=> $self->pkgnum } )
378 my $part_svc = qsearchs( 'part_svc', { 'svcpart' => $cust_svc->svcpart } );
380 $part_svc->svcdb =~ /^([\w\-]+)$/ or do {
381 $dbh->rollback if $oldAutoCommit;
382 return "Illegal svcdb value in part_svc!";
385 require "FS/$svcdb.pm";
387 my $svc = qsearchs( $svcdb, { 'svcnum' => $cust_svc->svcnum } );
389 $error = $svc->unsuspend;
391 $dbh->rollback if $oldAutoCommit;
398 unless ( ! $self->getfield('susp') ) {
399 my %hash = $self->hash;
401 my $new = new FS::cust_pkg ( \%hash );
402 $error = $new->replace($self);
404 $dbh->rollback if $oldAutoCommit;
409 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
416 Returns the definition for this billing item, as an FS::part_pkg object (see
423 qsearchs( 'part_pkg', { 'pkgpart' => $self->pkgpart } );
428 Returns a list of lists, calling the label method for all services
429 (see L<FS::cust_svc>) of this billing item.
435 map { [ $_->label ] } qsearch ( 'cust_svc', { 'pkgnum' => $self->pkgnum } );
440 Returns the parent customer object (see L<FS::cust_main>).
446 qsearchs( 'cust_main', { 'custnum' => $self->custnum } );
455 =item order CUSTNUM, PKGPARTS_ARYREF, [ REMOVE_PKGNUMS_ARYREF [ RETURN_CUST_PKG_ARRAYREF ] ]
457 CUSTNUM is a customer (see L<FS::cust_main>)
459 PKGPARTS is a list of pkgparts specifying the the billing item definitions (see
460 L<FS::part_pkg>) to order for this customer. Duplicates are of course
463 REMOVE_PKGNUMS is an optional list of pkgnums specifying the billing items to
464 remove for this customer. The services (see L<FS::cust_svc>) are moved to the
465 new billing items. An error is returned if this is not possible (see
466 L<FS::pkg_svc>). An empty arrayref is equivalent to not specifying this
469 RETURN_CUST_PKG_ARRAYREF, if specified, will be filled in with the
470 newly-created cust_pkg objects.
475 my($custnum, $pkgparts, $remove_pkgnums, $return_cust_pkg) = @_;
476 $remove_pkgnums = [] unless defined($remove_pkgnums);
478 my $oldAutoCommit = $FS::UID::AutoCommit;
479 local $FS::UID::AutoCommit = 0;
483 # $part_pkg{$pkgpart} is true iff $custnum may purchase $pkgpart
485 my($cust_main)=qsearchs('cust_main',{'custnum'=>$custnum});
486 my($agent)=qsearchs('agent',{'agentnum'=> $cust_main->agentnum });
487 my %part_pkg = %{ $agent->pkgpart_hashref };
491 # for those packages being removed:
492 #@{ $svcnum{$svcpart} } goes from a svcpart to a list of FS::Record
493 # objects (table eq 'cust_svc')
495 foreach $pkgnum ( @{$remove_pkgnums} ) {
497 foreach $cust_svc (qsearch('cust_svc',{'pkgnum'=>$pkgnum})) {
498 push @{ $svcnum{$cust_svc->getfield('svcpart')} }, $cust_svc;
504 # for those packages the customer is purchasing:
505 # @{$pkgparts} is a list of said packages, by pkgpart
506 # @cust_svc is a corresponding list of lists of FS::Record objects
508 foreach $pkgpart ( @{$pkgparts} ) {
509 unless ( $part_pkg{$pkgpart} ) {
510 $dbh->rollback if $oldAutoCommit;
511 return "Customer not permitted to purchase pkgpart $pkgpart!";
515 ( $svcnum{$_} && @{ $svcnum{$_} } ) ? shift @{ $svcnum{$_} } : ();
516 } map { $_->svcpart } qsearch('pkg_svc', { 'pkgpart' => $pkgpart })
520 #check for leftover services
521 foreach (keys %svcnum) {
522 next unless @{ $svcnum{$_} };
523 $dbh->rollback if $oldAutoCommit;
524 return "Leftover services, svcpart $_: svcnum ".
525 join(', ', map { $_->svcnum } @{ $svcnum{$_} } );
528 #no leftover services, let's make changes.
530 local $SIG{HUP} = 'IGNORE';
531 local $SIG{INT} = 'IGNORE';
532 local $SIG{QUIT} = 'IGNORE';
533 local $SIG{TERM} = 'IGNORE';
534 local $SIG{TSTP} = 'IGNORE';
535 local $SIG{PIPE} = 'IGNORE';
537 #first cancel old packages
539 foreach $pkgnum ( @{$remove_pkgnums} ) {
540 my($old) = qsearchs('cust_pkg',{'pkgnum'=>$pkgnum});
542 $dbh->rollback if $oldAutoCommit;
543 return "Package $pkgnum not found to remove!";
545 my(%hash) = $old->hash;
546 $hash{'cancel'}=time;
547 my($new) = new FS::cust_pkg ( \%hash );
548 my($error)=$new->replace($old);
550 $dbh->rollback if $oldAutoCommit;
551 return "Couldn't update package $pkgnum: $error";
555 #now add new packages, changing cust_svc records if necessary
557 while ($pkgpart=shift @{$pkgparts} ) {
559 my $new = new FS::cust_pkg {
560 'custnum' => $custnum,
561 'pkgpart' => $pkgpart,
563 my $error = $new->insert;
565 $dbh->rollback if $oldAutoCommit;
566 return "Couldn't insert new cust_pkg record: $error";
568 push @{$return_cust_pkg}, $new if $return_cust_pkg;
569 my $pkgnum = $new->pkgnum;
571 foreach my $cust_svc ( @{ shift @cust_svc } ) {
572 my(%hash) = $cust_svc->hash;
573 $hash{'pkgnum'}=$pkgnum;
574 my($new) = new FS::cust_svc ( \%hash );
575 my($error)=$new->replace($cust_svc);
577 $dbh->rollback if $oldAutoCommit;
578 return "Couldn't link old service to new package: $error";
583 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
592 $Id: cust_pkg.pm,v 1.12 2001-10-22 08:29:42 ivan Exp $
596 sub order is not OO. Perhaps it should be moved to FS::cust_main and made so?
598 In sub order, the @pkgparts array (passed by reference) is clobbered.
600 Also in sub order, no money is adjusted. Once FS::part_pkg defines a standard
601 method to pass dates to the recur_prog expression, it should do so.
603 FS::svc_acct, FS::svc_acct_sm, and FS::svc_domain are loaded via 'use' at
604 compile time, rather than via 'require' in sub { setup, suspend, unsuspend,
605 cancel } because they use %FS::UID::callback to load configuration values.
606 Probably need a subroutine which decides what to do based on whether or not
607 we've fetched the user yet, rather than a hash. See FS::UID and the TODO.
609 Now that things are transactional should the check in the insert method be
614 L<FS::Record>, L<FS::cust_main>, L<FS::part_pkg>, L<FS::cust_svc>,
615 L<FS::pkg_svc>, schema.html from the base documentation